Анализ целой страницы

Для начала работы с библиотекой Axe-core необходимо её установить. В среде Node.js это делается через npm:

npm install axe-core

Для браузерного окружения можно подключить скрипт напрямую:

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

После подключения библиотека доступна как глобальный объект axe.

Инициализация анализа

Анализ всей страницы начинается с вызова метода axe.run(). Он принимает объект с конфигурацией и возвращает промис с результатами:

axe.run(document, {
    runOnly: ['wcag2a', 'wcag2aa'],
    reporter: 'v2'
}).then(results => {
    console.log(results.violations);
});

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

  • runOnly — фильтрует правила, которые будут применяться (например, уровни WCAG).
  • reporter — определяет формат вывода (могут быть v1, v2, v3 или пользовательский).

Если аргумент document опущен, библиотека проанализирует весь текущий DOM по умолчанию.

Структура результата

Результаты анализа возвращаются объектом, содержащим несколько массивов:

  • violations — ошибки доступности, которые требуют исправления.
  • passes — элементы, прошедшие проверку.
  • incomplete — элементы, для которых проверка не может быть завершена.
  • inapplicable — правила, которые не применимы к текущему DOM.

Каждый объект из violations содержит поля:

  • id — идентификатор правила.
  • impact — степень влияния (minor, moderate, serious, critical).
  • description — текстовое описание проблемы.
  • help — краткое руководство по исправлению.
  • nodes — массив DOM-элементов, на которых обнаружена ошибка.

Пример объекта nodes:

{
  "html": "<button>Click me</button>",
  "target": ["button"],
  "failureSummary": "Button element has no accessible name"
}

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

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

axe.configure({
    rules: [
        { id: 'color-contrast', enabled: true },
        { id: 'label', enabled: false }
    ]
});
  • id — идентификатор правила, совпадает с violation.id.
  • enabled — включает или отключает проверку.

Можно создавать собственные правила, передавая их в axe.registerRule() с описанием, функцией проверки и уровнем влияния.

Асинхронный анализ и обработка результатов

axe.run() возвращает промис, что позволяет использовать как then/catch, так и async/await:

async function analyzePage() {
    const results = await axe.run();
    results.violations.forEach(v => {
        console.log(v.id, v.impact, v.nodes.length);
    });
}
analyzePage();

Важно обрабатывать ошибки промиса, так как при динамическом DOM возможны исключения.

Интеграция с тестами

Для автоматизации анализа доступности часто используют тестовые фреймворки, например Jest или Mocha. Пример с Jest:

const { configureAxe, toHaveNoViolations } = require('jest-axe');
expect.extend(toHaveNoViolations);

test('Главная страница доступна', async () => {
    const results = await configureAxe(axe).run(document.body);
    expect(results).toHaveNoViolations();
});

Такой подход позволяет включить проверку доступности в процесс CI/CD.

Фильтрация и выборка элементов

Для анализа не всей страницы, а только её части, можно передавать селекторы или элементы DOM:

const mainContent = document.querySelector('#main');
axe.run(mainContent).then(results => console.log(results.violations));

Это ускоряет проверку и позволяет сосредоточиться на критических областях.

Дополнительные возможности

  1. Настройка отчетов — можно формировать JSON, HTML или текстовые отчеты для аналитики.
  2. Локализация — поддержка сообщений на разных языках через кастомные локализации.
  3. Интеграция с CI/CD — автоматический анализ при деплое или коммите.
  4. Динамический контент — библиотека способна проверять элементы, созданные через JavaScript, что важно для SPA.

Оптимизация работы с DOM

  • Анализ больших страниц может быть ресурсоёмким. Рекомендуется ограничивать область анализа или использовать runOnly для конкретных правил.
  • Для элементов с одинаковой структурой можно использовать селекторы группами, чтобы сократить количество проверок.

Отображение результатов пользователю

Для визуальной диагностики можно подсвечивать элементы с проблемами:

results.violations.forEach(v => {
    v.nodes.forEach(node => {
        const el = document.querySelector(node.target[0]);
        if(el) el.style.border = '2px solid red';
    });
});

Это упрощает идентификацию проблем на странице и ускоряет исправление.

Совместная работа с другими библиотеками

  • React Testing Library: интеграция через axe-core/react для проверки компонентов.
  • Cypress: плагин cypress-axe позволяет проверять страницы в автоматических e2e-тестах.
  • Playwright / Puppeteer: можно запускать анализ в headless-браузере для тестирования всех страниц сайта.

Практические советы

  • Сначала подключать библиотеку в дев-окружении, чтобы минимизировать влияние на производительность.
  • Использовать runOnly для частых проверок и полный набор правил только перед релизом.
  • Проверять динамические модальные окна и элементы, создаваемые через JS, отдельно.
  • Отслеживать impact и исправлять сначала критические ошибки (critical), затем serious, и так далее.

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

Оглавление