Тестирование доступности: 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.