Возвращаемые промисы

Библиотека Axe-core предназначена для автоматизированного тестирования доступности веб-страниц. Она предоставляет функционал для анализа DOM и выявления нарушений стандартов доступности (WCAG). Все операции Axe-core, связанные с запуском анализа, возвращают промисы, что обеспечивает асинхронное выполнение и удобное взаимодействие с другими частями приложения.

Асинхронный метод run

Главный метод для запуска аудита — axe.run. Он принимает два основных параметра: объект контейнера и опции конфигурации. Возвращаемое значение — промис, который разрешается с объектом результатов.

axe.run(document, { runOnly: ['wcag2a', 'wcag2aa'] })
  .then(results => {
      console.log(results.violations);
  })
  .catch(err => {
      console.error(err);
  });

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

  • axe.run никогда не блокирует поток выполнения.
  • Метод возвращает промис, который содержит violations, incomplete и passes.
  • Ошибки обработки DOM, конфигурации или сторонних скриптов приводят к отклонению промиса через .catch.

Структура возвращаемого объекта

Результат промиса — объект с несколькими массивами:

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

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

  • passes — элементы, прошедшие проверку;

  • incomplete — проверки, которые не были завершены (например, динамический контент);

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

Использование async/await

Для удобного управления асинхронными операциями промисы можно использовать с async/await:

async function runAxe() {
    try {
        const results = await axe.run(document, { runOnly: ['wcag2a'] });
        console.log('Нарушения:', results.violations);
    } catch (err) {
        console.error('Ошибка выполнения Axe:', err);
    }
}

Преимущества:

  • Чтение кода становится линейным и наглядным.
  • Упрощается последовательное выполнение нескольких тестов.
  • Исключается необходимость вложенных .then и .catch.

Параметры конфигурации и влияние на промис

Метод axe.run поддерживает гибкую настройку:

  • runOnly — массив или объект правил, которые следует проверять. Ограничение правил влияет на размер массива violations.
  • reporter — формат результатов (v2, v3, json, html). Результат промиса всегда совместим с выбранным форматом.
  • elementRef — можно указать конкретный элемент DOM вместо всего документа. Промис вернёт только результаты для этого элемента.
  • rules — детальная настройка правил, включая включение или исключение отдельных проверок и уровней воздействия.
const options = {
  runOnly: { type: 'tag', values: ['wcag2aa'] },
  rules: {
    'color-contrast': { enabled: false }
  }
};

axe.run(document.body, options)
  .then(results => console.log(results))
  .catch(console.error);

Обработка множественных промисов

При необходимости анализа нескольких страниц или элементов часто используют Promise.all:

const elements = [document.querySelector('#header'), document.querySelector('#footer')];

Promise.all(elements.map(el => axe.run(el)))
  .then(resultsArray => {
      resultsArray.forEach((res, index) => {
          console.log(`Элемент ${index}:`, res.violations);
      });
  })
  .catch(err => console.error(err));
  • Каждый вызов axe.run создаёт отдельный промис.
  • Promise.all отклоняется, если хотя бы один промис завершился с ошибкой.
  • Для независимой обработки ошибок применяют Promise.allSettled.

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

В средах Jest, Mocha или Cypress промисы позволяют интегрировать Axe-core в цепочку тестов:

it('Проверка доступности', async () => {
    const results = await axe.run(document);
    expect(results.violations.length).toBe(0);
});
  • Асинхронные тесты автоматически ждут завершения промиса.
  • Ошибки аудита могут приводить к падению теста при необходимости.

Обработка исключений и временные задержки

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

  • Использовать try/catch или .catch.
  • Обеспечивать, чтобы DOM полностью загружался перед вызовом axe.run.
  • В динамических SPA добавлять задержку или наблюдать за изменениями DOM через MutationObserver.

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

Оглавление