Создание собственных правил

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

Структура пользовательского правила

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

const customRule = {
  id: 'custom-rule-id',
  selector: 'css-selector',
  any: [],
  all: [],
  none: [],
  enabled: true,
  tags: ['tag1', 'tag2'],
  description: 'Краткое описание правила',
  help: 'Подробное объяснение, почему правило важно',
  helpUrl: 'https://example.com/documentation',
  evaluate: (node, options) => {
    // Логика проверки возвращает true/false или объект с result
  }
};

Основные свойства:

  • id – уникальный идентификатор правила, используемый при фильтрации и логировании.
  • selector – CSS-селектор, который определяет, к каким элементам применяется проверка.
  • any, all, none – массивы других правил или условий, влияющих на активацию правила.
  • enabled – булевый флаг, включающий или отключающий правило.
  • tags – набор категорий, например "wcag2a", "wcag2aa", "experimental".
  • description – краткое описание сути проверки.
  • help – детальное объяснение правила и его значения для доступности.
  • helpUrl – ссылка на документацию или ресурсы с дополнительной информацией.
  • evaluate – функция проверки, возвращающая результат теста для каждого выбранного элемента.

Определение логики проверки

Функция evaluate является ядром пользовательского правила. Она получает два параметра:

  1. node – DOM-элемент, к которому применяется правило.
  2. options – объект с дополнительными параметрами, переданными при настройке Axe-core.

Пример проверки на отсутствие пустых ссылок:

const emptyLinkRule = {
  id: 'no-empty-links',
  selector: 'a',
  enabled: true,
  description: 'Ссылки не должны быть пустыми',
  help: 'Пустые ссылки создают проблемы для навигации с помощью экранных читалок',
  evaluate: (node) => {
    const text = node.textContent.trim();
    return text.length > 0 ? null : { message: 'Ссылка пуста', node };
  }
};

Функция возвращает null, если правило выполнено, или объект с информацией об ошибке, если проверка не прошла.

Использование условий any, all и none

Свойства any, all и none позволяют комбинировать правила и условия:

  • any – правило считается нарушенным, если хотя бы одно условие выполнено.
  • all – правило нарушено только при выполнении всех условий.
  • none – правило нарушено, если ни одно условие не выполнено.

Пример:

const complexRule = {
  id: 'image-alt-check',
  selector: 'img',
  all: [
    { id: 'alt-required' },
    { id: 'alt-not-empty' }
  ],
  description: 'Проверка атрибутов alt для изображений'
};

Добавление пользовательских правил в Axe-core

Пользовательские правила регистрируются через метод axe.configure:

import axe from 'axe-core';

axe.configure({
  rules: [emptyLinkRule, complexRule]
});

После конфигурации можно запускать сканирование как обычным способом:

axe.run(document, {}, (err, results) => {
  if (err) throw err;
  console.log(results.violations);
});

Контекстные проверки и DOM traversal

Для сложных правил возможно использование методов DOM API и вспомогательных функций Axe-core:

  • querySelectorAll – для поиска элементов внутри узла.
  • node.getAttribute – для проверки атрибутов.
  • node.tagName – для фильтрации по типу элемента.
  • helpers – встроенные утилиты Axe-core для анализа текста, видимости элемента и ARIA-атрибутов.

Пример проверки видимости элемента:

const visibleElementRule = {
  id: 'visible-elements',
  selector: '*',
  evaluate: (node) => {
    const style = window.getComputedStyle(node);
    const hidden = style.display === 'none' || style.visibility === 'hidden';
    return hidden ? { message: 'Элемент скрыт', node } : null;
  }
};

Теги и соответствие стандартам

Правила могут быть помечены тегами для группировки и фильтрации:

tags: ['wcag2a', 'wcag2aa', 'best-practice', 'experimental']

Использование тегов позволяет:

  • Выбирать только правила определенного уровня доступности.
  • Игнорировать экспериментальные или проектные проверки.
  • Настраивать отчетность по категориям нарушений.

Параметры и опции

Функции evaluate и правила можно настраивать через options, передаваемые при запуске axe.run. Это позволяет делать проверку динамичной:

const maxLengthRule = {
  id: 'input-max-length',
  selector: 'input[type="text"]',
  evaluate: (node, options) => {
    const max = options.maxLength || 50;
    return node.value.length <= max ? null : { message: `Длина превышает ${max}`, node };
  }
};

axe.run(document, { rules: [maxLengthRule], maxLength: 100 });

Совместимость и тестирование

  • Любое пользовательское правило должно быть обратимо совместимо с основными механизмами Axe-core.
  • Перед внедрением рекомендуется тестировать правило на разнообразных страницах и с разными типами контента.
  • Поддержка тегов и структурных свойств позволяет интегрировать пользовательские проверки в существующие CI/CD пайплайны.

Создание собственных правил в Axe-core предоставляет гибкий инструмент для адаптации стандартов доступности под конкретные требования проекта, позволяя выявлять узкоспециализированные проблемы, которые не покрываются стандартными правилами библиотеки.

Оглавление