Puppeteer

Для работы с библиотекой Axe-core в контексте Puppeteer необходимо установить соответствующие пакеты через npm:

npm install puppeteer axe-core

Axe-core представляет собой инструмент для автоматической проверки доступности веб-страниц (accessibility). В связке с Puppeteer она позволяет выполнять тестирование страниц в headless-браузере и получать структурированные отчёты о нарушениях WCAG, ARIA и других стандартов доступности.

Интеграция Axe-core с Puppeteer

После установки библиотек, Axe-core загружается в контекст страницы Puppeteer с помощью page.addScriptTag. Это позволяет запускать скрипт библиотеки непосредственно на открытой странице.

Пример:

const puppeteer = require('puppeteer');
const axeSource = require('axe-core').source;

(async () => {
  const browser = await puppeteer.launch();
  const page = await browser.newPage();
  
  await page.goto('https://example.com');

  // Внедрение axe-core в страницу
  await page.addScriptTag({ content: axeSource });

  // Выполнение аудита доступности
  const results = await page.evaluate(async () => {
    return await axe.run();
  });

  console.log(results.violations);
  await browser.close();
})();

Ключевой момент: axe.run() возвращает объект с результатами, где основное внимание уделяется массиву violations. Каждая запись содержит:

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

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

axe.run поддерживает передачу двух типов аргументов:

  1. Селекторы и контекст – позволяет ограничивать аудит определёнными областями страницы.
  2. Конфигурация – включает или отключает конкретные правила, изменяет уровень важности и т.д.

Пример конфигурации:

const results = await page.evaluate(async () => {
  return await axe.run(document, {
    runOnly: {
      type: 'tag',
      values: ['wcag2a', 'wcag2aa']
    },
    rules: {
      'color-contrast': { enabled: false }
    }
  });
});

Здесь указано:

  • runOnly – запуск только правил с тегами wcag2a и wcag2aa;
  • rules – отключение конкретного правила проверки контрастности текста.

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

Результаты Axe-core можно преобразовывать для удобства анализа. Чаще всего фильтруют по уровню серьёзности и выводят конкретные элементы с нарушениями.

Пример фильтрации критических и серьёзных нарушений:

const violations = results.violations
  .filter(v => v.impact === 'critical' || v.impact === 'serious')
  .map(v => ({
    id: v.id,
    impact: v.impact,
    description: v.description,
    elements: v.nodes.map(n => n.html)
  }));

console.log(JSON.stringify(violations, null, 2));

Это позволяет получать компактные отчёты, сразу выделяя элементы, требующие исправления.

Асинхронная проверка динамического контента

Для SPA и страниц с динамической подгрузкой контента важно вызывать axe.run после полной отрисовки элементов DOM. Puppeteer предоставляет методы ожидания:

await page.waitForSelector('#main-content', { visible: true });
const results = await page.evaluate(async () => await axe.run());

Можно использовать setTimeout или page.waitForFunction, если контент формируется через JavaScript и не имеет явных селекторов.

Автоматизация тестов доступности

Интеграция Axe-core с Puppeteer позволяет включать аудит доступности в CI/CD-пайплайны. Пример использования с Jest:

const puppeteer = require('puppeteer');
const axeSource = require('axe-core').source;

describe('Accessibility Tests', () => {
  let browser, page;

  beforeAll(async () => {
    browser = await puppeteer.launch();
    page = await browser.newPage();
    await page.goto('https://example.com');
    await page.addScriptTag({ content: axeSource });
  });

  afterAll(async () => {
    await browser.close();
  });

  test('Страница соответствует стандартам WCAG', async () => {
    const results = await page.evaluate(() => axe.run());
    expect(results.violations).toHaveLength(0);
  });
});

Такой подход гарантирует, что доступность проверяется на каждом коммите, а тесты CI будут падать при обнаружении серьёзных нарушений.

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

  • Тегирование нарушений: каждая проверка сопровождается тегами (wcag2aa, wcag21aa, section508), что позволяет настраивать аудит под конкретные требования.
  • Проверка ARIA и форм: анализ правильности использования атрибутов aria-*, role, а также валидности форм и интерактивных элементов.
  • Снимки нарушений: возможность сохранять скриншоты проблемных элементов через Puppeteer, чтобы сочетать текстовый отчёт с визуальной отладкой.

Рекомендации по производительности

  • Загружать axe-core один раз для всех страниц в рамках одной сессии Puppeteer, если выполняется пакетная проверка.
  • Использовать runOnly и селекторы для ограничения области проверки и ускорения анализа.
  • Фильтровать результаты на уровне выполнения page.evaluate, чтобы не передавать весь объект в Node.js, если требуется только краткий отчёт.

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

const fs = require('fs');

const results = await page.evaluate(() => axe.run());
const report = results.violations.map(v => ({
  rule: v.id,
  impact: v.impact,
  description: v.description,
  elements: v.nodes.map(n => n.html)
}));

fs.writeFileSync('axe-report.json', JSON.stringify(report, null, 2));

В дальнейшем такой JSON можно использовать для генерации HTML-отчётов или интеграции с системами анализа качества кода.

Форматирование отчёта позволяет объединять текстовое описание нарушений с конкретными HTML-элементами, что облегчает исправление проблем и интеграцию в workflow команды.

Оглавление