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

Резин проблем доступности? Автоматизируйте аудит с Pa11y

Вы потратили недели на вёрстку, а клиент на скринридере не видит кнопку «Купить». Или хуже — получили претензию от Роскомнадзора за несоответствие WCAG 2.1. Ручная проверка 500 страниц — это дни работы QA. Pa11y решает проблему: запускается в CLI, читает sitemap.xml и выдаёт отчёт по всем страницам за один проход. Мы используем Pa11y в CI/CD более 5 лет на 50+ проектах — делимся опытом. Автоматизация проверки доступности веб-сайта с Pa11y сокращает время аудита на 70%, а стоимость обслуживания снижается за счёт раннего обнаружения багов. Оцените экономию: на проекте с 2000 страниц мы сократили аудит с 3 дней до 2 часов и нашли 47 критических ошибок, которые пропустили QA.

Почему стоит автоматизировать тестирование доступности?

Без автоматики вы пропустите 30–50% нарушений. Pa11y проверяет цветовой контраст, alt-тексты, ARIA-атрибуты, навигацию с клавиатуры. Мы настраиваем его так, чтобы он не пропускал критические ошибки, но игнорировал ложные срабатывания (например, контраст на заблокированных элементах). Типичные проблемы: отсутствие alt у изображений, неправильные ARIA-роли, низкий контраст текста. Автоматизация доступности (a11y testing) снижает затраты на аудит и ускоряет релизы.

Как интегрировать Pa11y в CI/CD?

Процесс настройки занимает 1–2 дня и включает пять шагов:

1. Анализ — собираем URL из sitemap.xml, определяем стандарт (обычно WCAG 2.1 AA).
2. Конфигурация — создаём .pa11yci.json с нужными параметрами и исключениями.
3. Интеграция — добавляем команду pa11y-ci в ваш пайплайн (GitLab CI, GitHub Actions, Jenkins).
4. Тестирование — запускаем пробный аудит, корректируем ложные срабатывания.
5. Документация — описываем процесс работы для команды.

Анализ и конфигурация

Процесс начинается с анализа вашего сайта: собираем список URL из sitemap.xml, шотов. Определяем стандарт (обычно WCAG2AA), таймауты, исключения. На выходе — .pa11yci.json:

// .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"
      ]
    }
  ]
}

Интеграция в пайплайн

Добавляем шаг в CI: на GitLab — pa11y-ci --config .pa11yci.json --threshold 5, на GitHub Actions — аналогично. Параметр --threshold задаёт допустимое количество ошибок. Строгий режим (--threshold 0) означает, что пайплайн упадёт при любой ошибке.

Чтение из sitemap.xml

pa11y-ci --sitemap https://example.com/sitemap.xml \
  --sitemap-find "https://example.com" \
  --sitemap-replace "http://localhost:3000" \
  --threshold 0

Как игнорировать ложные срабатывания?

Pa11y иногда ругается на контраст для disabled-элементов или на ARIA-роли, заданные фреймворком. Мы добавляем ignore-список в конфиг — это правка под ваш UI-кит. Например:

"ignore": [
  "WCAG2AA.Principle1.Guideline1_4.1_4_3.G18.Fail",
  "WCAG2AA.Principle4.Guideline4_1.4_1_2.H91.InputSearch.Name"
]

Это устраняет до 90% ложных срабатываний без потери критических проверок.

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

Pa11y выигрывает, когда нужно прогнать весь сайт. Axe предпочтительнее в unit-тестах. Мы комбинируем: Pa11y для ночных аудитов, axe в пре-коммит хуках. Это даёт полное покрытие без дублирования.

Пример отчёта 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();

Что вы получаете?

После настройки Pa11y вы получаете:

• Рабочий конфигурационный файл .pa11yci.json с настройками под ваш проект.
• Интеграцию в CI/CD — автоматический запуск аудита при каждом пуше.
• Кастомный игнор-лист для ложных срабатываний.
• Документацию по интерпретации отчётов и исправлению типичных ошибок.
• Обучение команды: как читать отчёты Pa11y и фиксить баги доступности.

Этапы настройки Pa11y

Сроки и стоимость

Базовая настройка занимает 1–2 дня. Расширенная с кастомными правилами, скриншотами и обучением — до 5 дней. Стоимость рассчитывается индивидуально под объём сайта. Окупаемость настройки — менее 3 месяцев. Оценим проект за 1 час — свяжитесь с нами.

Pa11y запускает headless-браузер (Chrome), загружает каждую страницу и проверяет её на соответствие выбранному стандарту WCAG. Результаты группируются по типу ошибок: error (критические), warning (замечания), notice (информационные). Это позволяет быстро выявить проблемные места и приоритезировать правки.

Как начать?

Свяжитесь с нами для консультации. Закажите аудит доступности, и если после нашего аудита вы получите штраф за нарушение WCAG — перепроверим бесплатно. Вложения в автоматизацию окупаются уже через 2–3 месяца. Получите вашу конфигурацию Pa11y и избавьтесь от ручных проверок навсегда.

Доступность сайтов: WCAG, скринриндеры, клавиатурная навигация

На сайте крупного банка кнопка «Подать заявку» в разметке была <div class="btn" onclick="...">. Скринридер NVDA её не анонсировал, Tab пропускал, Enter не срабатывал. Для тысяч незрячих пользователей этот банк просто не существовал как онлайн-сервис. Мы видим такие проблемы каждый день в десятках проектов — и разработка доступных сайтов по стандарту WCAG 2.2 AA становится единственным способом избежать дискриминации и юридических рисков. Штрафы за недоступность для юрлиц достигают 300 000 ₽, а судебные иски — миллионы.

В этой карточке — как мы делаем веб-доступность a11y работающей, на реальных кейсах, с конкретным стеком и цифрами. Без общих фраз.

Почему семантическая разметка — основа веб-доступности a11y?

Большинство проблем доступности решается правильным HTML, а не дополнительными ARIA-атрибутами. <button> вместо <div onclick>, <nav> вместо <div class="navigation">, <h1>–<h6> в правильной иерархии, <label for="field-id"> вместо <div class="label">. Это базовый уровень, но на практике каждая вторая форма в российских интернет-магазинах не имеет корректных <label>.

ARIA нужна там, где нативный HTML не справляется: кастомные компоненты — выпадающие меню, тултипы, модальные окна, табы, accordion. И вот тут начинается сложность.

Типичная ошибка в кастомных дропдаунах: скринридер не знает, что это combobox, не объявляет количество опций, не говорит какая выбрана, фокус не переходит в список при открытии. Правильная реализация:

• role="combobox" на инпуте
• aria-expanded="true/false" при открытии/закрытии
• aria-controls="listbox-id" указывает на список
• aria-activedescendant — ID текущего выбранного элемента
• role="option" и aria-selected на каждом варианте

Это не теория, это то, что тестируется скринридером. NVDA + Chrome или VoiceOver + Safari — обязательная часть QA.

<div role="combobox" aria-expanded="false" aria-controls="listbox-1" aria-activedescendant="" tabindex="0">
  <label for="input-1">Выберите город</label>
  <input id="input-1" type="text" role="combobox" aria-autocomplete="list" />
  <ul id="listbox-1" role="listbox" aria-label="Города">
    <li role="option" aria-selected="false" id="opt-1">Москва</li>
    <li role="option" aria-selected="false" id="opt-2">Санкт-Петербург</li>
  </ul>
</div>

Стоимость исправления одного нарушения уровня A — от 5 000 до 15 000 ₽ в зависимости от сложности. Внедрение a11y с этапа проектирования сокращает бюджет на рефакторинг в 2–3 раза по сравнению с доработкой готового сайта.

Как правильно построить клавиатурную навигацию?

Tab-порядок должен совпадать с визуальным порядком элементов. Если в HTML кнопка «Отмена» стоит перед «Подтвердить», но CSS их меняет местами — пользователь клавиатуры в замешательстве.

Focus trap в модальных окнах. Когда модалка открывается, Tab должен циклиться только внутри неё. При закрытии — возврат фокуса на элемент, который открыл модалку. Без этого пользователь после закрытия оказывается в начале страницы.

tabindex="-1" — элемент не попадает в Tab-последовательность, но может получить фокус программно. Используется для элементов, которые получают фокус через JavaScript (заголовки секций после навигации по якорям).

tabindex="1" и выше — почти всегда ошибка. Явный порядок ломает естественный и создаёт непредсказуемое поведение. Управляйте порядком через DOM, не через tabindex.

Skip links — ссылка «Перейти к содержимому», скрытая визуально, видимая при Tab. Позволяет пользователям скринридеров пропустить повторяющуюся навигацию.

Цвет и контраст: требования и частые нарушения

WCAG 2.2 AA требует контраст 4.5:1 для обычного текста, 3:1 для крупного (18px+ или 14px+ bold). AAA требует 7:1 и 4.5:1.

Самые частые нарушения: серый placeholder в инпутах (#999 на белом = 2.9:1), светло-серый secondary текст, белый текст на пастельном фоне.

Цвет не должен быть единственным индикатором: «поля обязательные выделены красным» без звёздочки — нарушение для людей с цветовой слепотой.

Инструменты проверки: axe DevTools, WAVE, Accessibility Inspector в Chrome DevTools. axe-core интегрируется в Playwright-тесты: автоматическая проверка на 80+ правил при каждом деплое. Ручное тестирование находит примерно на 60% больше ошибок, чем автоматическое.

Медиаконтент и динамика: что важно?

Изображения без alt — частый базовый провал. alt должен быть смысловым: не alt="image_123.jpg", а описание содержимого, релевантное контексту. Декоративные изображения — alt="" (пустой, не отсутствующий атрибут).

Видео должно иметь субтитры. YouTube автосубтитры — не стандарт, они ошибаются. WebVTT-файлы с корректными субтитрами для всего образовательного и маркетингового видеоконтента.

Анимации — проблема для пользователей с вестибулярными расстройствами. @media (prefers-reduced-motion: reduce) — медиа-запрос, отключающий или замедляющий анимации для пользователей с такой настройкой в ОС.

Что изменилось в WCAG 2.2?

Версия 2.2 вступила в силу с новыми критериями:

Эти критерии повышают порог входа, но мы уже включаем их в стандартный чек-лист.

Аудит и устранение нарушений

Автоматические инструменты находят около 30–40% нарушений. Остальное — только ручное тестирование. Минимальный сценарий: пройти весь критический user flow (регистрация, покупка, форма) только клавиатурой и со скринридером.

Процесс работы

1. Автоматический аудит — axe-core, Lighthouse, WAVE — выдача 80+ правил.
2. Ручное тестирование — NVDA, VoiceOver, клавиатура — 2–3 дня на типовой сайт.
3. Приоритизация нарушений — P1 (блокирует использование), P2 (создаёт сложности), P3 (улучшения).
4. Исправление — итерациями, встраиваем проверки в CI через Playwright + axe.
5. Повторный аудит — закрытие всех P1/P2 перед релизом.
6. Документация и передача — отчёт с результатами, рекомендации по поддержке, обучение команды.

Результаты и объём работ

• Полный отчёт по аудиту с приоритизацией нарушений (PDF/HTML)
• Исправленный код: семантическая разметка, ARIA, клавиатурная навигация
• Интеграция axe-core в CI/CD для регрессионного контроля
• Обучение разработчиков заказчика по работе с a11y (2-часовая сессия)
• Доступ к репозиторию с примерами корректных компонентов
• Гарантия соответствия WCAG 2.2 AA на момент сдачи

Сроки

Бюджет рассчитывается индивидуально после аудита. Свяжитесь с нами — оценим ваш проект за 1 день. Получите консультацию и чек-лист бесплатно при заказе аудита.

Опыт и гарантии

Мы занимаемся веб-доступностью a11y более 8 лет. Реализовали более 50 проектов для банков, ритейла и госсектора. Сертифицированные специалисты (IAAP CPACC, WAS). Гарантируем прохождение аудита третьей стороной или дорабатываем бесплатно.

Стандарт WCAG 2.2 — официальная рекомендация W3C, определяющая требования к доступности веб-контента.

Wikipedia: Web Content Accessibility Guidelines
Wikipedia: ARIA

— уровни веб-доступности a11y по версии 2.2.

Закажите аудит сейчас — получите чек-лист и предварительную оценку бесплатно. Пишите в Telegram или на почту — ответим в течение часа.