Анализ отдельного элемента

Библиотека Axe-core является мощным инструментом для автоматизированного анализа доступности веб-страниц. Для работы с отдельными элементами необходимо установить пакет через npm:

npm install axe-core

В браузерных проектах можно подключить скрипт напрямую через CDN:

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

После подключения библиотека доступна через глобальный объект axe.

Инициализация и конфигурация

Для анализа конкретного элемента необходимо инициализировать Axe с настройками. Основной метод — axe.run(), который принимает два аргумента: целевой элемент и опции конфигурации.

import axe from 'axe-core';

const element = document.querySelector('#target-element');

axe.run(element, {
  rules: {
    'color-contrast': { enabled: true },
    'label': { enabled: true },
  },
  reporter: 'v2'
}).then(results => {
  console.log(results.violations);
});

Ключевые моменты конфигурации:

  • rules — объект с настройкой конкретных правил. Можно включать или отключать правила, настраивать их параметры.
  • reporter — определяет формат отчёта. В современных версиях рекомендуется v2, который структурирует данные для удобного анализа.

Выбор конкретного элемента

Метод axe.run() принимает DOM-элемент или селектор CSS. Важно передавать корень, с которого начинается анализ. Если не указать элемент, анализируется весь документ:

const element = document.querySelector('.form-section');

axe.run(element).then(results => {
  results.violations.forEach(v => {
    console.log(`Нарушение: ${v.id}, Элементы: ${v.nodes.map(n => n.target)}`);
  });
});

Особенности:

  • Для динамических элементов, которые подгружаются через JavaScript, необходимо запускать анализ после того, как элемент полностью отрендерен.
  • Можно использовать массив элементов или комбинированные селекторы для анализа нескольких узлов одновременно.

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

Результаты Axe включают массив violations, каждая из которых содержит список nodes — узлов DOM, к которым применимо нарушение. Для анализа отдельного элемента фильтруют nodes:

const targetElement = document.querySelector('#submit-button');

axe.run(document).then(results => {
  const violationsForElement = results.violations.filter(v =>
    v.nodes.some(node => node.target.includes('#submit-button'))
  );

  console.log(violationsForElement);
});

Преимущества такого подхода:

  • Можно просматривать только релевантные нарушения.
  • Удобно интегрировать в модульные тесты для конкретных компонентов интерфейса.

Настройка правил под отдельный элемент

Некоторые элементы требуют индивидуальной конфигурации правил. Например, кнопки могут проверяться на доступность текста, а формы — на корректное использование aria-label.

axe.run(document.querySelector('#login-form'), {
  rules: {
    'label': { enabled: true },
    'button-name': { enabled: true },
    'color-contrast': { enabled: false } // отключение для конкретного блока
  }
});

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

Для автоматизированного тестирования отдельных элементов удобно использовать Axe совместно с Jest или Cypress.

Пример с Jest:

import axe from 'axe-core';
import { render } from '@testing-library/react';
import MyButton from './MyButton';

test('кнопка доступна', async () => {
  const { container } = render(<MyButton />);
  const results = await axe.run(container.querySelector('button'));
  expect(results.violations).toHaveLength(0);
});

Пример с Cypress:

cy.get('#main-form').then($el => {
  cy.window().then(win => {
    win.axe.run($el[0], {}, (err, results) => {
      if (err) throw err;
      cy.log(JSON.stringify(results.violations));
    });
  });
});

Практические советы при анализе отдельного элемента

  1. Избегать анализа до полной загрузки DOM. Асинхронные компоненты могут не пройти проверку, если запускать Axe слишком рано.
  2. Использовать селекторы с высокой специфичностью. Это предотвращает включение лишних узлов в отчёт.
  3. Комбинировать включение и отключение правил. Позволяет фокусироваться на типичных нарушениях для конкретного элемента.
  4. Автоматизировать фильтрацию результатов. Для больших приложений полезно формировать отчёты только по изменяемым компонентам.

Расширенные возможности

Axe-core поддерживает:

  • Проверку ARIA-атрибутов на конкретном элементе.
  • Проверку контрастности текста, включая динамические цвета и темы.
  • Встроенные дескрипторы нарушений с детальной инструкцией по исправлению.

Пример анализа с детальным контекстом:

axe.run(document.querySelector('#profile-card')).then(results => {
  results.violations.forEach(v => {
    v.nodes.forEach(node => {
      console.log('Элемент:', node.target.join(', '));
      console.log('Описание:', node.failureSummary);
    });
  });
});

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

Оглавление