Интеграция в существующий проект

Для интеграции Axe-core в существующий проект на JavaScript необходимо сначала установить пакет через npm или yarn:

npm install axe-core --save-dev

или

yarn add axe-core --dev

После установки библиотеку можно подключить в коде:

import axe from 'axe-core';

Для старых проектов с использованием CommonJS:

const axe = require('axe-core');

В браузерных проектах возможно подключение через CDN:

<script src="https://cdnjs.cloudflare.com/ajax/libs/axe-core/4.6.3/axe.min.js"></script>

Инициализация и базовая проверка

Для запуска анализа доступности используется метод run, который принимает DOM-узел или документ целиком. В простейшем случае проверка выглядит так:

axe.run(document, (err, results) => {
    if (err) throw err;
    console.log(results.violations);
});

Ключевые моменты:

  • document — корневой узел, с которого начинается сканирование. Можно передать любой элемент DOM.
  • results.violations — массив объектов, описывающих найденные нарушения.
  • err — ошибка выполнения, обычно связана с некорректной структурой DOM.

Настройка правил и контекста

Библиотека позволяет включать или отключать отдельные правила и ограничивать область проверки. Например:

axe.run(document.getElementById('main-content'), {
    runOnly: {
        type: 'tag',
        values: ['wcag2a', 'wcag2aa']
    },
    rules: {
        'color-contrast': { enabled: false },
        'image-alt': { enabled: true }
    }
}, (err, results) => {
    console.log(results.violations);
});
  • runOnly позволяет выбрать набор правил по тегам или ID.
  • rules — настройка каждого конкретного правила: включение/отключение и дополнительные параметры.

Асинхронная работа и промисы

Начиная с версии 3, Axe-core поддерживает промисы, что удобно для интеграции с современными фреймворками:

axe.run(document).then(results => {
    console.log(results.violations);
}).catch(err => {
    console.error(err);
});

Это позволяет использовать async/await:

async function checkAccessibility() {
    try {
        const results = await axe.run(document);
        console.log(results.violations);
    } catch (err) {
        console.error(err);
    }
}

Интеграция с тестовыми фреймворками

Cypress

Для автоматизированного тестирования можно использовать Axe-core вместе с Cypress:

import 'cypress-axe';

describe('Accessibility tests', () => {
    it('Main page should be accessible', () => {
        cy.visit('/');
        cy.injectAxe();
        cy.checkA11y(null, {
            runOnly: ['wcag2aa']
        });
    });
});
  • cy.injectAxe() — внедряет библиотеку в контекст браузера.
  • cy.checkA11y() — запускает проверку доступности и автоматически выводит отчёт в консоль.

Jest + React Testing Library

Для компонентов React возможна интеграция через Jest:

import { render } from '@testing-library/react';
import { axe, toHaveNoViolations } from 'jest-axe';
expect.extend(toHaveNoViolations);

test('Button component should have no accessibility violations', async () => {
    const { container } = render(<Button label="Click me" />);
    const results = await axe(container);
    expect(results).toHaveNoViolations();
});
  • toHaveNoViolations позволяет прямо в тесте проверять отсутствие нарушений.
  • Такой подход подходит для unit-тестов компонентов и позволяет интегрировать доступность в CI/CD.

Кастомизация отчетов

Axe-core возвращает объект results с массивами violations, passes, incomplete и inapplicable. Каждый элемент содержит:

  • id — идентификатор правила.
  • impact — уровень критичности (critical, serious, moderate, minor).
  • description — текстовое описание проблемы.
  • helpUrl — ссылка на документацию.
  • nodes — список DOM-узлов, на которых найдено нарушение, с указанием селекторов и HTML-контента.

Для генерации собственного отчёта можно использовать:

const report = results.violations.map(v => ({
    rule: v.id,
    impact: v.impact,
    nodes: v.nodes.map(n => n.target)
}));
console.table(report);

Интеграция в существующие сборки

  • В Webpack можно подключать Axe-core как отдельный модуль в development-сборку для автоматического анализа при запуске npm start.
  • В Next.js или Nuxt.js анализ доступности можно выполнять на этапе getStaticProps или в useEffect для динамических страниц.
  • Для крупных SPA рекомендуется запускать проверки только на необходимых компонентах, чтобы минимизировать нагрузку на браузер.

Практические рекомендации

  • Использовать runOnly для ограничения объёма проверки на больших страницах.
  • Включать Axe-core в CI/CD для непрерывного контроля доступности.
  • Создавать кастомные правила при необходимости, используя API Axe-core для расширения стандартного набора.
  • Обрабатывать результаты асинхронно, чтобы не блокировать рендеринг страницы.
  • Документировать найденные нарушения с указанием impact и рекомендаций по исправлению.

Интеграция Axe-core позволяет превратить доступность из отдельного этапа проверки в непрерывный процесс разработки, повышая качество интерфейсов и соответствие стандартам WCAG.

Оглавление