Навигация

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

Доступность легко превратить в формальность: добавить eslint-plugin-jsx-a11y, запустить Lighthouse, увидеть 100 и решить, что работа сделана. Проблема в том, что автоматика проверяет только машинно-выводимые свойства разметки. Она не знает, что alt="фото" бесполезен, что фокус после закрытия диалога улетел в начало страницы и что ошибка формы читается дважды.

Эта статья — про практический слой: как встроить axe в компонентные и e2e-тесты, как проверять клавиатурные сценарии и состояния компонентов, как организовать ручной скрипт скринридера и где проходит граница автоматизации. Теория доступности и паттерны виджетов разобраны в WCAG 2.2 и ARIA-паттернах; здесь — как сделать так, чтобы регрессии ловились до релиза.

Содержание

  1. Глубокий разбор
  2. Практические примеры
  3. Типичные ошибки и антипаттерны
  4. Ключевые тезисы для интервью
  5. Практическое задание и code review-чеклист
  6. Заключение
  7. Полезные ссылки

Глубокий разбор

Что автоматика проверяет, а что нет

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([]);
});

Но зелёный тест может означать совсем не то, что кажется. Частые причины ложной уверенности:

  1. Проверяется только дефолтное состояние. Диалог закрыт, ошибок нет, меню не открыто — самые проблемные состояния не просканированы.
  2. Слишком широкий exclude. Если исключить весь layout или #app, axe не увидит ничего.
  3. Глобально отключённые правила. color-contrast: off «потому что шумит» скрывает реальные проблемы.
  4. Ожидание violations.length === 0 без учёта incomplete. Часть проверок axe не может завершить автоматически — их нужно смотреть руками.
  5. Сканирование до гидратации. React/Vue-приложение ещё не отрисовало интерактив, и axe проверяет пустой каркас.
  6. Отсутствие клавиатурных тестов. Даже идеальная разметка не гарантирует, что Tab и Esc работают.

Поэтому в проектном тесте лучше сразу закладывать:

  • сканирование после await expect(page.getByRole('main')).toBeVisible() и стабилизации интерфейса;
  • отдельные тесты для открытых overlays, ошибок формы и загрузки;
  • сохранение отчёта в артефакт, чтобы разбирать incomplete и passes;
  • проверку serious/critical как блокирующих, а minor/moderate — как предупреждений;
  • отдельный клавиатурный сценарий рядом с axe-тестом.

Тестирование клавиатуры

Клавиатурный тест — это не «нажать Tab и проверить, что что-то произошло». Это сценарий с ожидаемым фокусом на каждом шаге.

Что проверять в первую очередь:

  1. Skip link. Первый Tab с адресной строки переводит фокус на ссылку «К содержанию».
  2. Порядок фокуса. Он совпадает с визуальным и логическим порядком, без прыжков через всю страницу.
  3. Видимый фокус. У сфокусированного элемента есть заметный индикатор; в e2e это проверяют визуально или через toHaveScreenshot.
  4. Ловушки. Из каждого компонента можно выйти; модалка не выпускает фокус наружу, но и не запирает его навсегда.
  5. Overlay. Esc закрывает меню/диалог, фокус возвращается на триггер.
  6. Составные виджеты. Стрелки, Home/End, Enter/Space работают по APG-паттерну.
  7. 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
Disabledaria-disabled или нативный disabled, недоступность в Tab
Invalidaria-invalid, текст ошибки, aria-describedby
Loadingaria-busy, статус-регион, отсутствие ложных объявлений
EmptyПонятный текст, а не пустой контейнер
Open / closedaria-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), но основной сценарий остаётся ручным. Хороший скрипт выглядит как чек-лист с ожидаемыми объявлениями, а не как «посмотреть, всё ли ок».

Сценарий для формы:

  1. Открыть страницу и перейти по заголовкам (NVDA: H, VoiceOver: rotor → Headings).
  2. Проверить, что у каждого поля есть имя, тип и обязательность.
  3. Отправить пустую форму.
  4. Услышать error summary или первую ошибку, проверить, что фокус на проблеме.
  5. Вернуться к полю и услышать текст ошибки через aria-describedby.
  6. Исправить поле и убедиться, что ошибка исчезает и не читается повторно.

Сценарий для диалога:

  1. Открыть диалог с клавиатуры.
  2. Проверить, что скринридер объявляет роль dialog, имя из заголовка и описание.
  3. Убедиться, что фон не читается и не фокусируется.
  4. Закрыть по Esc и проверить возврат фокуса на триггер.

Сценарий для live-региона:

  1. Запустить асинхронный поиск.
  2. Услышать «Загрузка…», затем результат, без повторения на каждую букву.
  3. Проверить пустой результат и ошибку сети.

Фиксируйте результат в формате «шаг → ожидание → факт → severity». Это превращает субъективное «неудобно» в воспроизводимый дефект, который можно починить и проверить повторно.

CI: что блокирует merge, а что предупреждает

Разумная стратегия для команды:

  1. Линтер — блокирует merge, работает на каждом коммите.
  2. Компонентные axe-тесты — блокируют merge для дизайн-системы и ключевых компонентов.
  3. E2E axe-смоук — блокирует merge на 5–10 критичных маршрутах; остальное — nightly.
  4. Storybook a11y — блокирует merge для новых story с serious/critical.
  5. Ручной аудит — релизный чек-лист, а не CI.
  6. Скринридер — перед крупным релизом или изменением ключевого сценария.

Важно разделять 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-пирамиду для одного экрана

Возьмите форму оформления заказа или страницу настроек и сделайте четыре шага:

  1. Линтер. Подключите eslint-plugin-jsx-a11y или eslint-plugin-vuejs-accessibility и исправьте все предупреждения в затронутых компонентах.
  2. Компонентный тест. Напишите vitest-axe-тест для диалога и поля с ошибкой; проверьте открытое и невалидное состояния.
  3. E2E. Добавьте Playwright-тест: axe на странице, axe внутри открытого диалога, клавиатурный сценарий с Tab, Esc и возвратом фокуса.
  4. Ручной проход. Составьте скрипт на 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.

Полезные ссылки