Налаштування автоматичного тестування доступності через 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 робочих дні.