Частые ошибки конфигурации

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

Некорректная инициализация библиотеки

Ошибка: подключение Axe-core без правильной загрузки скрипта или объекта axe.

  • В средах Node.js важно импортировать библиотеку через require или import:
const axe = require('axe-core');

или

import axe from 'axe-core';
  • В браузерной среде требуется убедиться, что скрипт загружен перед вызовом axe.run(). Частая проблема — запуск проверки до полной загрузки DOM.
document.addEventListener('DOMContentLoaded', () => {
    axe.run(document, {}, (err, results) => {
        if (err) throw err;
        console.log(results.violations);
    });
});

Последствия ошибки: вызовы к axe.run() до полной инициализации DOM приведут к отсутствию результатов или к исключениям.

Неправильная конфигурация опций

Библиотека позволяет настраивать правила через объект axe.run(context, options). Распространённые ошибки:

  1. Игнорирование контекста Использование пустого контекста может пропускать специфические элементы страницы, особенно динамически загружаемые:
// Ошибочно
axe.run({}, { runOnly: ['wcag2aa'] });

Лучше явно указывать область проверки:

axe.run(document.body, { runOnly: ['wcag2aa'] });
  1. Неправильное указание правил Ошибка синтаксиса или опечатка в имени правила приводит к игнорированию всех правил:
// Некорректно
axe.run(document, { rules: { 'color-contrst': { enabled: true } } });

Правильный вариант:

axe.run(document, { rules: { 'color-contrast': { enabled: true } } });
  1. Конфликт опций runOnly и rules Если одновременно задаются конкретные правила через rules и фильтруется runOnly, можно получить пустой набор проверок:
axe.run(document, { runOnly: ['wcag2aa'], rules: { 'color-contrast': { enabled: false } } });
// Результат: 'color-contrast' не проверяется

Игнорирование динамического контента

Axe-core анализирует текущую структуру DOM. Ошибкой является запуск проверки до того, как динамический контент, загружаемый через JavaScript, будет вставлен в документ.

// Динамический контент
fetch('/data')
  .then(res => res.text())
  .then(html => {
    document.body.innerHTML += html;
    axe.run(document, {}, callback); // правильный момент запуска
  });

Если запуск произойдёт до вставки данных, нарушения доступности останутся незамеченными.

Неправильное использование результатов

Частая ошибка — игнорирование структуры объекта results. Axe-core возвращает массивы violations, passes, incomplete и inapplicable. Часто разработчики смотрят только на violations и не анализируют incomplete, что может скрывать потенциальные проблемы.

axe.run(document, {}, (err, results) => {
    console.log(results.violations); // видим только часть проблем
    console.log(results.incomplete); // скрытые проблемы с ограниченным контекстом
});

Неправильная интеграция с тестовыми фреймворками

При интеграции Axe-core с Jest, Mocha или Cypress распространены ошибки:

  • Асинхронность: отсутствие await или колбэка может привести к тому, что тест завершится раньше выполнения проверки.
// Ошибочно в Jest
test('доступность страницы', () => {
    axe.run(document).then(results => {
        expect(results.violations.length).toBe(0);
    });
});
// Тест может завершиться до вызова then()

Правильный способ:

test('доступность страницы', async () => {
    const results = await axe.run(document);
    expect(results.violations.length).toBe(0);
});
  • Игнорирование контекста внутри фреймов: элементы внутри <iframe> не проверяются без явного указания контекста и iframe опций.

Использование устаревших версий библиотеки

Старая версия Axe-core может не поддерживать последние правила WCAG или иметь баги с современными элементами HTML5. Это приводит к ложному ощущению безопасности страницы. Рекомендуется использовать последнюю стабильную версию и регулярно обновлять зависимости.

Чрезмерная фильтрация правил

Иногда разработчики отключают слишком много правил или ограничивают проверку отдельными категориями, что приводит к поверхностному тестированию:

axe.run(document, { runOnly: ['wcag2aa'], rules: { 'image-alt': { enabled: false } } });

В этом случае критическая проблема доступности (например, отсутствие описания для изображений) останется незамеченной.

Отсутствие логирования и структурированного вывода

Ошибка — вывод results.violations через console.log без форматирования. Это усложняет анализ и автоматизацию. Более корректно использовать функции форматирования или интеграцию с отчетными инструментами:

import { report } from 'axe-reports';

axe.run(document).then(results => {
    report(results, { format: 'html', outputFile: 'accessibility-report.html' });
});

Такой подход позволяет отслеживать нарушения, их детали и контекст для последующего исправления.

Вывод

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

Оглавление