Сообщения и данные

Библиотека Axe-core предназначена для автоматизированного тестирования доступности веб-приложений. Она анализирует DOM страницы, выявляет нарушения стандартов WCAG (Web Content Accessibility Guidelines) и предоставляет структурированные данные о найденных проблемах.

Для использования Axe-core в JavaScript необходимо подключить библиотеку через пакетный менеджер npm:

npm install axe-core

Или добавить скрипт напрямую на страницу:

<script src="https://cdnjs.cloudflare.com/ajax/libs/axe-core/4.7.2/axe.min.js"></script>

После подключения библиотеки доступен глобальный объект axe, через который осуществляется настройка и запуск проверок.

Инициализация и запуск анализа

Для запуска анализа используется метод axe.run. Он принимает два аргумента:

  1. Цель анализа — элемент DOM, который требуется проверить. По умолчанию это document.
  2. Конфигурация — объект с настройками правил, исключениями и параметрами вывода.

Пример базового запуска:

axe.run(document, {
  runOnly: {
    type: 'tag',
    values: ['wcag2a', 'wcag2aa']
  }
}).then(results => {
  console.log(results);
}).catch(err => {
  console.error(err);
});

Ключевой момент: results содержит полную структуру данных о нарушениях доступности, включая подробные сведения о каждом элементе, где обнаружена проблема.

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

Объект results включает несколько важных полей:

  • violations — массив нарушений, где каждый объект содержит:

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

  • passes — элементы, которые успешно прошли проверку.

  • incomplete — элементы, для которых проверка не была полностью проведена.

  • inapplicable — правила, которые не применяются к текущей структуре страницы.

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

axe.run(document).then(results => {
  results.violations.forEach(v => {
    console.log(`Правило: ${v.id} (${v.impact})`);
    console.log(`Описание: ${v.description}`);
    v.nodes.forEach(node => {
      console.log(`Элемент: ${node.html}`);
    });
  });
});

Конфигурация правил и фильтры

Axe-core позволяет гибко настраивать анализ. Основные возможности:

  • Включение и отключение правил:

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

  • Фильтрация по тегам: Теги группируют правила по WCAG, уровню критичности или типу проверки.

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

  • Контроль области проверки: Проверка может ограничиваться конкретным элементом DOM или селектором.

    const mainContent = document.querySelector('#main');
axe.run(mainContent);

Сообщения и данные о нарушениях

Каждое сообщение о нарушении содержит структурированную информацию, которая позволяет не только увидеть проблему, но и понять контекст:

  • target — CSS-селектор элемента;
  • html — исходный код узла;
  • failureSummary — краткое описание ошибки;
  • any, all, none — группы тестов, которые проверяются в рамках правила, где указано, какие конкретно подправила были нарушены.

Пример вывода для одного элемента:

{
  "id": "image-alt",
  "impact": "serious",
  "description": "Изображение должно иметь альтернативный текст",
  "help": "Добавьте атрибут alt",
  "nodes": [
    {
      "html": "<img src='photo.jpg'>",
      "target": ["img"],
      "failureSummary": "Элемент img не имеет атрибута alt"
    }
  ]
}

Эта структура позволяет интегрировать Axe-core с системами автоматизированного тестирования, строить отчёты и направлять задачи на исправление конкретных элементов.

Интеграция с тестовыми фреймворками

Axe-core легко подключается к популярным инструментам для тестирования интерфейсов:

  • Jest + Puppeteer: для проверки доступности динамических страниц.
  • Cypress: через плагин cypress-axe для интеграции с E2E тестами.
  • Playwright: поддержка через axe-core/playwright для автоматической генерации отчётов.

Пример использования с Jest:

const axe = require('axe-core');
const { JSDOM } = require('jsdom');

test('проверка доступности страницы', async () => {
  const dom = new JSDOM(`<body><img src="logo.png"></body>`);
  const results = await axe.run(dom.window.document);
  expect(results.violations.length).toBe(0);
});

Отчёты и визуализация

Для удобства анализа можно формировать отчёты в формате JSON или HTML. Стандартная структура позволяет интегрировать их с CI/CD, строить графики нарушений и формировать уведомления для команды разработки.

Пример экспорта в JSON:

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

Для HTML-отчётов можно использовать сторонние библиотеки, которые преобразуют массив violations в визуальный формат с подсветкой проблемных элементов.

Практические советы при работе с сообщениями

  • Проверки должны запускаться как на статических страницах, так и на динамическом контенте после рендеринга.
  • Использовать runOnly и rules для ускорения анализа больших приложений.
  • Хранить отчёты в CI/CD для отслеживания регрессий доступности.
  • Для сложных правил анализировать массив nodes и подправила (any, all, none) для точного исправления ошибок.

Структурированность сообщений Axe-core делает библиотеку мощным инструментом для поддержания и улучшения доступности веб-приложений на всех этапах разработки.

Оглавление