Режим debug

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

Включение режима debug

Режим debug не является отдельной функцией библиотеки, это скорее способ работы с выводом ошибок и дополнительными инструментами для разработчиков. Для его активации используют объект конфигурации при вызове axe.run(). Основные параметры:

axe.run(document, {
  reporter: 'v2', 
  rules: {
    'color-contrast': { enabled: true },
    'image-alt': { enabled: true }
  },
  resultTypes: ['violations', 'incomplete', 'passes', 'inapplicable']
}).then(results => {
  console.log(results);
});

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

  • reporter — формат вывода, режим debug предполагает использование подробного формата (обычно 'v2' или 'v3').
  • resultTypes — список типов результатов, которые возвращаются. Для отладки важно включить все возможные типы, чтобы видеть не только ошибки (violations), но и элементы, которые прошли проверку (passes) и частично проверенные (incomplete).

Детализация ошибок

При работе в режиме debug каждый объект ошибки (violation) содержит расширенную информацию:

  • id — уникальный идентификатор правила.

  • impact — уровень воздействия (critical, serious, moderate, minor).

  • description — краткое описание нарушения.

  • help и helpUrl — рекомендации по исправлению и ссылка на документацию.

  • nodes — массив объектов DOM-узлов, где обнаружено нарушение.

    • html — исходный HTML узла.
    • target — CSS-селектор узла.
    • failureSummary — подробный текст ошибки.

Пример структуры:

{
  "id": "color-contrast",
  "impact": "serious",
  "description": "Цвет текста и фона недостаточно контрастны",
  "help": "Увеличить контраст между текстом и фоном",
  "helpUrl": "https://dequeuniversity.com/rules/axe/4.4/color-contrast",
  "nodes": [
    {
      "html": "<p style='color: #aaa; background: #fff;'>Пример текста</p>",
      "target": ["p"],
      "failureSummary": "Контраст 2.5:1, минимальный рекомендуемый 4.5:1"
    }
  ]
}

Эта информация позволяет быстро локализовать проблему и понять контекст, включая стили и DOM-структуру.

Интеграция с браузерными инструментами

Режим debug особенно полезен при интеграции Axe-core с DevTools:

  1. Axe DevTools для Chrome/Firefox — расширение, которое визуализирует все узлы, вызывающие нарушения.
  2. Собственные консольные логи — вывод console.log(results) с параметром JSON.stringify(results, null, 2) обеспечивает читаемую структуру.
  3. Скриптовый дебаг — вызов axe.run() на отдельных контейнерах или компонентах позволяет отслеживать ошибки на уровне конкретных блоков страницы.

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

  • Фильтрация правил: можно временно отключать или включать определённые проверки для упрощения анализа.

    axe.run(document, {
  rules: {
    'color-contrast': { enabled: false },
    'label': { enabled: true }
  }
});

  • Селективная проверка элементов: режим debug позволяет запускать анализ не на всей странице, а на конкретном DOM-узле.

    const node = document.querySelector('#form');
axe.run(node).then(results => console.log(results));

  • Визуализация нарушений: через nodes[target] можно напрямую подсветить проблемные элементы на странице, что ускоряет исправление ошибок.

  • Анализ динамического контента: для SPA и приложений с динамическим рендерингом axe.run() в режиме debug можно вызывать после изменения DOM, чтобы фиксировать новые нарушения.

Логирование и сохранение результатов

Режим debug часто подразумевает ведение журнала ошибок для последующего анализа:

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

Такой подход позволяет:

  • Архивировать результаты тестирования для отчетов.
  • Сравнивать изменения доступности после правок.
  • Автоматизировать интеграцию с CI/CD для проверки accessibility.

Советы по эффективной отладке

  • Всегда использовать resultTypes: ['violations','passes','incomplete','inapplicable'] для полного контекста.
  • Разделять проверки по компонентам, чтобы легче отслеживать источники ошибок.
  • Сохранять результаты в формате JSON для анализа с внешними инструментами.
  • Использовать helpUrl и failureSummary для получения рекомендаций по исправлению.

Режим debug в Axe-core превращает библиотеку не просто в инструмент выявления ошибок, а в полноценный инструмент диагностики доступности, позволяющий детально анализировать DOM, стили и соответствие стандартам WCAG.

Оглавление