Настройка доступа

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

npm install axe-core --save-dev

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

import axe from 'axe-core';

или через CommonJS:

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

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

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

Инициализация и базовое использование

Для проведения проверки доступности требуется вызвать функцию axe.run(), передав ей DOM-узел или объект с конфигурацией:

axe.run(document, {
  runOnly: {
    type: 'tag',
    values: ['wcag2aa'] // проверка по стандарту WCAG 2.1 AA
  }
}).then(results => {
  console.log(results.violations);
}).catch(err => {
  console.error(err);
});

Ключевые параметры axe.run():

  • context – DOM-узел, селектор или объект с настройками области проверки.
  • options – конфигурация правил, тегов и исключений.
  • callback – альтернативный способ получения результатов вместо промиса.

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

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

axe.run(document, {
  rules: {
    'color-contrast': { enabled: true },
    'image-alt': { enabled: false } // отключение проверки
  },
  runOnly: {
    type: 'tag',
    values: ['wcag2a', 'wcag2aa']
  }
});
  • enabled – включение или отключение правила.
  • tags – группы правил, соответствующие стандартам WCAG или Section 508.
  • selector – ограничение области проверки конкретными селекторами.

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

Для автоматизированного тестирования Axe-core можно использовать совместно с Jest или Mocha. Пример интеграции с Jest:

import { configureAxe, toHaveNoViolations } from 'jest-axe';
import ReactDOMServer from 'react-dom/server';
import MyComponent from './MyComponent';

expect.extend(toHaveNoViolations);

test('Компонент соответствует стандартам доступности', async () => {
  const html = ReactDOMServer.renderToString(<MyComponent />);
  const results = await configureAxe(axe).run(html);
  expect(results).toHaveNoViolations();
});

Преимущество такого подхода — возможность включения проверок доступности в CI/CD, предотвращая попадание недоступных компонентов в продакшн.

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

Контекст проверки определяет область DOM, на которой будут выполняться правила. Возможные значения:

  • document — весь документ.
  • CSS-селекторы ('#main', '.header') — ограничение проверки конкретными элементами.
  • Объекты с фильтрацией include и exclude:
axe.run(document, {
  context: {
    include: [['#main-content']],
    exclude: [['.ads', '.popups']]
  }
});

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

Асинхронная обработка результатов

Все проверки Axe-core выполняются асинхронно. Результаты содержат несколько ключевых объектов:

  • violations — список найденных нарушений, включая описание и селекторы элементов.
  • incomplete — правила, которые не удалось полностью проверить.
  • passes — правила, которые прошли проверку.
  • inapplicable — правила, неприменимые к текущему контенту.

Пример обработки:

axe.run(document).then(results => {
  results.violations.forEach(v => {
    console.log(`Нарушение: ${v.id}`);
    v.nodes.forEach(node => {
      console.log(`  Селектор: ${node.target.join(', ')}`);
      console.log(`  Сообщение: ${node.failureSummary}`);
    });
  });
});

Настройка отчетов и интеграция с инструментами

Axe-core поддерживает кастомные функции отчетности. Можно формировать JSON, HTML или интегрировать с системами логирования:

axe.run(document).then(results => {
  const report = JSON.stringify(results, null, 2);
  console.log(report);
  // или отправка в систему CI
});

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

Конфигурация для SPA и динамического контента

Для приложений с динамическим DOM (React, Angular, Vue) рекомендуется запускать проверку после полной загрузки компонентов или событий обновления:

function checkAccessibility() {
  axe.run(document.getElementById('app')).then(results => {
    console.log(results.violations);
  });
}

// пример с MutationObserver
const observer = new MutationObserver(checkAccessibility);
observer.observe(document.getElementById('app'), { childList: true, subtree: true });

Такой подход гарантирует, что проверки проходят на актуальном состоянии страницы, включая контент, загруженный через AJAX или динамические компоненты.

Оглавление