Настройка автоматического тестирования доступности через pa11y

Тестирование доступности с Pa11y

Pa11y — CLI-инструмент и Node.js библиотека для автоматизированного тестирования доступности. В отличие от axe-core, Pa11y лучше подходит для пакетного аудита всего сайта: читает sitemap.xml и проверяет сотни страниц последовательно.

Установка и базовый запуск

npm install -g pa11y pa11y-ci

# Проверка одной страницы
pa11y https://example.com --standard WCAG2AA

# Вывод в JSON
pa11y https://example.com --reporter json > report.json

pa11y-ci: пакетный аудит

// .pa11yci.json
{
  "defaults": {
    "standard":  "WCAG2AA",
    "timeout":   30000,
    "wait":      1000,
    "ignore":    [
      "WCAG2AA.Principle1.Guideline1_4.1_4_3.G18.Fail"
    ],
    "chromeLaunchConfig": {
      "args": ["--no-sandbox", "--disable-setuid-sandbox"]
    }
  },
  "urls": [
    "https://example.com",
    "https://example.com/about",
    "https://example.com/contact",
    {
      "url":    "https://example.com/login",
      "actions": [
        "wait for element #login-form to be visible"
      ]
    }
  ]
}

pa11y-ci --config .pa11yci.json --threshold 5
# --threshold: допустимое количество ошибок (0 = строгий режим)

Чтение из sitemap.xml

# Автоматически извлекает URLs из sitemap
pa11y-ci --sitemap https://example.com/sitemap.xml \
  --sitemap-find "https://example.com" \
  --sitemap-replace "http://localhost:3000" \
  --threshold 0

Node.js API для кастомных отчётов

// scripts/a11y-audit.js
const pa11y   = require('pa11y');
const fs      = require('fs');

const PAGES = [
  { url: 'http://localhost:3000', name: 'Главная' },
  { url: 'http://localhost:3000/catalog', name: 'Каталог' },
  { url: 'http://localhost:3000/checkout', name: 'Оформление заказа' },
];

async function audit() {
  const results = [];

  for (const page of PAGES) {
    console.log(`Checking: ${page.name}`);
    const result = await pa11y(page.url, {
      standard:  'WCAG2AA',
      timeout:   20000,
      actions:   page.actions || [],
    });

    results.push({
      name:       page.name,
      url:        page.url,
      issues:     result.issues.length,
      critical:   result.issues.filter(i => i.type === 'error').length,
      warnings:   result.issues.filter(i => i.type === 'warning').length,
      violations: result.issues,
    });
  }

  // Сохраняем отчёт
  fs.writeFileSync('a11y-report.json', JSON.stringify(results, null, 2));

  // Вывод сводки
  console.table(results.map(r => ({
    Страница: r.name,
    Ошибки:   r.critical,
    Предупреждения: r.warnings,
  })));

  // Падаем если есть критические
  if (results.some(r => r.critical > 0)) {
    process.exit(1);
  }
}

audit();

Скриншоты при нарушениях

const result = await pa11y(url, {
  screenCapture: `screenshots/${Date.now()}.png`,
  viewport: { width: 1280, height: 900 },
});

Сравнение Pa11y vs axe-core

Сроки

Настройка Pa11y CI с sitemap-аудитом и кастомным отчётом: 1–2 рабочих дня.