Простейший пример использования

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

npm install axe-core

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

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

В браузерных проектах возможно использование через <script>:

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

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

Инициализация и базовый анализ

Основной метод для запуска проверки доступности — axe.run(). Он принимает два параметра: селектор области документа для анализа и объект опций.

Простейший пример проверки всего документа:

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

Ключевые моменты:

  • document — DOM-узел или селектор, который будет проверяться. Можно использовать любой узел, включая document.body.
  • Второй параметр — объект конфигурации, который позволяет включать или исключать определённые правила.
  • results.violations — массив объектов с информацией о нарушениях доступности, содержащий id, impact, description, nodes.

Структура объекта violations

Каждое нарушение имеет следующую структуру:

{
  "id": "color-contrast",
  "impact": "serious",
  "description": "Контраст текста слишком низкий",
  "help": "Использовать более контрастные цвета текста и фона",
  "nodes": [
    {
      "html": "<p style='color:#aaa;'>Текст</p>",
      "target": ["p"],
      "failureSummary": "Контраст между цветом текста и фоном слишком низкий"
    }
  ]
}

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

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

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

Для анализа можно указать конкретные правила или группы правил:

axe.run(document, {
    rules: {
        'color-contrast': { enabled: true },
        'image-alt': { enabled: false }
    }
}, (err, results) => {
    if (err) throw err;
    console.log(results.violations);
});

Это позволяет исключить из проверки ненужные правила, ускоряя анализ и сокращая количество ложных срабатываний.

Анализ конкретного элемента

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

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

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

В этом случае axe-core анализирует только содержимое указанного узла и его потомков.

Асинхронная работа через промисы

Современный подход использует промисы:

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

Преимущество промисов в том, что их легко интегрировать в тестовые фреймворки, такие как Jest или Mocha, и использовать с async/await.

Интеграция с автоматизированным тестированием

Простейший пример с Jest:

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

test('Проверка доступности страницы', async () => {
    const results = await axe.run(document);
    expect(results.violations.length).toBe(0);
});

В этом случае тест пройдёт, если нарушений нет, и упадёт при обнаружении хотя бы одного.

Визуализация результатов

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

results.violations.forEach(v => {
    console.log(`Правило: ${v.id}`);
    console.log(`Влияние: ${v.impact}`);
    console.log(`Описание: ${v.description}`);
    v.nodes.forEach(node => {
        console.log(`Элемент: ${node.html}`);
        console.log(`Сводка: ${node.failureSummary}`);
    });
});

Это удобно для журналирования и составления отчетов.

Примечания

  • Axe-core не изменяет DOM, проверка только читает структуру.
  • Важна актуальность версии библиотеки, так как правила и рекомендации по доступности обновляются.
  • Использование axe.run() совместимо с любыми библиотеками для тестирования компонентов, включая React, Vue и Angular, при условии, что доступен DOM.
Оглавление