Testowanie zgodności A11y

Twoja firma właśnie otrzymała pismo o niezgodności z ADA w Twojej aplikacji webowej. Zespół prawny jest zaniepokojony, a inżynieria odkrywa, że formularz rejestracji nie ma powiązanych etykiet, nawigacja jest nieużywalna z klawiatury, a kontrast kolorów na połowie przycisków call-to-action nie spełnia standardów WCAG AA. Dostępność to nie nice-to-have — to wymóg prawny i dyscyplina inżynierska, którą narzędzia AI mogą dramatycznie przyspieszyć.

Czego się nauczysz

• Zautomatyzowane testowanie zgodności WCAG 2.2 AA zintegrowane z Twoim pipeline’em CI
• Audyt dostępności wspomagany AI, który wyjaśnia naruszenia i generuje poprawki
• Wzorce testów dostępności oparte na Playwright dla flowów E2E
• Workflow testowania nawigacji klawiaturowej i czytników ekranu
• Prompty generujące dostępny kod od samego początku

Automatyczny audyt WCAG

Używanie axe-core z analizą AI

Cursor

Set up automated accessibility testing for our Next.js application:

1. Install @axe-core/playwright for Playwright integration
2. Create an accessibility test helper at /tests/a11y/audit-helper.ts that:
   - Runs axe-core on any page
   - Filters results by WCAG 2.2 AA criteria
   - Categorizes violations by severity (critical, serious, moderate, minor)
   - Generates fix suggestions for each violation

3. Create accessibility tests for our critical pages:
   - /tests/a11y/pages/homepage.a11y.spec.ts
   - /tests/a11y/pages/login.a11y.spec.ts
   - /tests/a11y/pages/dashboard.a11y.spec.ts
   - /tests/a11y/pages/settings.a11y.spec.ts

4. Each test should:
   - Run the full axe audit
   - Fail on critical and serious violations
   - Report moderate violations as warnings
   - Test at both desktop and mobile viewports

Follow our Playwright config in playwright.config.ts

Claude Code

claude "Set up accessibility testing infrastructure:

1. Install: npm install -D @axe-core/playwright
2. Create /tests/a11y/run-audit.ts:
   - Accept a URL and Playwright page
   - Run axe-core with WCAG 2.2 AA rules
   - Return structured results with fix suggestions
3. Create tests for all routes in our application:
   - Discover routes from /src/pages/ directory
   - Generate an a11y test for each page
   - Save to /tests/a11y/pages/
4. Run all accessibility tests
5. Generate a compliance report at /docs/a11y-report.md

For each violation found, include:
- The WCAG criterion it violates
- The HTML element causing the violation
- A specific code fix"

Codex

Set up WCAG 2.2 AA compliance testing:
1. Add axe-core to our Playwright test infrastructure
2. Create accessibility tests for every page
3. Run the audit and generate a compliance report
4. Create fixes for any critical violations found
5. Create a PR with tests, fixes, and the compliance report

Wskazówka

Prompt do skopiowania — audyt dostępności i poprawki:

Run an accessibility audit on our React component library (/src/components/ui/).

For each component, check:
1. Do all interactive elements have accessible names? (buttons, links, inputs)
2. Do all form inputs have associated labels? (not just placeholder text)
3. Do all images have meaningful alt text? (or alt="" for decorative)
4. Are ARIA roles used correctly? (no redundant roles on semantic HTML)
5. Is the focus order logical? (follows visual layout)
6. Do custom components (dropdowns, modals, tabs) have correct ARIA patterns?
7. Are color contrast ratios at least 4.5:1 for text and 3:1 for large text?

For each violation:
- Show the current code
- Show the fixed code
- Explain which WCAG criterion it violates and why it matters

Testowanie nawigacji klawiaturowej

Wskazówka

Prompt do skopiowania — testy nawigacji klawiaturowej:

Generate Playwright tests that verify keyboard navigation for our application:

1. Tab order test:
   - Start at the top of the page
   - Tab through every interactive element
   - Verify the focus order matches visual order
   - Verify no elements are skipped
   - Verify focus is visible on every element

2. Modal keyboard trap:
   - Open a modal dialog
   - Verify focus moves to the modal
   - Tab should cycle within the modal (not escape to the page behind)
   - Escape key should close the modal
   - Focus should return to the trigger element

3. Form navigation:
   - Tab through all form fields
   - Enter should submit the form
   - Error messages should be announced (use aria-live or role="alert")
   - Required field indicators should be accessible

4. Dropdown/menu navigation:
   - Arrow keys navigate between items
   - Enter/Space selects an item
   - Escape closes the dropdown
   - Home/End jump to first/last item

Save to /tests/a11y/keyboard-navigation.spec.ts

Generowanie dostępnego kodu od początku

Zamiast audytować i naprawiać, generuj dostępny kod od razu.

Wskazówka

Prompt do skopiowania — generowanie dostępnego komponentu:

Create an accessible dropdown select component for React (TypeScript):

Requirements:
- Follows the ARIA combobox pattern (WAI-ARIA 1.2)
- Keyboard navigation: Arrow Up/Down to navigate, Enter to select, Escape to close
- Screen reader announcements for: opening, closing, selection changes, option count
- Visual focus indicator that meets WCAG 2.2 AA (3:1 contrast, 2px minimum)
- Support for grouped options with group labels
- Support for disabled options
- Search/filter functionality with aria-live announcements

Do NOT use a native select element - this is a custom implementation.
Include all ARIA attributes: role, aria-expanded, aria-activedescendant,
aria-haspopup, aria-label, aria-selected, aria-disabled.

Include a Storybook story showing all states: default, open, with selection,
disabled, with groups, with search.
Include unit tests that verify ARIA attribute states change correctly.

Integracja z CI dla dostępności

1. Uruchamiaj axe-core na każdym PR

   Dodaj testowanie dostępności do pipeline’u CI. Failuj build na krytycznych i poważnych naruszeniach.

2. Śledź zgodność w czasie

   Przechowuj wyniki audytu i monitoruj trendy. Twój wskaźnik zgodności powinien rosnąć z czasem, nie spadać.

3. Zapobiegaj nowym naruszeniom

   Najważniejsza bramka: żadnych nowych krytycznych ani poważnych naruszeń dostępności w żadnym PR. Istniejące naruszenia mogą być śledzone w backlogu.

4. Cotygodniowy raport dostępności

   Generuj raport pokazujący: całkowite naruszenia według poziomu istotności, nowe naruszenia w tym tygodniu, rozwiązane naruszenia, procent zgodności według strony.

Gdy coś się zepsuje

“axe-core raportuje setki naruszeń i to przytłaczające.” Zacznij od naprawienia tylko naruszeń krytycznych. To te, które całkowicie blokują użytkowników przed dostępem do treści. Potem przejdź do poważnych, następnie umiarkowanych. Nie próbuj naprawiać wszystkiego naraz.

“AI generuje dostępny kod, ale wygląda inaczej niż nasz design system.” Dodaj ograniczenia design systemu do prompta: “Use our existing color palette. Focus indicator must be our brand blue (#2563eb) with a 2px offset.” Dostępny nie oznacza brzydki — oznacza celowy.

“Testowanie z czytnikami ekranu jest ręczne i wolne.” Zautomatyzowane testy łapią 30-40% problemów z dostępnością. Reszta wymaga ręcznego testowania z czytnikami ekranu (VoiceOver, NVDA). Użyj AI do wygenerowania ręcznej listy kontrolnej testów dla QA, skupiając się na interakcjach, które zautomatyzowane narzędzia pomijają.

“Deweloperzy nie wiedzą wystarczająco dużo o dostępności, żeby naprawiać naruszenia.” Prompty AI w tym przewodniku generują zarówno poprawkę, jak i wyjaśnienie. Deweloperzy uczą się dostępności naprawiając prawdziwe naruszenia z kontekstem, nie czytając dokumentację.

Co dalej

E2E Testing Integrate accessibility checks into your E2E test flows.

Mobile Testing Accessibility testing on mobile platforms.

Code Quality Add accessibility as a quality gate in your pipeline.