Регистрация проверок

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

npm install axe-core --save-dev

После установки библиотеку можно подключить как в Node.js, так и в браузерных тестах:

const axe = require('axe-core');

Для браузерного окружения возможно подключение через CDN:

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

Основные принципы регистрации проверок

В Axe-core проверка доступности реализована через набор правил (rules). Каждое правило проверяет конкретный аспект доступности страницы: цветовую контрастность, наличие альтернативного текста для изображений, корректность структуры заголовков и так далее.

Регистрация новых проверок происходит через метод axe.registerRule(rule). Структура объекта правила строго определена:

const customRule = {
    id: 'my-custom-rule',
    selector: 'button',
    enabled: true,
    any: ['aria-label'],
    all: [],
    none: ['disabled'],
    tags: ['custom', 'accessibility'],
    description: 'Кнопки должны иметь атрибут aria-label',
    help: 'Добавить aria-label к кнопкам для доступности',
    helpUrl: 'https://example.com/accessibility-guidelines',
    evaluate(node) {
        return !node.hasAttribute('aria-label');
    }
};

axe.registerRule(customRule);

Ключевые поля правила:

  • id — уникальный идентификатор проверки.
  • selector — CSS-селектор, к которому применяется проверка.
  • enabled — определяет, будет ли правило активным.
  • any, all, none — массивы условий, которые влияют на срабатывание правила.
  • tags — категории или типы доступности (например, wcag2a, wcag2aa).
  • description — краткое объяснение, что проверяет правило.
  • help — советы по исправлению ошибок.
  • helpUrl — ссылка на документацию или рекомендации.
  • evaluate(node) — функция, возвращающая true, если элемент нарушает правило, и false в противном случае.

Регистрация группы правил

Для удобства можно объединять несколько правил в массив и регистрировать их одновременно:

const rules = [rule1, rule2, rule3];

rules.forEach(rule => axe.registerRule(rule));

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

Расширение существующих правил

Axe-core позволяет модифицировать встроенные правила, например, чтобы изменить условия срабатывания или добавить дополнительные проверки:

const modifiedRule = axe.getRules().find(r => r.id === 'color-contrast');
modifiedRule.evaluate = function(node) {
    // дополнительная логика проверки контрастности
    return originalEvaluate(node) || node.style.color === '#ccc';
};
axe.registerRule(modifiedRule);

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

Использование кастомных правил в тестах

После регистрации правила его можно применять в автоматизированных тестах:

axe.run(document, { runOnly: ['my-custom-rule'] })
    .then(results => {
        if (results.violations.length > 0) {
            results.violations.forEach(v => {
                console.log(`${v.id}: ${v.help}`);
            });
        }
    });

Параметр runOnly позволяет ограничить проверку конкретными правилами, включая кастомные, что ускоряет выполнение тестов и фокусирует внимание на важных аспектах доступности.

Советы по проектированию собственных правил

  1. Использовать уникальные идентификаторы для избежания конфликтов.
  2. Документировать правило через поля description и help.
  3. Применять CSS-селекторы точно, чтобы не охватывать лишние элементы.
  4. Проверять производительность, особенно при больших DOM-структурах.
  5. Следовать стандартам WCAG, чтобы кастомные проверки не противоречили основным правилам доступности.

Работа с контекстом и параметрами

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

const contextualRule = {
    id: 'image-alt-required',
    context: 'main',
    selector: 'img',
    evaluate(node) {
        return !node.alt || node.alt.trim() === '';
    },
    description: 'Изображения внутри main должны иметь alt текст'
};

axe.registerRule(contextualRule);

Поле context позволяет ограничить область проверки, что особенно полезно для больших страниц с различными компонентами.

Логирование и отладка

Для отладки кастомных правил можно использовать встроенные методы Axe-core:

axe.configure({
    reporter: 'v2',
    checks: [{
        id: 'my-custom-rule',
        enabled: true
    }]
});

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

Подробные отчёты содержат информацию о каждом элементе, нарушающем правило, CSS-селектор, рекомендации по исправлению и уровень нарушения (minor, moderate, serious, critical).

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

Оглавление