Skip to content

ever-co/ever-works / .agents/skills/playwright-best-practices

playwright-best-practices

Verified

Use 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.

FileKindSize
LICENSE.mdmarkdown1.0 KB
README.mdmarkdown9.9 KB
SKILL.mdskill md25.7 KB
advanced/authentication-flows.mdmarkdown10.4 KB
advanced/authentication.mdmarkdown29.4 KB
advanced/clock-mocking.mdmarkdown9.4 KB
advanced/mobile-testing.mdmarkdown10.3 KB
advanced/multi-context.mdmarkdown8.2 KB
advanced/multi-user.mdmarkdown10.9 KB
advanced/network-advanced.mdmarkdown10.1 KB
advanced/third-party.mdmarkdown11.1 KB
architecture/pom-vs-fixtures.mdmarkdown11.4 KB
architecture/test-architecture.mdmarkdown14.3 KB
architecture/when-to-mock.mdmarkdown11.9 KB
browser-apis/browser-apis.mdmarkdown10.1 KB
browser-apis/iframes.mdmarkdown11.1 KB
browser-apis/service-workers.mdmarkdown13.1 KB
browser-apis/websockets.mdmarkdown9.9 KB
core/annotations.mdmarkdown10.4 KB
core/assertions-waiting.mdmarkdown9.1 KB
core/configuration.mdmarkdown13.7 KB
core/fixtures-hooks.mdmarkdown11.2 KB
core/global-setup.mdmarkdown12.4 KB
core/locators.mdmarkdown6.4 KB
core/page-object-model.mdmarkdown7.7 KB
core/projects-dependencies.mdmarkdown8.1 KB
core/test-data.mdmarkdown11.3 KB
core/test-suite-structure.mdmarkdown9.1 KB
core/test-tags.mdmarkdown6.7 KB
debugging/console-errors.mdmarkdown9.3 KB
debugging/debugging.mdmarkdown14.7 KB
debugging/error-testing.mdmarkdown9.2 KB
debugging/flaky-tests.mdmarkdown14.5 KB
frameworks/angular.mdmarkdown18.9 KB
frameworks/nextjs.mdmarkdown13.4 KB
frameworks/react.mdmarkdown17.5 KB
frameworks/vue.mdmarkdown17.3 KB
infrastructure-ci-cd/ci-cd.mdmarkdown10.4 KB
infrastructure-ci-cd/docker.mdmarkdown7.0 KB
infrastructure-ci-cd/github-actions.mdmarkdown15.1 KB
infrastructure-ci-cd/gitlab.mdmarkdown10.9 KB
infrastructure-ci-cd/other-providers.mdmarkdown14.2 KB
infrastructure-ci-cd/parallel-sharding.mdmarkdown11.6 KB
infrastructure-ci-cd/performance.mdmarkdown11.3 KB
infrastructure-ci-cd/reporting.mdmarkdown11.4 KB
infrastructure-ci-cd/test-coverage.mdmarkdown12.0 KB
testing-patterns/accessibility.mdmarkdown8.7 KB
testing-patterns/api-testing.mdmarkdown23.5 KB
testing-patterns/browser-extensions.mdmarkdown13.0 KB
testing-patterns/canvas-webgl.mdmarkdown12.3 KB
testing-patterns/component-testing.mdmarkdown11.0 KB
testing-patterns/drag-drop.mdmarkdown17.4 KB
testing-patterns/electron.mdmarkdown12.8 KB
testing-patterns/file-operations.mdmarkdown10.0 KB
testing-patterns/file-upload-download.mdmarkdown16.5 KB
testing-patterns/forms-validation.mdmarkdown21.3 KB
testing-patterns/graphql-testing.mdmarkdown8.6 KB
testing-patterns/i18n.mdmarkdown12.3 KB
testing-patterns/performance-testing.mdmarkdown11.5 KB
testing-patterns/security-testing.mdmarkdown11.5 KB
testing-patterns/visual-regression.mdmarkdown18.4 KB

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
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: 471kUpdated Claude CodeCodexVerifiedInstall
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: 471kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first.Stars: 194kUpdated Claude CodeCodexVerifiedInstall