Создание кастомных checks

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

Структура кастомного check

Каждый кастомный check в Axe-core состоит из нескольких ключевых компонентов:

  1. ID правила — уникальный идентификатор, используемый для регистрации и последующей ссылки на check.
  2. Описание (description) — краткая формулировка цели проверки, отображаемая в отчетах.
  3. Селекторы (selector) — CSS-селекторы или функции для поиска элементов, к которым будет применяться проверка.
  4. Функция проверки (check function) — ядро проверки, в котором реализуется логика анализа элемента. Функция получает на вход DOM-узел и возвращает объект с результатом проверки.
  5. Сообщения о нарушениях (messages) — текстовые описания проблем и рекомендации по исправлению.
  6. Риск и влияние (impact) — уровень важности нарушения: critical, serious, moderate или minor.

Пример минимальной структуры кастомного check:

axe.core.registerCheck({
  id: 'custom-heading-check',
  description: 'Проверка наличия хотя бы одного <h1> на странице',
  selector: 'h1',
  evaluate: (node) => {
    return node ? { passed: true } : { passed: false, message: 'На странице отсутствует <h1>' };
  },
  impact: 'serious'
});

Селекторы для кастомных правил

Селекторы могут быть строковыми CSS-селекторами или функциями. Строковые селекторы удобны для простых проверок:

selector: 'button[aria-label]'

Функции-селекторы дают полный контроль:

selector: (root) => {
  return Array.from(root.querySelectorAll('img')).filter(img => !img.hasAttribute('alt'));
}

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

Функция проверки и структура результата

Функция проверки должна возвращать объект с ключами:

  • passed — true, если элемент прошел проверку, false в противном случае.
  • message — строка с описанием нарушения (необязательный, но рекомендуется).
  • helpUrl — URL к документации или внутренним рекомендациям (опционально).

Пример проверки для всех изображений с отсутствующим атрибутом alt:

axe.core.registerCheck({
  id: 'img-alt-check',
  description: 'Все изображения должны иметь атрибут alt',
  selector: 'img',
  evaluate: (node) => {
    if (!node.hasAttribute('alt') || node.getAttribute('alt').trim() === '') {
      return { passed: false, message: 'Изображение не имеет описательного alt' };
    }
    return { passed: true };
  },
  impact: 'critical'
});

Интеграция кастомных checks с тестами

После регистрации кастомного check он автоматически включается в сканирование Axe-core. Пример использования с Node.js и браузерной средой:

const { AxePuppeteer } = require('axe-puppeteer');
const puppeteer = require('puppeteer');

(async () => {
  const browser = await puppeteer.launch();
  const page = await browser.newPage();
  await page.goto('https://example.com');

  const results = await new AxePuppeteer(page).analyze();
  console.log(results.violations);
  
  await browser.close();
})();

Все кастомные проверки, зарегистрированные через axe.core.registerCheck, автоматически добавляются в объект results.violations.

Уровни влияния и категоризация

Кастомные checks в Axe-core поддерживают уровни влияния, аналогичные встроенным правилам:

  • critical — нарушение, которое делает контент недоступным для пользователей с особыми потребностями.
  • serious — значительные барьеры для использования сайта.
  • moderate — умеренные проблемы, влияющие на удобство использования.
  • minor — косметические или малозначимые нарушения.

Присвоение правильного уровня критичности важно для формирования приоритетов исправления ошибок.

Использование кастомных checks с конфигурациями

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

const config = {
  rules: {
    'img-alt-check': { enabled: true },
    'custom-heading-check': { enabled: false }
  }
};

axe.run(document, config).then(results => {
  console.log(results.violations);
});

Это позволяет selectively активировать checks в разных средах или для различных страниц.

Советы по разработке кастомных проверок

  1. Минимизировать селекторы: проверка должна затрагивать только релевантные элементы.
  2. Писать информативные сообщения: рекомендации должны быть понятны разработчику и дизайнерам.
  3. Тестировать в разных браузерах: DOM может отличаться, что влияет на результаты проверки.
  4. Использовать impact корректно: правильно выбранный уровень критичности помогает приоритизировать исправления.
  5. Следовать стандартам WCAG: кастомные проверки должны расширять существующие правила, а не противоречить им.

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

Оглавление