Метод axe.run

Библиотека Axe-core предназначена для автоматизированного тестирования доступности веб-страниц и компонентов интерфейса. Одним из ключевых элементов библиотеки является метод axe.run, который инициирует анализ DOM и возвращает структурированные результаты с обнаруженными нарушениями стандартов доступности.

Синтаксис метода

axe.run([context], [options], [callback])

  • context (опционально) — определяет область DOM для анализа. Может быть:

    • объект HTMLElement или селектор CSS (например, '#main'),
    • массив элементов DOM,
    • объект с ключами include и exclude для точного указания областей.

  • options (опционально) — объект настроек анализа:

    • runOnly — фильтр правил для выполнения (type: "tag" | "rule", values: []),
    • rules — включение или отключение отдельных правил,
    • reporter — форматирование результатов для конкретных инструментов.

  • callback (опционально) — функция обратного вызова, которая получает два аргумента (error, results).

Также метод axe.run возвращает Promise, что позволяет использовать его с async/await:

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

Настройка контекста анализа

Контекст определяет, какие части страницы будут проверяться. Примеры использования:

// Проверка всей страницы
await axe.run(document);

// Проверка конкретного блока
await axe.run(document.querySelector('#header'));

// Исключение блока из анализа
await axe.run(document, {
  exclude: [['#footer']]
});

Важно помнить, что точное указание контекста может ускорить анализ и снизить количество ложных срабатываний.

Опции анализа

Опции позволяют гибко управлять правилами проверки и структурой отчета.

Пример отключения правил

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

Использование фильтра runOnly

await axe.run(document, {
  runOnly: {
    type: 'tag',
    values: ['wcag2aa']
  }
});

В данном случае будут выполнены только правила, соответствующие стандарту WCAG 2.1 AA.

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

Метод axe.run возвращает объект с несколькими ключевыми полями:

  • violations — массив обнаруженных нарушений доступности. Каждый объект содержит:

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

  • passes — массив успешных проверок.

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

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

Пример обработки результатов:

const results = await axe.run(document);

results.violations.forEach(v => {
  console.log(`Нарушение: ${v.id}`);
  console.log(`Уровень: ${v.impact}`);
  v.nodes.forEach(node => {
    console.log(`Элемент: ${node.html}`);
  });
});

Асинхронное использование с async/await

Метод axe.run хорошо интегрируется с современными подходами:

async function checkAccessibility() {
  try {
    const results = await axe.run(document, {
      runOnly: { type: 'tag', values: ['wcag2a', 'wcag2aa'] }
    });

    if (results.violations.length > 0) {
      console.log('Найдены нарушения доступности:');
      results.violations.forEach(v => console.log(v.help));
    } else {
      console.log('Нарушений не обнаружено');
    }
  } catch (err) {
    console.error('Ошибка при запуске axe:', err);
  }
}

checkAccessibility();

Особенности работы с Node.js и тестовыми фреймворками

Метод axe.run может использоваться не только в браузере, но и в средах тестирования:

  • Cypress: через пакет cypress-axe можно интегрировать axe.run в тестовые сценарии.
  • Jest / Puppeteer: позволяет проверять компоненты на стадии E2E-тестирования, используя page.evaluate(() => axe.run(...)).

Пример с Puppeteer:

await page.evaluate(async () => {
  const results = await axe.run(document);
  window.axeResults = results;
});

Логирование и интеграция с CI/CD

Результаты метода можно сериализовать в JSON для интеграции с системами CI/CD:

const fs = require('fs');

const results = await axe.run(document);
fs.writeFileSync('axe-report.json', JSON.stringify(results, null, 2));

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

Важные рекомендации

  • Точный выбор контекста анализа минимизирует количество ложных срабатываний.
  • Использование runOnly и отключение правил ускоряет проверку на больших страницах.
  • Обработка результатов должна учитывать все поля, особенно nodes, чтобы локализовать проблему и исправить её корректно.
  • Для комплексных приложений рекомендуется интегрировать axe.run в E2E-тесты для постоянного контроля доступности.

Метод axe.run является фундаментальной точкой взаимодействия с библиотекой Axe-core, предоставляя полный контроль над процессом аудита доступности и удобный способ интеграции в автоматизированные рабочие процессы.

Оглавление