Формирование отчетов

Библиотека Axe-core распространяется через npm и CDN. В среде Node.js установка выполняется командой:

npm install axe-core

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

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

После подключения библиотеки объект axe становится доступен в глобальном контексте, что позволяет сразу выполнять анализ доступности.

Базовое использование

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

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

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

  • document — проверка выполняется на всем DOM.
  • runOnly — фильтрация по стандартам доступности.
  • results.violations — массив обнаруженных нарушений с полной структурой.

Структура отчета

Результат работы axe.run() возвращает объект с несколькими основными свойствами:

  • violations — массив нарушений, включающий:

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

  • passes — элементы, которые прошли проверку.

  • incomplete — правила, которые не удалось полностью проверить.

  • inapplicable — правила, не применимые к текущему DOM.

Каждое нарушение содержит детальную информацию о контексте, включая CSS-селекторы и атрибуты проблемных элементов.

Форматы отчетов

Axe-core поддерживает несколько способов представления результатов:

  1. JSON — основной формат для дальнейшей обработки и интеграции с CI/CD.
axe.run().then(results => {
  const jsonReport = JSON.stringify(results, null, 2);
  console.log(jsonReport);
});
  1. HTML — визуальный отчет для просмотра в браузере. Для генерации требуется использовать внешние библиотеки или собственный шаблонизатор, поскольку axe-core напрямую HTML-отчеты не формирует.
  2. Текстовый отчет — удобен для командной строки и логирования:
axe.run().then(results => {
  results.violations.forEach(v => {
    console.log(`${v.impact} | ${v.description} | ${v.helpUrl}`);
  });
});

Настройка отчетов

Конфигурация позволяет адаптировать отчет под конкретные задачи:

  • Фильтрация правил: runOnly или rules для включения/отключения отдельных проверок.
  • Селекторы: include и exclude для ограничения анализа конкретными элементами.
  • Теги стандартов: wcag2a, wcag2aa, wcag21aa и другие.

Пример кастомного запуска:

axe.run(document, {
  rules: {
    'color-contrast': { enabled: true },
    'label': { enabled: false }
  },
  include: [['#main-content']],
  exclude: [['.ads']]
})
.then(results => {
  console.log(results);
});

Интеграция с CI/CD

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

const fs = require('fs');

axe.run(document).then(results => {
  fs.writeFileSync('axe-report.json', JSON.stringify(results, null, 2));
});

Далее этот файл может быть использован для:

  • Генерации HTML-отчета средствами CI/CD.
  • Уведомлений в систему сборки о критических нарушениях.
  • Автоматизированного анализа трендов по доступности.

Визуализация и фильтрация нарушений

Для удобства анализа violations можно группировать:

  • По уровню важности:
const grouped = results.violations.reduce((acc, v) => {
  acc[v.impact] = acc[v.impact] || [];
  acc[v.impact].push(v);
  return acc;
}, {});
  • По типу нарушения — позволяет быстро выявлять самые частые проблемы.
  • По селекторам DOM — помогает разработчикам оперативно локализовать элементы для исправления.

Расширенные возможности

  • Асинхронная обработка: все методы возвращают промисы, что позволяет интегрировать проверки в сложные скрипты без блокировки UI.
  • Настройка контекста: возможность анализировать только определенные фреймы или shadow DOM.
  • Пользовательские правила: axe-core позволяет создавать собственные правила, расширяя базовый набор стандартов.

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

  • Сохранять результаты в формате JSON для последующей обработки.
  • Фильтровать правила, неактуальные для проекта, чтобы снизить шум в отчете.
  • Автоматизировать интеграцию в pipeline, чтобы доступность проверялась на каждом коммите.
  • Использовать группировку по impact для приоритизации исправлений.

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

Оглавление