Работа с passes и incomplete

Библиотека axe-core предназначена для автоматизированной проверки доступности веб-страниц. В её основе лежит система правил, которые анализируют DOM, CSS и ARIA-атрибуты для выявления нарушений стандартов WCAG. Два ключевых состояния проверки — passes и incomplete — играют центральную роль в интерпретации результатов.

  • passes — это правила, которые были проверены и не выявили нарушений. Каждое такое правило считается полностью выполненным на текущем фрагменте DOM.
  • incomplete — это правила, которые не удалось полностью проверить. Причины могут быть различными: ограниченный доступ к DOM-элементам, динамическая загрузка контента, использование нестандартных компонентов или сложности с асинхронной проверкой.

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

Структура объектов результатов

Каждая проверка axe-core возвращает объект с четырьмя основными массивами: violations, passes, incomplete и inapplicable.

{
  violations: [...],
  passes: [...],
  incomplete: [...],
  inapplicable: [...]
}
  • passes и incomplete содержат объекты правил. Каждый объект имеет поля:
{
  id: "rule-id",
  impact: "critical | serious | moderate | minor",
  description: "текстовое описание правила",
  help: "подсказка по исправлению",
  nodes: [
    {
      html: "<button>Click me</button>",
      target: ["#button1"],
      failureSummary: "информация о непрохождении правила",
      all: [...],
      any: [...],
      none: [...]
    }
  ]
}

Ключевое отличие: у элементов в passes.nodes все проверки пройдены, а в incomplete.nodes — проверки частично выполнены или не могут быть завершены.

Причины появления incomplete

  1. Динамический контент: элементы, которые рендерятся после асинхронных запросов или через JavaScript-фреймворки, могут быть недоступны в момент проверки.
  2. Нестандартные виджеты: пользовательские компоненты, реализованные через canvas, SVG или shadow DOM, часто вызывают затруднения.
  3. Сложные ARIA-конструкции: неправильно структурированные роли или состояния элементов.
  4. Ограничения среды: если axe-core запускается в headless-браузере без полной поддержки API браузера, часть правил может оставаться непроверенной.

Обработка passes

Элементы в passes можно использовать для:

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

Пример фильтрации всех пройденных элементов с критическим impact:

const criticalPasses = results.passes.filter(rule => rule.impact === "critical");
criticalPasses.forEach(rule => {
  rule.nodes.forEach(node => console.log(node.target));
});

Обработка incomplete

Элементы в incomplete требуют особого внимания. Их нельзя игнорировать, поскольку они могут скрывать реальные проблемы доступности. Практики работы с ними:

  1. Повторная проверка: запуск axe-core после полной загрузки страницы или завершения всех асинхронных операций.
  2. Локализация проблем: анализ полей all, any, none внутри nodes, чтобы понять, какие условия не выполнены.
  3. Настройка правил: некоторые правила могут быть отключены или изменены через конфигурацию axe-core, чтобы избежать ложных непрохождений.

Пример обработки incomplete:

results.incomplete.forEach(rule => {
  console.log(`Невозможно полностью проверить правило: ${rule.id}`);
  rule.nodes.forEach(node => {
    console.log(`Элемент: ${node.html}`);
    console.log(`Проблемные условия:`, node.any.map(a => a.message));
  });
});

Настройка и оптимизация passes/incomplete

Axe-core позволяет конфигурировать проверку через объект опций:

axe.run(document, {
  runOnly: {
    type: "tag",
    values: ["wcag2a", "wcag2aa"]
  },
  rules: {
    "color-contrast": { enabled: true },
    "aria-roles": { enabled: false }
  }
});
  • runOnly ограничивает проверку нужными тегами или правилами.
  • rules позволяет включать или выключать отдельные правила, что снижает количество incomplete и ускоряет тестирование.

Важные моменты при интеграции

  • Асинхронность: axe-core работает асинхронно. Любая проверка должна быть выполнена после полной загрузки DOM и завершения всех скриптов.
  • Shadow DOM: стандартные правила могут не видеть элементы внутри shadow root. Для этого нужно использовать опцию includeShadowDom: true.
  • Кэширование результатов: для больших страниц рекомендуется сохранять результаты passes и повторно проверять только новые элементы.

Использование passes и incomplete для отчетности

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

  1. Проблемы (violations) — требуют исправления.
  2. Неопределённые (incomplete) — требуют дополнительного анализа.
  3. Прошедшие (passes) — демонстрируют соответствие стандартам.

Это позволяет создать точную карту доступности страницы и эффективно планировать исправления.

Хотите, я могу подготовить отдельный блок с реальными примерами сложных случаев incomplete и способами их устранения на практике?

Оглавление