re:re:actable
Урок 015 минут чтения

Тестирование доступности: axe и проверки с клавиатуры

На этой странице
Кратко

Доступность проверяют на трёх уровнях. Статический анализ — eslint-plugin-jsx-a11y ловит <img> без alt, клик по <div>, неверные ARIA-атрибуты прямо в редакторе. Автоматические проверки в тестах — движок axe-core находит около трети–половины типовых проблем WCAG: контраст, отсутствующие подписи полей и доступные имена кнопок, дубли id, неправильные роли и вложенность, отсутствие lang; подключается в Vitest (vitest-axe/jest-axe), в Playwright (@axe-core/playwright), в Storybook (@storybook/addon-a11y) и в CI. Функциональные тесты доступности — то, что автоматика не может оценить: управление с клавиатуры (Tab-порядок, Enter/Space/Escape/стрелки), перемещение и возврат фокуса в диалогах, объявления aria-live, доступные имена через getByRole. И наконец ручная проверка со скринридером (NVDA, VoiceOver) для ключевых сценариев. Важно: «axe ничего не нашёл» не значит «доступно» — автоматические инструменты — нижняя планка.

Вопрос

Как автоматически тестировать доступность фронтенд-приложения? Что может проверить axe, а что нужно проверять отдельно?

Что ловит автоматика, а что нет

✓ axe находит✗ Нужно проверять тестами/вручную
Недостаточный контраст текстаЛогичный порядок фокуса
Поле без подписи, кнопка без имениПонятность текстов и подписей
<img> без altКорректность alt по смыслу
Неверные ARIA-роли и атрибутыРабота виджета с клавиатуры
Дубли id, пропуски уровней заголовков (best practice)Ловушка и возврат фокуса в модалке
Отсутствие lang, titleЧто озвучивает скринридер при изменениях
Интерактивные элементы внутри интерактивныхПоведение при увеличении до 200–400%

Vitest + vitest-axe

// vitest.setup.ts
import * as matchers from "vitest-axe/matchers";
import { expect } from "vitest";
expect.extend(matchers);
import { axe } from "vitest-axe";
 
it("форма входа не имеет нарушений доступности", async () => {
  const { container } = render(<LoginForm onSubmit={vi.fn()} />);
  expect(await axe(container)).toHaveNoViolations();
});
 
it("и в состоянии ошибки", async () => {
  const user = userEvent.setup();
  const { container } = render(<LoginForm onSubmit={vi.fn()} />);
  await user.click(screen.getByRole("button", { name: "Войти" }));
  expect(await axe(container)).toHaveNoViolations();     // проверяй разные состояния
});

В jsdom axe не может проверить контраст (нет реального рендеринга) — это делают в браузере: Playwright, Storybook, Vitest Browser Mode.

Playwright + @axe-core/playwright

import { test, expect } from "@playwright/test";
import AxeBuilder from "@axe-core/playwright";
 
test("страница каталога доступна", async ({ page }) => {
  await page.goto("/catalog/kettles");
  const results = await new AxeBuilder({ page })
    .withTags(["wcag2a", "wcag2aa", "wcag21a", "wcag21aa", "wcag22aa"])
    .exclude("#third-party-chat")                      // чужой виджет, который мы не контролируем
    .analyze();
  expect(results.violations).toEqual([]);
});
 
test("открытый диалог доступен", async ({ page }) => {
  await page.goto("/cart");
  await page.getByRole("button", { name: "Удалить «Чайник»" }).click();
  const results = await new AxeBuilder({ page }).include('[role="dialog"]').analyze();
  expect(results.violations).toEqual([]);
});

Удобно сделать фикстуру makeAxeBuilder с общими настройками и прогонять axe по списку ключевых страниц в одном тесте.

Клавиатура и фокус

test("модальное окно: фокус внутри, Escape закрывает, фокус возвращается", async ({ page }) => {
  await page.goto("/account/addresses");
  const trigger = page.getByRole("button", { name: "Добавить адрес" });
  await trigger.click();
 
  const dialog = page.getByRole("dialog", { name: "Новый адрес" });
  await expect(dialog.getByLabel("Город")).toBeFocused();       // фокус в первое поле
 
  for (let i = 0; i < 10; i++) await page.keyboard.press("Tab");
  await expect(dialog.locator(":focus")).toHaveCount(1);         // фокус не ушёл из диалога
 
  await page.keyboard.press("Escape");
  await expect(dialog).toBeHidden();
  await expect(trigger).toBeFocused();                           // фокус вернулся на кнопку
});
 
test("ссылка «Перейти к содержимому» работает", async ({ page }) => {
  await page.goto("/");
  await page.keyboard.press("Tab");
  await expect(page.getByRole("link", { name: "Перейти к основному содержимому" })).toBeFocused();
  await page.keyboard.press("Enter");
  await expect(page.locator("main")).toBeFocused();
});

Объявления для скринридеров

it("объявляет о добавлении в корзину", async () => {
  const user = userEvent.setup();
  render(<AddToCart product={product} />);
  await user.click(screen.getByRole("button", { name: "В корзину" }));
  expect(screen.getByRole("status")).toHaveTextContent("«Чайник» добавлен в корзину");  // role=status = aria-live polite
});

Доступность структуры: ARIA-снимки

await expect(page.getByRole("main")).toMatchAriaSnapshot(`
  - heading "Корзина" [level=1]
  - list:
    - listitem:
      - link "Электрический чайник Aqua"
      - spinbutton "Количество"
      - button "Удалить «Электрический чайник Aqua»"
  - button "Оформить заказ"
`);

Storybook

@storybook/addon-a11y запускает axe для каждой истории (вкладка Accessibility), а при запуске историй как тестов (Vitest-аддон) нарушения можно сделать ошибками: parameters: { a11y: { test: "error" } }. Так каждый компонент дизайн-системы автоматически проверяется во всех состояниях.

Ручная проверка (чек-лист)

  • Пройти ключевой сценарий только с клавиатуры.
  • Видимый фокус на каждом интерактивном элементе.
  • Скринридер (NVDA + Firefox/Chrome, VoiceOver + Safari) озвучивает элементы осмысленно.
  • Увеличение до 200% и ширина 320 px — без потери контента и горизонтального скролла.
  • prefers-reduced-motion и высокий контраст.

Что важно помнить

  • Три уровня: линтер → axe в тестах → функциональные тесты клавиатуры и фокуса (+ ручная проверка).
  • axe находит только часть проблем; отсутствие нарушений ≠ доступность.
  • Контраст проверяется только в реальном браузере.
  • Проверяй разные состояния: ошибки, открытые диалоги, меню.
  • getByRole в обычных тестах — уже проверка доступных имён.

Мини-шпаргалка

  • eslint-plugin-jsx-a11y.
  • expect(await axe(container)).toHaveNoViolations().
  • new AxeBuilder({ page }).withTags([...]).analyze() → violations.
  • toBeFocused, keyboard.press("Tab" | "Escape"), role="status".
  • Storybook addon-a11y, toMatchAriaSnapshot.

Документация

Дочитали до конца?
Отметьте урок — прогресс сохранится в браузере.

Поиск

Поиск по урокам