accessibility-testing

Files (1)

• SKILL.md

SKILL.md (first lines)

<objective>
Test applications for accessibility to ensure they are usable by everyone, including people who use assistive technologies. Automated tools catch 30-40% of accessibility issues -- the rest requires manual testing with keyboard navigation, screen readers, and human judgment. This skill covers both approaches.
</objective>

---

## Discovery Questions

Before designing an accessibility testing strategy, understand the requirements and current state. Check `.agents/qa-project-context.md` first -- if it exists, use it as the foundation and skip questions already answered there.

### Requirements and Compliance
- What WCAG conformance level is required? (A, AA, or AAA)
- What legal requirements apply? (ADA, EAA/EN 301 549, Section 508, AODA)
- Are there contractual accessibility requirements from customers? (common in enterprise/government)
- Is there a Voluntary Product Accessibility Template (VPAT) to maintain?

### Current State
- Has an accessibility audit been performed before? What were the findings?
- Are there known accessibility issues in the backlog?
- Does the design system include accessibility guidelines?

### Testing Infrastructure
- Is automated accessibility testing integrated into CI?
- Which screen readers does the team test with? (VoiceOver, NVDA, JAWS, TalkBack)
- What browsers and devices must be accessible?

---

## Core Principles

### 1. Automated Testing Catches 30-40% of Issues
Tools like axe-core can detect missing alt text, insufficient color contrast, missing form labels, and invalid ARIA attributes. They cannot detect whether alt text is meaningful, whether the tab order is logical, whether a custom widget is operable by keyboard, or whether the reading order makes sense. Both automated and manual testing are essential.

### 2. Semantic HTML First, ARIA as Last Resort
Native HTML elements (`<button>`, `<nav>`, `<input>`, `<table>`, `<dialog>`) carry built-in accessibility semantics, keyboard behavior, and screen reader support. Adding `role="button"` to a `<div>` requires also adding `tabindex`, `keydown` handlers for Enter and Space, focus styles, and ARIA states. Use the native element. Reach for ARIA only when no native element exists for the pattern.

### 3. Test in Order: Keyboard, Screen Reader, Automated
Keyboard testing catches the most impactful issues (users physically blocked from features). Screen reader testing catches semantics issues (users confused by incorrect announcements). Automated testing catches the remaining mechanical issues (missing attributes, contrast ratios). Start with the highest-impact method.

### 4. Accessibility Is Not a Feature -- It Is a Quality Attribute
Accessibility is tested continuously, like performance or security. Every new component, every new page, every PR gets accessibility review. Retrofitting accessibility onto a finished product costs 10-100x more than building it in from the start.

### 5. Test With Real Assistive Technology
Browser DevTools and axe-core extensions are useful for development, but they are not substitutes for testing with actual screen readers. VoiceOver on macOS, NVDA on Windows, and TalkBack on Android each have different behaviors and quirks.

---

## Automated Testing with axe-core and Playwright

### Setup

```bash
# axe-core 4.11.x or later — current is 4.11.4 (Apr 2026)
npm install --save-dev @axe-core/playwright
```

> **axe-core 4.11+ caveat:** Several best-practice rules (`focus-order-semantics`, `region`, `skip-link`, `table-duplicate-name`) are now also tagged `RGAAv4` (the French national standard). If you filter by tag and don't intend to test against RGAA, exclude it explicitly: `withTags(['wcag2a', 'wcag2aa', 'wcag22aa']).disableRules([])` is fine, but `.withTags(['best-practice'])` will pull in RGAA-specific rules.

### Reusable Helper

```typescript
// e2e/helpers/a11y.ts
import { type Page, type TestInfo, expect } from '@playwright/test';
import AxeBuilder from '@axe-core/playwright';

interface A11yOptions {
  tags?: string[];
  exclude?: string[];
  disableRules?: string[];
}

export async function checkAccessibility(
  page: Page, testInfo: TestInfo, options: A11yOptions = {}
): Promise<void> {
  let builder = new AxeBuilder({ page })
    .withTags(options.tags ?? ['wcag2a', 'wcag2aa', 'wcag22aa']);

  for (const sel of options.exclude ?? []) builder = builder.exclude(sel);
  if (options.disableRules?.length) builder = builder.disableRules(options.disableRules);

  const results = await builder.analyze();

  await testInfo.attach('a11y-results', {
    body: JSON.stringify(results, null, 2), contentType: 'application/json',
  });

  const violations = results.violations.map((v) => ({
    rule: v.id, impact: v.impact, description: v.description,
    helpUrl: v.helpUrl, elements: v.nodes.map((n) => n.html).slice(0, 5),
  }));

  expect(violations, `${violations.length} a11y violations:\n${JSON.stringify(violations, null, 2)}`)
    .toHaveLength(0);
}
```

### Using in Tests

```typescript
// e2e/tests/a11y/pages.spec.ts
import { test, expect } from '@playwright/test';
import { checkAccessibility } from '../../helpers/a11y';

test.describe('Accessibility - public pages', () => {
  for (const { name, path } of [
    { name: 'Home', path: '/' }, { name: 'Login', path: '/login' },
    { name: 'Pricing', path: '/pricing' }, { name: 'Sign Up', path: '/signup' },
  ]) {
    test(`${name} page has no a11y violations`, async ({ page }, testInfo) => {
      await page.goto(path);
      await checkAccessibility(page, testInfo);
    });
  }
});

test.describe('Accessibility - interactive states', () => {
  test('modal dialog is accessible when open', async ({ page }, testInfo) => {
    await page.goto('/dashboard');
    await page.getByRole('button', { name: 'Create project' }).click();

From JaiminVadadoriya/Distributed-Cloud-Storage---Sync-Platform, MIT.

More from JaiminVadadoriya/Distributed-Cloud-Storage---Sync-Platform