Уведомления о проблемах

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

Типы уведомлений

Axe-core классифицирует результаты проверки в несколько категорий:

  • Violations (Нарушения) Это критические проблемы, которые точно нарушают требования стандартов доступности, таких как WCAG. Нарушения включают, например, отсутствие текстовых альтернатив для изображений или недостаточный контраст текста и фона.

  • Incomplete (Неполные проверки) Проблемы, которые не могут быть однозначно оценены автоматически. Для их анализа может потребоваться ручная проверка. Пример: оценка адекватности текста альтернативного описания сложной инфографики.

  • Passes (Соответствия) Элементы, которые прошли проверку и полностью соответствуют требованиям доступности.

  • Inapplicable (Неприменимые) Сценарии, к которым данное правило не применимо. Например, проверка атрибута alt у элементов без изображений.

Структура уведомления

Каждое уведомление о проблеме содержит следующие ключевые поля:

  • id – уникальный идентификатор правила, по которому произошло нарушение.

  • impact – уровень критичности: "critical", "serious", "moderate", "minor".

  • description – краткое описание сути нарушения.

  • help – текст рекомендации по исправлению.

  • helpUrl – ссылка на документацию или руководство по исправлению.

  • nodes – массив элементов DOM, на которых обнаружена проблема. Каждый объект в nodes содержит:

    • html – фрагмент исходного HTML-кода элемента.
    • target – селектор или путь к элементу.
    • failureSummary – детальное объяснение причины нарушения.
    • any, all, none – подробные данные о конкретных условиях проверки.

Пример структуры элемента node:

{
  "html": "<img src='logo.png'>",
  "target": ["#header img"],
  "failureSummary": "Элемент img отсутствует текстовая альтернатива",
  "any": [...],
  "all": [...],
  "none": [...]
}

Получение уведомлений

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

import axe from 'axe-core';

axe.run(document, { runOnly: { type: 'tag', values: ['wcag2aa'] } })
    .then(results => {
        console.log(results.violations);
        console.log(results.incomplete);
    })
    .catch(err => {
        console.error(err);
    });
  • Параметр runOnly позволяет ограничить проверку определёнными правилами или тегами.
  • Параметр include/exclude задаёт области DOM для проверки или исключения.

Обработка уведомлений

Для удобного анализа рекомендуется:

  1. Фильтрация по уровню влияния:
const criticalViolations = results.violations.filter(v => v.impact === 'critical');
  1. Группировка по правилам для выявления повторяющихся нарушений:
const grouped = results.violations.reduce((acc, v) => {
    acc[v.id] = acc[v.id] || [];
    acc[v.id].push(...v.nodes);
    return acc;
}, {});
  1. Генерация отчетов в форматах JSON или HTML для интеграции с системами CI/CD.

Настройка уведомлений

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

  • Отключение отдельных правил:
axe.configure({
  rules: [
    { id: 'color-contrast', enabled: false }
  ]
});
  • Изменение уровня важности:
axe.configure({
  rules: [
    { id: 'image-alt', impact: 'critical' }
  ]
});
  • Добавление собственных правил с кастомными проверками DOM:
axe.configure({
  rules: [
    {
      id: 'custom-button-label',
      selector: 'button',
      any: [{ id: 'label-present', evaluate: node => !!node.textContent }]
    }
  ]
});

Автоматизация уведомлений

Для проектов с большим количеством страниц часто используют CI/CD интеграцию:

  • Скрипты на Node.js выполняют axe.run на страницах или компонентах.
  • Отчёты автоматически формируются и загружаются в систему отслеживания багов.
  • Предупреждения о критических нарушениях могут блокировать сборку, предотвращая выпуск недоступных интерфейсов.

Визуализация проблем

Axe-core предоставляет возможность подсвечивать элементы с нарушениями прямо на странице:

axe.run(document).then(results => {
  results.violations.forEach(v => {
    v.nodes.forEach(node => {
      const el = document.querySelector(node.target.join(', '));
      el.style.outline = '3px solid red';
    });
  });
});

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

Взаимодействие с другими инструментами

Axe-core интегрируется с браузерными расширениями и тестовыми фреймворками:

  • Cypress, Jest, Playwright – проверка компонентов и страниц.
  • Chrome DevTools – визуальная диагностика нарушений.
  • CI/CD системы – Jenkins, GitHub Actions, GitLab CI для автоматизированных тестов.

Использование уведомлений позволяет не только выявлять ошибки доступности, но и внедрять процессы контроля качества интерфейсов на всех этапах разработки.

Оглавление