Анализ violations

Библиотека Axe-core предназначена для автоматического выявления проблем доступности веб-приложений. Центральным объектом при выполнении проверок является массив violations, который содержит сведения о всех обнаруженных нарушениях стандартов доступности.

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

  • violations — массив объектов с информацией о найденных нарушениях.
  • incomplete — массив объектов, где результаты проверки не являются окончательными (например, из-за динамического контента).
  • passes — массив объектов, которые прошли проверку без нарушений.
  • inapplicable — проверки, которые не применяются к текущему DOM.

Структура объекта violation

Каждый элемент массива violations имеет строго определённую структуру:

{
  id: "color-contrast",
  impact: "serious",
  description: "Ensures the contrast between foreground and background colors meets WCAG 2 AA contrast ratio thresholds",
  help: "Elements must have sufficient color contrast",
  helpUrl: "https://dequeuniversity.com/rules/axe/4.8/color-contrast?application=axeAPI",
  nodes: [
    {
      html: "<p style='color:#777;'>Some text</p>",
      target: ["body > div > p:nth-child(1)"],
      failureSummary: "This element has insufficient color contrast of 2.5:1",
      any: [...],
      all: [...],
      none: [...]
    }
  ]
}

Ключевые поля:

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

Каждый элемент nodes содержит:

  • html — строка с HTML-кодом элемента, вызвавшего нарушение.
  • target — CSS-селектор или путь к элементу в DOM.
  • failureSummary — текстовое описание конкретного нарушения для этого элемента.
  • any, all, none — массивы результатов проверки подусловий правила. Они дают детальную информацию о том, какие именно условия правила не выполнены.

Работа с массивом violations

Обработка violations обычно выполняется с использованием итераций по массиву и его подструктурам. Пример получения всех HTML-элементов с нарушениями:

axe.run(document).then(results => {
  results.violations.forEach(v => {
    console.log(`Нарушение: ${v.id}, уровень: ${v.impact}`);
    v.nodes.forEach(node => {
      console.log(`Элемент: ${node.html}`);
      console.log(`Путь в DOM: ${node.target.join(", ")}`);
      console.log(`Описание: ${node.failureSummary}`);
    });
  });
});

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

Категоризация нарушений

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

  • minor — мелкие проблемы, которые незначительно влияют на доступность.
  • moderate — средние нарушения, требующие внимания.
  • serious — серьёзные проблемы, которые могут затруднять использование сайта для определённых категорий пользователей.
  • critical — критические ошибки, которые делают элементы полностью недоступными.

Эта классификация полезна при автоматическом формировании отчетов и приоритизации исправлений.

Подробный разбор поля nodes

Поле nodes предоставляет детальную информацию о каждом элементе, вызвавшем нарушение:

  • html помогает идентифицировать проблемный элемент без необходимости поиска в DOM.
  • target позволяет привязать нарушение к конкретному селектору CSS, что удобно для автоматизации исправлений.
  • failureSummary содержит готовый текст для отчёта или логирования.
  • any, all, none дают возможность понять, какие подусловия правила были соблюдены или нарушены, что особенно важно для сложных правил WCAG.

Автоматизация отчётности

На основе массива violations создаются отчёты для команд разработки и QA. Обычно формируют таблицы или JSON-структуры, включающие:

  • Тип нарушения (id, impact).
  • Ссылку на документацию (helpUrl).
  • Локализацию нарушений в DOM (target).
  • Подробное описание (failureSummary).

Пример фильтрации критических и серьёзных нарушений для отчёта:

const criticalViolations = results.violations.filter(v => 
  v.impact === 'critical' || v.impact === 'serious'
);

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

Применение в тестах и CI/CD

Использование массива violations в автоматизированных тестах позволяет:

  • Проверять доступность на каждой сборке.
  • Заводить баги автоматически по обнаруженным критическим нарушениям.
  • Генерировать отчёты в формате JSON или HTML для QA и разработчиков.

Пример интеграции с Jest:

test('Страница должна быть доступной', async () => {
  const results = await axe.run(document.body);
  expect(results.violations.length).toBe(0);
});

Если violations содержит хотя бы один элемент, тест будет провален, что обеспечивает контроль качества доступности на уровне CI/CD.

Итоговая роль массива violations

Массив violations является центральным инструментом анализа доступности:

  • Он предоставляет полную информацию о проблемах.
  • Позволяет автоматизировать отчётность и интеграцию в тестовые системы.
  • Дает возможность классифицировать нарушения по критичности и подчинённым условиям.

Глубокий разбор структуры и полей каждого violation обеспечивает точную локализацию проблем и эффективное исправление кода без лишних догадок.

Оглавление