ever-co/ever-works / .agents/skills/playwright-best-practices
playwright-best-practices
VerifiedUse when writing Playwright tests, fixing flaky tests, debugging failures, implementing Page Object Model, configuring CI/CD, optimizing performance, mocking APIs, handling authentication or OAuth, testing accessibility (axe-core), file uploads/downloads, date/time mocking, WebSockets, geolocation, permissions, multi-tab/popup flows, mobile/responsive layouts, touch gestures, GraphQL, error handling, offline mode, multi-user collaboration, third-party services (payments, email verification), console error monitoring, global setup/teardown, test annotations (skip, fixme, slow), test tags (@smoke, @fast, @critical, filtering with --grep), project dependencies, security testing (XSS, CSRF, auth), performance budgets (Web Vitals, Lighthouse), iframes, component testing, canvas/WebGL, service workers/PWA, test coverage, i18n/localization, Electron apps, or browser extension testing. Covers E2E, component, API, visual, accessibility, security, Electron, and extension testing.
testing-patterns/accessibility.md
View on GitHub# Accessibility Testing
## Table of Contents
1. [Axe-Core Integration](#axe-core-integration)
2. [Keyboard Navigation](#keyboard-navigation)
3. [ARIA Validation](#aria-validation)
4. [Focus Management](#focus-management)
5. [Color & Contrast](#color--contrast)
## Axe-Core Integration
### Setup
```bash
npm install -D @axe-core/playwright
```
### Basic A11y Test
```typescript
import { test, expect } from '@playwright/test';
import AxeBuilder from '@axe-core/playwright';
test('homepage should have no a11y violations', async ({ page }) => {
await page.goto('/');
const results = await new AxeBuilder({ page }).analyze();
expect(results.violations).toEqual([]);
});
```
### Scoped Analysis
```typescript
test('form accessibility', async ({ page }) => {
await page.goto('/contact');
// Analyze only the form
const results = await new AxeBuilder({ page }).include('#contact-form').analyze();
expect(results.violations).toEqual([]);
});
test('ignore known issues', async ({ page }) => {
await page.goto('/legacy-page');
const results = await new AxeBuilder({ page })
.exclude('.legacy-widget') // Skip legacy component
.disableRules(['color-contrast']) // Disable specific rule
.analyze();
expect(results.violations).toEqual([]);
});
```
### A11y Fixture
```typescript
// fixtures/a11y.fixture.ts
import { test as base } from '@playwright/test';
import AxeBuilder from '@axe-core/playwright';
type A11yFixtures = {
makeAxeBuilder: () => AxeBuilder;
};
export const test = base.extend<A11yFixtures>({
makeAxeBuilder: async ({ page }, use) => {
await use(() => new AxeBuilder({ page }).withTags(['wcag2a', 'wcag2aa', 'wcag21a', 'wcag21aa']));
}
});
// Usage
test('dashboard a11y', async ({ page, makeAxeBuilder }) => {
await page.goto('/dashboard');
const results = await makeAxeBuilder().analyze();
expect(results.violations).toEqual([]);
});
```
### Detailed Violation Reporting
```typescript
test('report a11y issues', async ({ page }) => {
await page.goto('/');
const results = await new AxeBuilder({ page }).analyze();
// Custom failure message with details
const violations = results.violations.map((v) => ({
id: v.id,
impact: v.impact,
description: v.description,
nodes: v.nodes.map((n) => n.html)
}));
expect(violations, JSON.stringify(violations, null, 2)).toHaveLength(0);
});
```
## Keyboard Navigation
### Tab Order Testing
```typescript
test('correct tab order in form', async ({ page }) => {
await page.goto('/signup');
// Start from the beginning
await page.keyboard.press('Tab');
await expect(page.getByLabel('Email')).toBeFocused();
await page.keyboard.press('Tab');
await expect(page.getByLabel('Password')).toBeFocused();
await page.keyboard.press('Tab');
await expect(page.getByRole('button', { name: 'Sign up' })).toBeFocused();
});
```
### Keyboard-Only Interaction
```typescript
test('complete flow with keyboard only', async ({ page }) => {
await page.goto('/products');
// Navigate to product with keyboard
await page.keyboard.press('Tab'); // Skip to main content
await page.keyboard.press('Tab'); // First product
await page.keyboard.press('Enter'); // Open product
await expect(page).toHaveURL(/\/products\/\d+/);
// Add to cart with keyboard
await page.keyboard.press('Tab');
await page.keyboard.press('Tab'); // Navigate to "Add to Cart"
await page.keyboard.press('Enter');
await expect(page.getByRole('alert')).toContainText('Added to cart');
});
```
### Skip Links
```typescript
test('skip link works', async ({ page }) => {
await page.goto('/');
await page.keyboard.press('Tab');
const skipLink = page.getByRole('link', { name: /skip to main/i });
await expect(skipLink).toBeFocused();
await page.keyboard.press('Enter');
// Focus should move to main content
await expect(page.getByRole('main')).toBeFocused();
});
```
### Escape Key Handling
```typescript
test('escape closes modal', async ({ page }) => {
await page.goto('/dashboard');
await page.getByRole('button', { name: 'Settings' }).click();
const modal = page.getByRole('dialog');
await expect(modal).toBeVisible();
await page.keyboard.press('Escape');
await expect(modal).toBeHidden();
// Focus should return to trigger
await expect(page.getByRole('button', { name: 'Settings' })).toBeFocused();
});
```
## ARIA Validation
### Role Verification
```typescript
test('correct ARIA roles', async ({ page }) => {
await page.goto('/dashboard');
// Verify landmark roles
await expect(page.getByRole('navigation')).toBeVisible();
await expect(page.getByRole('main')).toBeVisible();
await expect(page.getByRole('contentinfo')).toBeVisible(); // footer
// Verify interactive roles
await expect(page.getByRole('button', { name: 'Menu' })).toBeVisible();
await expect(page.getByRole('search')).toBeVisible();
});
```
### ARIA States
```typescript
test('aria-expanded updates correctly', async ({ page }) => {
await page.goto('/faq');
const accordion = page.getByRole('button', { name: 'Shipping' });
// Initially collapsed
await expect(accordion).toHaveAttribute('aria-expanded', 'false');
await accordion.click();
// Now expanded
await expect(accordion).toHaveAttribute('aria-expanded', 'true');
// Content is visible
const panel = page.getByRole('region', { name: 'Shipping' });
await expect(panel).toBeVisible();
});
```
### Live Regions
```typescript
test('live region announces updates', async ({ page }) => {
await page.goto('/checkout');
// Find live region
const liveRegion = page.locator('[aria-live="polite"]');
await page.getByLabel('Quantity').fill('3');
// Live region should update with new total
await expect(liveRegion).toContainText('Total: $29.97');
});
```
## Focus Management
### Focus Trap in Modal
```typescript
test('focus trapped in modal', async ({ page }) => {
await page.goto('/');
await page.getByRole('button', { name: 'Open Modal' }).click();
const modal = page.getByRole('dialog');
await expect(modal).toBeVisible();
// Get all focusable elements in modal
const focusableElements = modal.locator('button, [href], input, select, textarea, [tabindex]:not([tabindex="-1"])');
const count = await focusableElements.count();
// Tab through all elements, should stay in modal
for (let i = 0; i < count + 1; i++) {
await page.keyboard.press('Tab');
const focused = page.locator(':focus');
await expect(modal).toContainText((await focused.textContent()) || '');
}
});
```
### Focus Restoration
```typescript
test('focus returns after modal close', async ({ page }) => {
await page.goto('/');
const trigger = page.getByRole('button', { name: 'Delete Item' });
await trigger.click();
await page.getByRole('button', { name: 'Cancel' }).click();
// Focus should return to the trigger
await expect(trigger).toBeFocused();
});
```
## Color & Contrast
### High Contrast Mode
```typescript
test('works in high contrast mode', async ({ page }) => {
await page.emulateMedia({ forcedColors: 'active' });
await page.goto('/');
// Verify key elements are visible
await expect(page.getByRole('navigation')).toBeVisible();
await expect(page.getByRole('button', { name: 'Sign In' })).toBeVisible();
// Take screenshot for visual verification
await expect(page).toHaveScreenshot('high-contrast.png');
});
```
### Reduced Motion
```typescript
test('respects reduced motion preference', async ({ page }) => {
await page.emulateMedia({ reducedMotion: 'reduce' });
await page.goto('/');
// Animations should be disabled
const hero = page.getByTestId('hero-animation');
const animation = await hero.evaluate((el) => getComputedStyle(el).animationDuration);
expect(animation).toBe('0s');
});
```
## CI Integration
### A11y as CI Gate
```typescript
// playwright.config.ts
export default defineConfig({
projects: [
{
name: 'a11y',
testMatch: /.*\.a11y\.spec\.ts/,
use: { ...devices['Desktop Chrome'] }
}
]
});
```
```yaml
# .github/workflows/a11y.yml
- name: Run accessibility tests
run: npx playwright test --project=a11y
```
## Anti-Patterns to Avoid
| Anti-Pattern | Problem | Solution |
| ----------------------------- | ---------------------------- | ------------------------------------------ |
| Testing a11y only on homepage | Misses issues on other pages | Test all critical user flows |
| Ignoring all violations | No value from tests | Address or explicitly exclude known issues |
| Only automated testing | Misses many a11y issues | Combine with manual testing |
| Testing without screen reader | Misses interaction issues | Test with VoiceOver/NVDA periodically |
## Related References
- **Locators**: See [locators.md](../core/locators.md) for role-based selectors
- **Visual testing**: See [test-suite-structure.md](../core/test-suite-structure.md) for screenshot comparison
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |