Тестирование доступности: axe, Playwright и скринридеры
Доступность легко превратить в формальность: добавить eslint-plugin-jsx-a11y, запустить Lighthouse, увидеть 100 и решить, что работа сделана. Проблема в том, что автоматика проверяет только машинно-выводимые свойства разметки. Она не знает, что alt="фото" бесполезен, что фокус после закрытия диалога улетел в начало страницы и что ошибка формы читается дважды.
Эта статья — про практический слой: как встроить axe в компонентные и e2e-тесты, как проверять клавиатурные сценарии и состояния компонентов, как организовать ручной скрипт скринридера и где проходит граница автоматизации. Теория доступности и паттерны виджетов разобраны в WCAG 2.2 и ARIA-паттернах; здесь — как сделать так, чтобы регрессии ловились до релиза.
Содержание
- Глубокий разбор
- Практические примеры
- Типичные ошибки и антипаттерны
- Ключевые тезисы для интервью
- Практическое задание и code review-чеклист
- Заключение
- Полезные ссылки
Глубокий разбор
Что автоматика проверяет, а что нет
axe-core — движок правил, который анализирует DOM, вычисленные стили и ARIA-атрибуты. Он умеет находить:
- отсутствующее доступное имя у кнопок, ссылок и полей;
- отсутствующий
altилиalt, дублирующий имя файла; - невалидные роли и атрибуты, ARIA-связи на несуществующие id;
aria-hiddenна фокусируемых элементах;- часть проблем контраста текста;
- отсутствие
<html lang>,<title>, корректной структуры заголовков и landmarks; - дублирующиеся id, неверный порядок
tabindexв некоторых случаях; - проблемы таблиц: отсутствие
<th>,scope,<caption>.
Чего axe не умеет:
- понимать смысл текста:
alt="image1"формально валиден; - проверять логичность порядка фокуса и удобство клавиатурного сценария;
- слышать, что реально произносит NVDA или VoiceOver;
- оценивать читаемость, когнитивную нагрузку и визуальный ритм;
- проверять reflow при 400% zoom и перекрытие фокуса sticky-хедером;
- видеть проблемы в закрытых состояниях, которые ещё не отрендерены;
- гарантировать, что пользователь может выполнить задачу.
Отсюда практическое правило: axe — это линтер доступности, а не тест доступности. Он ловит дешёвые и частые дефекты, освобождая время для ручной проверки. По разным оценкам, автоматика обнаруживает порядка 30–50% проблем WCAG; точная цифра зависит от продукта, но порядок именно такой.
Уровни тестирования доступности
Строить проверки стоит слоями, как и обычные тесты:
| Уровень | Инструмент | Что ловит | Скорость |
|---|---|---|---|
| Линтер | eslint-plugin-jsx-a11y, eslint-plugin-vuejs-accessibility | Статически очевидные ошибки в JSX/шаблонах | Миллисекунды |
| Компонентный | vitest-axe / jest-axe + Testing Library / VTU | Разметка и ARIA в изоляции, регрессия пропсов | Секунды |
| Storybook | @storybook/addon-a11y | Все состояния story, axe в браузере | Секунды на story |
| E2E | @axe-core/playwright | Реальная страница, контраст, состояния после взаимодействия | Минуты |
| Визуальный | Chromatic, Percy, Playwright screenshots | Регрессия внешнего вида, включая focus/error/dark | Минуты |
| Ручной | Клавиатура, NVDA, VoiceOver, TalkBack | Порядок, объявления, смысл, удобство | Часы |
На интервью важно не перечислить инструменты, а объяснить, какой класс дефектов закрывает каждый уровень и почему одного недостаточно.
axe в Playwright: как не получить ложную уверенность
Базовый тест выглядит просто:
import { test, expect } from '@playwright/test';
import AxeBuilder from '@axe-core/playwright';
test('страница без нарушений WCAG A/AA', async ({ page }) => {
await page.goto('/checkout');
const results = await new AxeBuilder({ page })
.withTags(['wcag2a', 'wcag2aa', 'wcag21a', 'wcag21aa', 'wcag22aa'])
.analyze();
expect(results.violations).toEqual([]);
});
Но зелёный тест может означать совсем не то, что кажется. Частые причины ложной уверенности:
- Проверяется только дефолтное состояние. Диалог закрыт, ошибок нет, меню не открыто — самые проблемные состояния не просканированы.
- Слишком широкий
exclude. Если исключить весь layout или#app, axe не увидит ничего. - Глобально отключённые правила.
color-contrast: off«потому что шумит» скрывает реальные проблемы. - Ожидание
violations.length === 0без учётаincomplete. Часть проверок axe не может завершить автоматически — их нужно смотреть руками. - Сканирование до гидратации. React/Vue-приложение ещё не отрисовало интерактив, и axe проверяет пустой каркас.
- Отсутствие клавиатурных тестов. Даже идеальная разметка не гарантирует, что
TabиEscработают.
Поэтому в проектном тесте лучше сразу закладывать:
- сканирование после
await expect(page.getByRole('main')).toBeVisible()и стабилизации интерфейса; - отдельные тесты для открытых overlays, ошибок формы и загрузки;
- сохранение отчёта в артефакт, чтобы разбирать
incompleteиpasses; - проверку
serious/criticalкак блокирующих, аminor/moderate— как предупреждений; - отдельный клавиатурный сценарий рядом с axe-тестом.
Тестирование клавиатуры
Клавиатурный тест — это не «нажать Tab и проверить, что что-то произошло». Это сценарий с ожидаемым фокусом на каждом шаге.
Что проверять в первую очередь:
- Skip link. Первый
Tabс адресной строки переводит фокус на ссылку «К содержанию». - Порядок фокуса. Он совпадает с визуальным и логическим порядком, без прыжков через всю страницу.
- Видимый фокус. У сфокусированного элемента есть заметный индикатор; в e2e это проверяют визуально или через
toHaveScreenshot. - Ловушки. Из каждого компонента можно выйти; модалка не выпускает фокус наружу, но и не запирает его навсегда.
- Overlay.
Escзакрывает меню/диалог, фокус возвращается на триггер. - Составные виджеты. Стрелки,
Home/End,Enter/Spaceработают по APG-паттерну. - Roving tabindex. В группе одна остановка
Tab, а не по одной на каждый элемент.
В Playwright это выглядит так:
test('диалог удерживает и возвращает фокус', async ({ page }) => {
await page.goto('/settings');
const trigger = page.getByRole('button', { name: 'Настройки' });
await trigger.click();
const dialog = page.getByRole('dialog', { name: 'Настройки уведомлений' });
await expect(dialog).toBeVisible();
await expect(page.getByRole('button', { name: 'Отмена' })).toBeFocused();
// Уходим на последний элемент и проверяем цикл
await page.getByRole('button', { name: 'Сохранить' }).focus();
await page.keyboard.press('Tab');
await expect(page.getByRole('button', { name: 'Отмена' })).toBeFocused();
await page.keyboard.press('Escape');
await expect(dialog).toBeHidden();
await expect(trigger).toBeFocused();
});
Важно: focus() в тесте — это подготовка состояния, а не проверка пользовательского пути. Основной сценарий должен идти через Tab и стрелки, иначе тест не поймает сломанный порядок.
Для tabs:
test('tabs: стрелки, Home/End и aria-selected', async ({ page }) => {
await page.goto('/profile');
const profile = page.getByRole('tab', { name: 'Профиль' });
const security = page.getByRole('tab', { name: 'Безопасность' });
const notifications = page.getByRole('tab', { name: 'Уведомления' });
await profile.focus();
await page.keyboard.press('ArrowRight');
await expect(security).toBeFocused();
await expect(security).toHaveAttribute('aria-selected', 'true');
await page.keyboard.press('End');
await expect(notifications).toBeFocused();
await page.keyboard.press('Home');
await expect(profile).toBeFocused();
// Вся группа — одна остановка Tab
await page.keyboard.press('Tab');
await expect(profile).not.toBeFocused();
});
Для combobox:
test('combobox: activedescendant и выбор с клавиатуры', async ({ page }) => {
await page.goto('/search');
const input = page.getByRole('combobox', { name: 'Город' });
await input.fill('Моск');
const listbox = page.getByRole('listbox', { name: 'Города' });
await expect(listbox).toBeVisible();
await page.keyboard.press('ArrowDown');
const activeId = await input.getAttribute('aria-activedescendant');
expect(activeId).toBeTruthy();
await expect(page.locator(`#${activeId}`)).toHaveAttribute('aria-selected', 'true');
await page.keyboard.press('Enter');
await expect(input).toHaveValue('Москва');
await expect(listbox).toBeHidden();
});
Состояния компонента — часть тестового контракта
Одна из самых частых ошибок — тестировать только «счастливый путь». Для UI-компонента матрица состояний выглядит так:
| Состояние | Что проверять |
|---|---|
| Default | Роль, имя, базовые стили и фокус |
| Hover / focus / active | Видимый фокус, контраст, отсутствие layout shift |
| Disabled | aria-disabled или нативный disabled, недоступность в Tab |
| Invalid | aria-invalid, текст ошибки, aria-describedby |
| Loading | aria-busy, статус-регион, отсутствие ложных объявлений |
| Empty | Понятный текст, а не пустой контейнер |
| Open / closed | aria-expanded, видимость, фокус, Esc |
| Dark theme | Контраст и границы, а не только фон |
| RTL | Порядок, стрелки, логические свойства |
| Zoom 200–400% | Reflow, отсутствие обрезки |
| Forced colors | Границы и состояния не только цветом |
В Storybook это превращается в набор story на каждое состояние, а в e2e — в отдельные тесты открытого диалога, невалидной формы и загрузки. Если состояние нельзя воспроизвести в тесте, оно, скорее всего, не покрыто и в дизайн-системе.
Storybook addon-a11y и Chromatic
@storybook/addon-a11y запускает axe внутри preview-iframe и показывает нарушения в панели. В связке с @storybook/test-runner или Chromatic это даёт регрессию по каждой story:
- компонент проверяется в изоляции, без логина и окружения;
- матрица вариантов (size, variant, state, theme) покрывается дешевле, чем e2e;
- нарушения видны дизайнеру и разработчику в привычном интерфейсе;
- Chromatic может сравнивать не только скриншоты, но и a11y-результаты между сборками.
Ограничения те же: addon не проверяет клавиатуру, порядок фокуса и объявления скринридера. Он также может давать ложные срабатывания на контраст в историях с фоновыми изображениями и градиентами. Поэтому story-тесты — это быстрый уровень, а не замена e2e и ручному аудиту.
Компонентные тесты: vitest-axe
vitest-axe (или jest-axe) добавляет матчер toHaveNoViolations и работает в jsdom. Пример для React Testing Library:
import { render, screen } from '@testing-library/react';
import { axe } from 'vitest-axe';
import * as matchers from 'vitest-axe/matchers';
import { expect, test } from 'vitest';
import { Dialog } from './Dialog';
expect.extend(matchers);
test('Dialog без нарушений в открытом состоянии', async () => {
render(
<Dialog open title="Удалить файл?">
<p>Файл будет удалён без возможности восстановления.</p>
<button>Отмена</button>
<button>Удалить</button>
</Dialog>,
);
expect(await axe(screen.getByRole('dialog'))).toHaveNoViolations();
});
Для Vue Test Utils:
import { mount } from '@vue/test-utils';
import { axe } from 'vitest-axe';
import * as matchers from 'vitest-axe/matchers';
import { expect, test } from 'vitest';
import Dialog from './Dialog.vue';
expect.extend(matchers);
test('Dialog без нарушений в открытом состоянии', async () => {
const wrapper = mount(Dialog, {
props: { open: true, title: 'Удалить файл?' },
attachTo: document.body,
});
expect(await axe(wrapper.element)).toHaveNoViolations();
});
Что важно:
attachTo: document.bodyдля Vue нужен, чтобы компонент был в документе и axe видел вычисленные связи.- Проверяйте открытое состояние, а не только закрытое:
v-ifможет не отрендерить содержимое. - jsdom не считает контраст и layout, поэтому цветовые проверки остаются браузеру.
vitest-axeне работает вhappy-domиз-за проблем сNode.prototype.isConnected; используйте окружениеjsdom.- Не снимайте все правила, если тест падает: сначала разберитесь, реальный это дефект или ограничение jsdom.
Ручной скрипт скринридера
Автоматизировать скринридер можно частично (есть экспериментальные инструменты вроде Guidepup), но основной сценарий остаётся ручным. Хороший скрипт выглядит как чек-лист с ожидаемыми объявлениями, а не как «посмотреть, всё ли ок».
Сценарий для формы:
- Открыть страницу и перейти по заголовкам (NVDA:
H, VoiceOver: rotor → Headings). - Проверить, что у каждого поля есть имя, тип и обязательность.
- Отправить пустую форму.
- Услышать error summary или первую ошибку, проверить, что фокус на проблеме.
- Вернуться к полю и услышать текст ошибки через
aria-describedby. - Исправить поле и убедиться, что ошибка исчезает и не читается повторно.
Сценарий для диалога:
- Открыть диалог с клавиатуры.
- Проверить, что скринридер объявляет роль
dialog, имя из заголовка и описание. - Убедиться, что фон не читается и не фокусируется.
- Закрыть по
Escи проверить возврат фокуса на триггер.
Сценарий для live-региона:
- Запустить асинхронный поиск.
- Услышать «Загрузка…», затем результат, без повторения на каждую букву.
- Проверить пустой результат и ошибку сети.
Фиксируйте результат в формате «шаг → ожидание → факт → severity». Это превращает субъективное «неудобно» в воспроизводимый дефект, который можно починить и проверить повторно.
CI: что блокирует merge, а что предупреждает
Разумная стратегия для команды:
- Линтер — блокирует merge, работает на каждом коммите.
- Компонентные axe-тесты — блокируют merge для дизайн-системы и ключевых компонентов.
- E2E axe-смоук — блокирует merge на 5–10 критичных маршрутах; остальное — nightly.
- Storybook a11y — блокирует merge для новых story с
serious/critical. - Ручной аудит — релизный чек-лист, а не CI.
- Скринридер — перед крупным релизом или изменением ключевого сценария.
Важно разделять severity и уверенность. critical и serious от axe обычно реальные дефекты и должны блокировать. moderate и minor стоит показывать как предупреждения, иначе команда привыкнет игнорировать красный CI. incomplete требует ручного разбора: axe не смог определить контраст из-за фонового изображения или градиента.
Границы автоматизации
Автотесты никогда не ответят на вопросы:
- Понятен ли
altи текст ошибки человеку? - Логичен ли порядок фокуса для конкретного сценария?
- Удобно ли пользоваться combobox с клавиатуры, а не просто «работает ли Enter»?
- Не перебивает ли
aria-liveпользователя? - Читается ли интерфейс при 400% zoom и в forced-colors?
- Не перекрывает ли sticky-хедер сфокусированный элемент?
- Доступен ли сценарий человеку с тремором, дислексией или мигренью?
Эти вопросы решаются ручным аудитом, тестированием с людьми и дизайн-ревью. Автоматика лишь гарантирует, что уже найденные дефекты не вернутся.
Практические примеры
Пример 1. Полноценный axe-тест с артефактом и фильтром severity
import { test, expect } from '@playwright/test';
import AxeBuilder from '@axe-core/playwright';
const BLOCKING = new Set(['serious', 'critical']);
test.describe('a11y: checkout', () => {
test('страница и открытый диалог', async ({ page }, testInfo) => {
await page.goto('/checkout');
await expect(page.getByRole('main')).toBeVisible();
const pageResults = await new AxeBuilder({ page })
.withTags(['wcag2a', 'wcag2aa', 'wcag21aa', 'wcag22aa'])
.analyze();
await testInfo.attach('axe-checkout.json', {
body: JSON.stringify(pageResults, null, 2),
contentType: 'application/json',
});
const blocking = pageResults.violations.filter((v) => BLOCKING.has(v.impact ?? ''));
expect(blocking, JSON.stringify(blocking, null, 2)).toEqual([]);
await page.getByRole('button', { name: 'Промокод' }).click();
const dialog = page.getByRole('dialog', { name: 'Промокод' });
await expect(dialog).toBeVisible();
const dialogResults = await new AxeBuilder({ page })
.include('[role="dialog"]')
.withTags(['wcag2a', 'wcag2aa', 'wcag21aa', 'wcag22aa'])
.analyze();
await testInfo.attach('axe-promo-dialog.json', {
body: JSON.stringify(dialogResults, null, 2),
contentType: 'application/json',
});
expect(dialogResults.violations.filter((v) => BLOCKING.has(v.impact ?? ''))).toEqual([]);
});
});
Почему так:
- артефакт сохраняет полный отчёт, включая
incompleteиpasses; - блокируются только
serious/critical, чтобы CI не тонул в мелочах; - открытый диалог сканируется отдельно, потому что его нет в дефолтном DOM;
include('[role="dialog"]')сужает область и ускоряет проверку.
Если нужно исключить сторонний виджет, делайте это точечно и с комментарием:
const results = await new AxeBuilder({ page })
.exclude('[data-third-party-chat]') // виджет без доступа к разметке, issue #123
.withTags(['wcag2a', 'wcag2aa'])
.analyze();
Пример 2. Клавиатурный сценарий для формы с ошибками
import { test, expect } from '@playwright/test';
test('форма: ошибки, фокус и aria-invalid', async ({ page }) => {
await page.goto('/signup');
await page.getByRole('button', { name: 'Создать аккаунт' }).click();
const summary = page.getByRole('group', { name: 'Проверьте поля' });
await expect(summary).toBeVisible();
await expect(summary).toBeFocused();
const email = page.getByLabel('Email');
await expect(email).toHaveAttribute('aria-invalid', 'true');
await expect(email).toHaveAccessibleDescription(/name@example\.com/);
await page.keyboard.press('Tab');
await expect(page.getByLabel('Пароль')).toBeFocused();
await email.fill('user@example.com');
await email.blur();
await expect(email).not.toHaveAttribute('aria-invalid', 'true');
});
Что проверяется:
- ошибка появляется после submit, а не при загрузке;
- фокус уходит на summary;
- поле связано с текстом ошибки через
aria-describedby; - после исправления состояние снимается.
toHaveAccessibleDescription — хороший пример проверки, которая ближе к тому, что слышит пользователь, чем проверка наличия атрибута.
Пример 3. Story-тест с addon-a11y и матрицей состояний
// Button.stories.tsx
import type { Meta, StoryObj } from '@storybook/react';
import { Button } from './Button';
const meta = {
title: 'Components/Button',
component: Button,
parameters: {
a11y: {
// В Storybook 8+ можно сделать нарушения ошибкой в test-runner
test: 'error',
},
},
} satisfies Meta<typeof Button>;
export default meta;
type Story = StoryObj<typeof meta>;
export const Default: Story = {
args: { children: 'Сохранить' },
};
export const Disabled: Story = {
args: { children: 'Сохранить', disabled: true },
};
export const Loading: Story = {
args: { children: 'Сохранить', loading: true },
};
export const Danger: Story = {
args: { children: 'Удалить', variant: 'danger' },
};
В Storybook панель Accessibility покажет нарушения для каждой story, а test-runner или Chromatic превратит это в гейт. Матрица Default/Disabled/Loading/Danger важна потому, что контраст и имена часто ломаются именно в неосновных вариантах.
Пример 4. Ручной скрипт для NVDA и VoiceOver
# A11y smoke: оформление заказа
Окружение: Chrome + NVDA 2025.x, Safari + VoiceOver (macOS 15).
Время: 15 минут.
1. Загрузка страницы.
Ожидание: заголовок «Оформление заказа», один main, есть skip link.
Факт: ...
2. Навигация по заголовкам (NVDA: H, VoiceOver: rotor → Headings).
Ожидание: h1 → h2 «Контакты» → h2 «Доставка» → h2 «Оплата».
Факт: ...
3. Поле «Email».
Ожидание: «Email, редактируемое поле, обязательно».
Факт: ...
4. Submit с пустыми полями.
Ожидание: error summary, фокус на нём, перечислены поля.
Факт: ...
5. Открыть «Промокод».
Ожидание: dialog «Промокод», фон не читается, Esc возвращает фокус.
Факт: ...
6. Применить промокод.
Ожидание: status «Промокод применён», без повторного чтения всей формы.
Факт: ...
Скрипт хранится в docs/qa/a11y-checkout.md или рядом с e2e-тестами. Его можно передать другому разработчику, и результат будет сопоставим.
Пример 5. CI-workflow: быстрый и полный прогон
# .github/workflows/a11y.yml
name: a11y
on:
pull_request:
schedule:
- cron: '0 3 * * *'
jobs:
component-a11y:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: 22
cache: npm
- run: npm ci
- run: npm run test:unit -- --run
env:
A11Y_MODE: strict
e2e-a11y:
if: github.event_name == 'schedule'
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: 22
cache: npm
- run: npm ci
- run: npx playwright install --with-deps chromium
- run: npm run test:e2e -- --grep "@a11y"
- uses: actions/upload-artifact@v4
if: always()
with:
name: axe-reports
path: test-results/**/axe-*.json
Идея: компонентные проверки — на каждый PR, полный e2e-аудит — nightly или перед релизом. Это баланс между скоростью обратной связи и стоимостью прогона.
Типичные ошибки и антипаттерны
- «Lighthouse 100 — значит доступно». Оценка не покрывает клавиатуру, скринридер и смысл; 100 — это только отсутствие части машинных нарушений.
- Один axe-тест на главную страницу. Все остальные маршруты и состояния остаются непроверенными.
- Сканирование только закрытых компонентов. Диалоги, меню и ошибки формы появляются после взаимодействия — их нужно проверять отдельно.
- Глобальное отключение
color-contrast. Скрывает реальные проблемы; отключайте точечно и с обоснованием. excludeна весь layout. Тест зелёный, потому что ничего не проверяет.- Ожидание только
violations.length === 0.incompleteи предупреждения остаются без разбора. - Исправление axe через
aria-hidden. Маскирует симптом и создаёт фантомные фокусы; чините причину. - Тест клавиатуры без проверки фокуса. «Нажали Tab» ничего не доказывает, если не проверено, куда он пришёл.
- Проверка только мышиных сценариев. Основной пользователь клавиатуры остаётся без покрытия.
- Один тест на все состояния. Loading, error, disabled и dark theme ломаются чаще, чем default.
- Скринридер «на глаз». Без скрипта и ожидаемых объявлений результат нельзя воспроизвести и сравнить.
- Автоматизация скринридера как замена ручной проверки. Инструменты нестабильны и не покрывают реальные режимы AT.
- Игнорирование
forced-colorsи zoom. Эти режимы часто ломают границы, иконки и layout. - Тесты только для дизайн-системы. Страницы, собранные из компонентов, могут ломать связи и порядок.
- Красный CI из-за
minor. Команда привыкает игнорировать сигнал; разделяйте severity. - Нет артефактов. Без отчёта невозможно понять, что именно нашёл axe и что осталось в
incomplete.
Ключевые тезисы для интервью
- axe — линтер, а не тест доступности. Он ловит машинно-выводимые нарушения и не заменяет клавиатуру, скринридер и смысловую проверку.
- Тестирование строится слоями. Линтер → компонентные axe-тесты → Storybook → e2e → визуальная регрессия → ручной аудит.
- Состояния — часть контракта компонента. Default, open, error, loading, disabled, dark, RTL и zoom проверяются отдельно.
- Клавиатурный тест проверяет фокус, а не факт нажатия.
toBeFocused,aria-selected,aria-activedescendantи возврат фокуса — обязательные ожидания. - Focus trap тестируется переходом через границу. С последнего элемента
Tabведёт к первому,Shift+Tab— обратно. - Playwright + axe проверяет реальный браузер. Компонентный
vitest-axeбыстрее, но не видит контраст и layout. - Storybook addon-a11y масштабирует проверку дизайн-системы. Он дешёвый, но не проверяет клавиатуру и объявления.
- Ручной скрипт скринридера должен быть воспроизводимым. Ожидание → факт → severity, а не субъективное «неудобно».
incompleteтребует ручного разбора. Автоматика не всегда может вычислить контраст на градиенте или изображении.- CI должен разделять severity.
serious/criticalблокируют,minor/moderateпредупреждают, e2e-аудит идёт nightly. - Автотесты не заменяют пользователей. Смысл, порядок, когнитивная нагрузка и удобство проверяются людьми.
Практическое задание и code review-чеклист
Задание: построить a11y-пирамиду для одного экрана
Возьмите форму оформления заказа или страницу настроек и сделайте четыре шага:
- Линтер. Подключите
eslint-plugin-jsx-a11yилиeslint-plugin-vuejs-accessibilityи исправьте все предупреждения в затронутых компонентах. - Компонентный тест. Напишите
vitest-axe-тест для диалога и поля с ошибкой; проверьте открытое и невалидное состояния. - E2E. Добавьте Playwright-тест: axe на странице, axe внутри открытого диалога, клавиатурный сценарий с
Tab,Escи возвратом фокуса. - Ручной проход. Составьте скрипт на 10 шагов для NVDA/VoiceOver, пройдите его и запишите три дефекта с severity.
Результат: набор тестов, который падает при регрессии, и список проблем, которые автоматика не увидела.
Чек-лист code review тестов доступности
- axe запускается после стабилизации интерфейса, а не до гидратации.
- Проверены открытые overlays, ошибки формы и загрузка, а не только default.
-
serious/criticalблокируют merge;minor/moderateне создают шум. - Полный отчёт сохраняется артефактом,
incompleteразобран. -
excludeиdisableRulesточечные, с комментарием и ссылкой на issue. - Есть клавиатурный тест с
toBeFocused, а не только с нажатиями. - Проверены
Tab,Shift+Tab, стрелки,Home/End,Enter/Space,Esc. - Проверен возврат фокуса после закрытия диалога/меню.
- Проверен roving tabindex: одна остановка
Tabна группу. - Проверен
aria-activedescendantв combobox и выбранный вариант. - Есть тест на
aria-invalidиaria-describedbyв форме. - Storybook-матрица покрывает default, disabled, loading, error, dark и RTL.
- Storybook a11y-тест включён в CI или Chromatic.
- Есть воспроизводимый ручной скрипт для NVDA/VoiceOver.
- Проверены zoom 200–400%,
forced-colorsиprefers-reduced-motion. - Тест не маскирует проблему через
aria-hiddenили отключение правила.
Заключение
Тестирование доступности — это не один инструмент, а система уровней. Линтер ловит очевидное в коде, vitest-axe — разметку компонента, Storybook — матрицу состояний, Playwright — реальную страницу и клавиатурные сценарии, а ручной аудит — смысл и удобство. Если оставить только axe, команда получит зелёный CI и непроверенные диалоги, формы и объявления.
Для UI Engineer важна не столько настройка конкретного пакета, сколько понимание границ: что автоматика доказывает, а что нет. Хороший тест доступности падает при реальной регрессии, сохраняет отчёт для разбора и не превращает minor в блокер. А главное — он не отменяет необходимости пройти интерфейс клавиатурой и послушать его скринридером.
Продолжение практики — ARIA-паттерны и клавиатурное взаимодействие, Визуальное тестирование и E2E с Playwright. Vue-специфика доступности — в Доступные компоненты во Vue.