Возвращаемые значения

Библиотека Axe-core предназначена для автоматизации проверки доступности веб-контента (a11y) и предоставляет детализированные отчёты о найденных проблемах. Важным аспектом работы с ней является понимание структуры возвращаемых значений, которые позволяют эффективно интегрировать инструмент в тестовые сценарии и автоматизированные пайплайны.

Возвращаемые значения в Axe-core представляют собой объекты JavaScript, содержащие информацию о результатах анализа. Основной метод, который используется для запуска проверки — это axe.run(). Этот метод возвращает Promise, который при выполнении предоставляет объект с результатами анализа.

axe.run(document).then(results => {
    console.log(results);
});

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

Объект, возвращаемый axe.run(), состоит из нескольких ключевых свойств:

  1. violations – массив объектов, каждый из которых описывает конкретное нарушение правил доступности.
  2. passes – массив объектов с успешными проверками.
  3. incomplete – массив правил, которые не удалось полностью проверить.
  4. inapplicable – массив правил, которые не применимы к текущему документу.

Пример структуры объекта violation

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

  • id – уникальный идентификатор правила (например, color-contrast).
  • impact – уровень влияния нарушения: minor, moderate, serious, critical.
  • description – текстовое описание нарушения.
  • help – краткая подсказка по исправлению.
  • helpUrl – ссылка на официальную документацию по конкретному правилу.
  • nodes – массив объектов, представляющих DOM-элементы, где обнаружено нарушение.
{
  id: "color-contrast",
  impact: "serious",
  description: "Контраст текста и фона недостаточен",
  help: "Увеличить контраст текста и фона",
  helpUrl: "https://dequeuniversity.com/rules/axe/4.4/color-contrast",
  nodes: [
    {
      html: "<button style='color: #ccc; background-color: #fff'>Click me</button>",
      target: ["button"],
      failureSummary: "Контраст ниже рекомендуемого уровня 4.5:1"
    }
  ]
}

Работа с результатами

Для анализа результатов необходимо правильно обходить массивы объектов. Наиболее распространённый подход — фильтрация по impact или id правила:

results.violations
  .filter(v => v.impact === "critical")
  .forEach(v => {
      console.log(v.id, v.help);
  });

Использование поля nodes позволяет точно идентифицировать проблемные элементы и получать их HTML-код или CSS-селекторы для последующей автоматизации исправлений.

Особенности работы с incomplete и inapplicable

  • incomplete включает правила, для которых Axe не смог полностью определить результат, часто из-за ограничений DOM или динамического контента. Поле nodes также присутствует, но может быть пустым.
  • inapplicable показывает правила, которые не применимы к текущей структуре страницы. Это важно для корректного подсчёта процента покрытия тестов.

Асинхронность и обработка ошибок

axe.run() всегда возвращает Promise, что требует использования async/await или .then():

async function testAccessibility() {
    try {
        const results = await axe.run(document);
        console.log(results.violations.length + " нарушений найдено");
    } catch (error) {
        console.error("Ошибка при запуске Axe-core:", error);
    }
}

Возможные ошибки могут быть связаны с отсутствием DOM-элементов, неправильной инициализацией библиотеки или проблемами в конфигурации правил.

Кастомизация возвращаемых данных

Axe-core позволяет ограничивать проверку конкретными правилами и элементами, что влияет на возвращаемый объект:

const options = {
    runOnly: {
        type: "rule",
        values: ["color-contrast", "label"]
    },
    elements: document.querySelectorAll("form, button")
};

const results = await axe.run(document, options);

В результате объект будет содержать только выбранные правила и элементы, что облегчает интеграцию в CI/CD и сокращает объём данных для анализа.

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

  • Все результаты возвращаются в виде объектов с массивами violations, passes, incomplete, inapplicable.
  • nodes внутри violations позволяют получить точное местоположение нарушений в DOM.
  • impact и id помогают фильтровать и приоритизировать исправления.
  • Асинхронная природа axe.run() требует корректной работы с промисами и обработкой ошибок.
  • Настройка runOnly и elements позволяет ограничить возвращаемые данные для оптимизации анализа.

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

Оглавление