Функция evaluate

Функция evaluate является одним из ключевых инструментов библиотеки Axe-core для автоматизированной проверки доступности веб-контента. Она позволяет запускать анализ конкретного элемента или целой страницы и получать структурированные результаты, включающие обнаруженные ошибки, предупреждения и рекомендации по исправлению.

Подключение Axe-core

Для использования evaluate необходимо подключить библиотеку Axe-core. Наиболее часто это делается через npm:

import axe from 'axe-core';

Для работы в браузере возможна загрузка через CDN:

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

После загрузки библиотеки становится доступна глобальная функция axe.run, которая является основной для анализа, но evaluate используется внутри для обработки и фильтрации результатов.

Синтаксис функции evaluate

Функция evaluate применяется к объекту, описывающему контекст проверки:

axe.evaluate(options, callback);

Параметры:

  • options — объект с настройками проверки. Может содержать:

    • element — DOM-элемент, для которого проводится анализ. Если не указан, анализируется весь документ.
    • runOnly — массив правил или категорий правил для ограничения проверки.
    • includedImpacts — список уровней влияния (critical, serious, moderate, minor), которые будут включены в результат.

  • callback — функция обратного вызова, которая получает результаты проверки после завершения анализа.

Пример базового вызова:

axe.evaluate({ element: document.body }, function(results) {
    console.log(results.violations);
});

Структура результата

Результат, возвращаемый функцией evaluate, представляет собой объект с несколькими ключевыми полями:

  • violations — массив объектов с выявленными нарушениями. Каждый объект содержит:

    • id — уникальный идентификатор правила.
    • impact — уровень воздействия.
    • description — текстовое описание проблемы.
    • help — краткая рекомендация.
    • nodes — массив элементов DOM, на которых обнаружена проблема, с подробной информацией о селекторах и HTML-контексте.

  • passes — массив объектов правил, успешно пройденных на странице.

  • incomplete — правила, которые не удалось полностью проверить.

  • inapplicable — правила, которые не применимы к текущему контенту.

Пример обработки результата:

axe.evaluate({ element: document.body }, function(results) {
    results.violations.forEach(violation => {
        console.log(`Ошибка: ${violation.description} (уровень: ${violation.impact})`);
        violation.nodes.forEach(node => {
            console.log(`Элемент: ${node.target}`);
        });
    });
});

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

Функция evaluate поддерживает гибкую фильтрацию по правилам и уровням важности. Это позволяет сосредоточиться на наиболее критичных проблемах:

const options = {
    runOnly: {
        type: 'tag',
        values: ['wcag2a', 'wcag2aa']
    },
    includedImpacts: ['critical', 'serious']
};

axe.evaluate(options, function(results) {
    console.log(results.violations.length + ' критических и серьёзных нарушений обнаружено.');
});
  • runOnly с type: 'tag' позволяет запускать проверку только для выбранных стандартов WCAG.
  • includedImpacts ограничивает результат только указанными уровнями влияния.

Асинхронный вариант

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

async function checkAccessibility() {
    const results = await axe.run(document.body);
    results.violations.forEach(v => console.log(v.description));
}

Хотя axe.run используется чаще, evaluate лежит в основе обработки данных и обеспечивает расширенные возможности фильтрации, особенно при создании собственных инструментов отчётности.

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

evaluate часто используется совместно с Jest, Mocha или Cypress для автоматизации тестирования доступности:

import axe from 'axe-core';
import { mount } from '@cypress/react';

it('проверяет доступность компонента', () => {
    mount(<MyComponent />);
    cy.document().then(doc => {
        axe.evaluate({ element: doc.body }, (results) => {
            expect(results.violations).to.have.length(0);
        });
    });
});

Это позволяет интегрировать анализ доступности в CI/CD и выявлять ошибки до публикации продукта.

Практические рекомендации

  • Проверка конкретного элемента через element снижает время анализа больших страниц.
  • Использование фильтров runOnly и includedImpacts помогает сосредоточиться на критических проблемах.
  • Для динамического контента рекомендуется запускать evaluate после рендеринга элементов, чтобы результаты отражали актуальное состояние DOM.
  • Сочетание с асинхронными вызовами и промисами упрощает интеграцию с современными SPA-фреймворками, такими как React или Vue.

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

Оглавление