Настройка проверки

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

npm install axe-core

или

yarn add axe-core

После установки библиотеку можно подключить в проекте:

import axe from 'axe-core';

Для работы в браузерной среде возможно использование CDN:

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

В этом случае объект axe будет доступен глобально.

Инициализация и базовая проверка

Для запуска проверки доступности необходимо вызвать метод run на выбранном DOM-элементе или на всем документе:

axe.run(document, {}, (err, results) => {
  if (err) throw err;
  console.log(results.violations);
});
  • document — корневой узел, на котором выполняется проверка. Можно использовать любой DOM-элемент.
  • {} — объект опций для настройки проверок.
  • results.violations — массив объектов с нарушениями доступности.

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

  • id — уникальный идентификатор правила;
  • impact — уровень влияния (critical, serious, moderate, minor);
  • description — текстовое описание нарушения;
  • nodes — список элементов, на которых найдено нарушение.

Настройка опций проверки

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

const options = {
  runOnly: {
    type: 'tag',
    values: ['wcag2a', 'wcag2aa']
  },
  rules: {
    'color-contrast': { enabled: false },
    'label': { enabled: true }
  }
};

axe.run(document, options, (err, results) => {
  console.log(results.violations);
});
  • runOnly — ограничение проверки только определенными наборами правил или тегами WCAG.
  • rules — включение или отключение конкретных правил по id.

Это позволяет, например, отключить проверку контрастности цвета для прототипов или сосредоточиться на критических правилах WCAG.

Настройка контекста проверки

Проверку можно ограничить частью DOM, передав элемент или селектор:

axe.run(document.querySelector('#main-content'), options, callback);

Контекст может быть любым элементом, включая Shadow DOM. Для работы с Shadow DOM используется опция include:

axe.run(document, {
  include: [['#shadow-host']]
}, callback);
  • include — массив селекторов или элементов, которые необходимо проверить.
  • exclude — массив элементов, которые следует игнорировать.

Асинхронная проверка и промисы

Axe-core поддерживает промисы для удобной интеграции с современными фреймворками:

axe.run(document, options).then(results => {
  console.log(results.violations);
}).catch(err => {
  console.error(err);
});

Это упрощает использование вместе с async/await:

async function checkAccessibility() {
  try {
    const results = await axe.run(document, options);
    console.log(results.violations);
  } catch (err) {
    console.error(err);
  }
}

Настройка отчетности

Результаты проверок можно фильтровать и форматировать:

results.violations.forEach(v => {
  console.log(`Rule: ${v.id}`);
  console.log(`Impact: ${v.impact}`);
  v.nodes.forEach(node => {
    console.log(`Element: ${node.html}`);
    console.log(`Message: ${node.failureSummary}`);
  });
});

Дополнительно доступны методы экспорта в JSON для автоматизированной интеграции с CI/CD:

const fs = require('fs');
fs.writeFileSync('axe-results.json', JSON.stringify(results, null, 2));

Настройка пользовательских правил

Axe-core позволяет создавать собственные правила:

axe.registerRule({
  id: 'custom-heading-check',
  selector: 'h1,h2,h3',
  enabled: true,
  evaluate(node) {
    return {
      result: node.textContent.trim().length > 0
    };
  },
  metadata: {
    description: 'Проверка наличия текста в заголовках',
    impact: 'moderate'
  }
});
  • id — уникальный идентификатор правила.
  • selector — CSS-селектор для элементов проверки.
  • evaluate — функция, возвращающая объект с полем result: true/false.
  • metadata — описание и уровень влияния.

Пользовательские правила интегрируются с основным результатом проверок и отображаются в results.violations.

Интеграция с тестовыми фреймворками

Axe-core часто используется с Jest и Cypress:

Jest:

import { configureAxe, toHaveNoViolations } from 'jest-axe';
expect.extend(toHaveNoViolations);

const axe = configureAxe();

test('component should be accessible', async () => {
  const html = renderToString(<MyComponent />);
  const results = await axe(html);
  expect(results).toHaveNoViolations();
});

Cypress:

import 'cypress-axe';

cy.visit('/page');
cy.injectAxe();
cy.checkA11y({
  runOnly: ['wcag2a']
});

Такая интеграция позволяет автоматизировать проверки доступности на уровне unit-тестов и end-to-end тестов.

Управление уровнями критичности

Axe-core классифицирует нарушения по влиянию на пользователя:

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

Фильтрация по уровню воздействия:

const criticalViolations = results.violations.filter(v => v.impact === 'critical');

Это позволяет сосредоточиться на исправлении наиболее значимых проблем перед релизом.

Локализация сообщений

Сообщения об ошибках можно локализовать, заменяя стандартные тексты:

axe.configure({
  locale: {
    'color-contrast': {
      description: 'Контраст текста и фона слишком низкий'
    }
  }
});

Поддерживается переопределение описаний, сообщений и примеров исправлений для каждой проверки. Это особенно важно для многоязычных приложений.

Оглавление