Як автоматизувати тестування доступності з axe-core, Jest та Playwright

Часто порушення доступності (a11y) спливають лише на етапі ручного тестування або, що гірше, в продакшні. Кожен пропущений критичний баг — наприклад, відсутність alt у зображення або несправна навігація з клавіатури — може коштувати репутації та великих штрафів. Ми автоматизуємо перевірку WCAG 2.1/2.2 через бібліотеку axe-core від Deque Systems, щоб виловлювати такі проблеми на етапі CI/CD. Бібліотека знаходить близько 57% порушень автоматично, залишаючи решту на ручний аудит. Досвід показує: після впровадження axe-core кількість регресій за доступністю падає на 70–80%. Автоматичне тестування в 10 разів швидше за ручне.

Як axe-core допомагає автоматизувати перевірку доступності?

axe-core працює як у браузері, так і в Node.js, і легко вбудовується в існуючі тестові фреймворки. В основі лежать правила стандарту WCAG 2.1, згруповані за тегами (wcag2a, wcag2aa, wcag21aa). Для кожного елемента сторінки бібліотека перевіряє: контрастність, семантику заголовків, доступність форм, ARIA-атрибути та багато іншого. Результат — структурований звіт з типом, рівнем серйозності та посиланням на елемент.

Інтеграція з Jest + Testing Library

npm install --save-dev jest-axe @testing-library/react

// __tests__/accessibility.test.tsx
import { render } from '@testing-library/react';
import { axe, toHaveNoViolations } from 'jest-axe';

expect.extend(toHaveNoViolations);

describe('Доступність компонентів', () => {
  it('Button не має порушень', async () => {
    const { container } = render(<Button>Відправити</Button>);
    const results = await axe(container);
    expect(results).toHaveNoViolations();
  });

  it('Form не має порушень', async () => {
    const { container } = render(
      <form>
        <label htmlFor="email">Email</label>
        <input id="email" type="email" />
        <button type="submit">Увійти</button>
      </form>
    );
    const results = await axe(container, {
      rules: {
        'color-contrast': { enabled: true },
        'label': { enabled: true },
      },
    });
    expect(results).toHaveNoViolations();
  });
});

Інтеграція з Playwright

// tests/accessibility.spec.ts
import { test, expect } from '@playwright/test';
import AxeBuilder from '@axe-core/playwright';

test('Головна сторінка проходить WCAG 2.1 AA', async ({ page }) => {
  await page.goto('/');

  const results = await new AxeBuilder({ page })
    .withTags(['wcag2a', 'wcag2aa', 'wcag21aa'])
    .exclude('.cookie-banner')  // Виключаємо компоненти третіх сторін
    .analyze();

  expect(results.violations).toEqual([]);
});

test('Форма реєстрації — доступність', async ({ page }) => {
  await page.goto('/register');

  const results = await new AxeBuilder({ page })
    .include('#registration-form')
    .analyze();

  // Детальний звіт при падінні
  if (results.violations.length > 0) {
    console.table(results.violations.map(v => ({
      id:          v.id,
      impact:      v.impact,
      description: v.description,
      nodes:       v.nodes.length,
    })));
  }

  expect(results.violations).toEqual([]);
});

Чому варто інтегрувати axe-core в CI/CD?

Ручну перевірку доступності складно масштабувати: на один аудит сторінки йде 2–3 години. Інтеграція axe-core в CI/CD (наприклад, через Playwright тест перед кожним деплоєм) автоматизує цю перевірку. Ми гарантуємо, що критичні порушення не потраплять у продакшн. В одному з проектів з 500+ сторінками після налаштування axe-core кількість регресій по a11y знизилась з 30 до 2–3 на місяць. Вартість впровадження — від 4000 грн.

З чого почати: покрокова інструкція

1. Встановіть пакет jest-axe для модульного тестування компонентів.
2. Налаштуйте тести з використанням matcher toHaveNoViolations.
3. Інтегруйте axe-core з Playwright для e2e-тестів критичних сторінок.
4. Додайте тести в CI/CD пайплайн (GitHub Actions, GitLab CI).
5. Налаштуйте сповіщення про падіння.

Типові помилки при налаштуванні axe-core

При першому запуску axe-core часто видає хибні спрацьовування на сторонніх iframe, cookie-банерах або динамічно завантажуваному контенті. Щоб уникнути шуму, налаштуйте винятки через exclude() та задайте точні теги перевірки (наприклад, wcag2aa). Також важливо правильно сконфігурувати правила: вимкнути ті, що не застосовні до проекту (наприклад, color-contrast для компонентів з кастомними кольорами).

Чек-лист впровадження axe-core

• Виключити iframe та віджети третіх сторін.
• Налаштувати кастомні правила для специфічних компонентів.
• Інтегрувати з Jest для модульних тестів компонентів.
• Інтегрувати з Playwright для e2e тестів критичних сторінок.
• Додати запуск в CI/CD (GitHub Actions, GitLab CI).
• Налаштувати сповіщення про падіння.

Що входить в роботу (під ключ)

• Документація: звіт про поточні порушення, список правил, винятки для сторонніх компонентів.
• Інтеграція: налаштування axe-core в Jest (модульні тести компонентів), Playwright (e2e-тести сторінок) та Storybook (візуальна інспекція) — при необхідності.
• CI/CD пайплайн: додавання тестів доступності в GitLab CI, GitHub Actions або аналогічні.
• Навчання команди: базова лекція (1–2 години) по WCAG та роботі з axe-core.
• Підтримка: консультації з виправлення виявлених порушень протягом місяця після впровадження.

Терміни

Налаштування axe-core в Jest + Playwright, покриття ключових сторінок та компонентів: 2–3 робочих дні. Якщо проект використовує нестандартні фреймворки (Angular, Vue 3 з SSR) або потребує глибокої кастомізації правил, термін може збільшитися до 5 днів. Ми працюємо за передоплатою 50%, остаточна вартість розраховується індивідуально після аудиту вашого коду. Оцінимо ваш проект безкоштовно.

Наша команда має 5+ років досвіду в a11y-аудиті та понад 50 успішних проектів. Пишіть нам для консультації з впровадження axe-core у ваш проект. Замовте аудит доступності — це знизить ризики та заощадить час.

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

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

У цій картці — як ми робимо веб-доступність 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 — відповідно до складності (від невеликих до значних сум). Впровадження 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 або на пошту — відповімо протягом години.