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

core/test-suite-structure.md

View on GitHub
# Test Suite Structure

## Table of Contents

1. [Configuration](#configuration)
2. [E2E Tests](#e2e-tests)
3. [Component Tests](#component-tests)
4. [API Tests](#api-tests)
5. [Visual Regression Tests](#visual-regression-tests)
6. [Work Structure](#work-structure)
7. [Tagging & Filtering](#tagging--filtering)

### Project Setup

```bash
npm init playwright@latest
```

## Configuration

### Essential Configuration

```typescript
// playwright.config.ts
import { defineConfig, devices } from '@playwright/test';

export default defineConfig({
	testDir: './tests',
	fullyParallel: true,
	forbidOnly: !!process.env.CI,
	retries: process.env.CI ? 2 : 0,
	workers: process.env.CI ? 1 : undefined,
	reporter: [['html'], ['list']],
	use: {
		baseURL: 'http://localhost:3000',
		trace: 'on-first-retry',
		screenshot: 'only-on-failure'
	},
	projects: [
		{ name: 'setup', testMatch: /.*\.setup\.ts/ },
		{
			name: 'chromium',
			use: { ...devices['Desktop Chrome'] },
			dependencies: ['setup']
		}
	],
	webServer: {
		command: 'npm run dev',
		url: 'http://localhost:3000',
		reuseExistingServer: !process.env.CI
	}
});
```

## E2E Tests

Full user journey tests through the browser.

### Structure

```typescript
// tests/e2e/checkout.spec.ts
import { test, expect } from '@playwright/test';

test.describe('Checkout Flow', () => {
	test.beforeEach(async ({ page }) => {
		await page.goto('/products');
	});

	test('complete purchase as guest', async ({ page }) => {
		// Add to cart
		await page.getByRole('button', { name: 'Add to Cart' }).first().click();
		await expect(page.getByTestId('cart-count')).toHaveText('1');

		// Go to checkout
		await page.getByRole('link', { name: 'Cart' }).click();
		await page.getByRole('button', { name: 'Checkout' }).click();

		// Fill shipping
		await page.getByLabel('Email').fill('guest@example.com');
		await page.getByLabel('Address').fill('123 Test St');
		await page.getByRole('button', { name: 'Continue' }).click();

		// Payment
		await page.getByLabel('Card Number').fill('4242424242424242');
		await page.getByRole('button', { name: 'Pay Now' }).click();

		// Confirmation
		await expect(page.getByRole('heading')).toHaveText('Order Confirmed');
	});

	test('apply discount code', async ({ page }) => {
		await page.getByRole('button', { name: 'Add to Cart' }).first().click();
		await page.getByRole('link', { name: 'Cart' }).click();

		await page.getByLabel('Discount Code').fill('SAVE10');
		await page.getByRole('button', { name: 'Apply' }).click();

		await expect(page.getByText('10% discount applied')).toBeVisible();
	});
});
```

### Best Practices

- Test critical user journeys
- Keep tests independent
- Use realistic data
- Clean up test data in teardown

## Component Tests

Test individual components in isolation using Playwright Component Testing.

```bash
npm init playwright@latest -- --ct
```

For comprehensive component testing patterns including mounting, props, events, slots, mocking, and framework-specific examples (React, Vue, Svelte), see **[component-testing.md](../testing-patterns/component-testing.md)**.

## API Tests

Test backend APIs without browser.

### API Mocking Patterns

For E2E tests that need to mock API responses:

```typescript
// Mock single endpoint
test('displays mocked users', async ({ page }) => {
	await page.route('**/api/users', (route) =>
		route.fulfill({
			status: 200,
			json: [{ id: 1, name: 'Test User' }]
		})
	);

	await page.goto('/users');
	await expect(page.getByText('Test User')).toBeVisible();
});

// Mock with different responses
test('handles API errors', async ({ page }) => {
	await page.route('**/api/users', (route) =>
		route.fulfill({
			status: 500,
			json: { error: 'Server error' }
		})
	);

	await page.goto('/users');
	await expect(page.getByText('Server error')).toBeVisible();
});

// Conditional mocking
test('mocks based on request', async ({ page }) => {
	await page.route('**/api/users', (route, request) => {
		if (request.method() === 'GET') {
			route.fulfill({ json: [{ id: 1, name: 'User' }] });
		} else {
			route.continue();
		}
	});
});

// Mock with delay (simulate slow network)
test('handles slow API', async ({ page }) => {
	await page.route('**/api/data', (route) =>
		route.fulfill({
			json: { data: 'test' },
			delay: 2000 // 2 second delay
		})
	);

	await page.goto('/dashboard');
	await expect(page.getByText('Loading...')).toBeVisible();
	await expect(page.getByText('test')).toBeVisible();
});
```

For advanced patterns (GraphQL mocking, HAR recording, request modification, network throttling), see **[network-advanced.md](../advanced/network-advanced.md)**.

## Visual Regression Tests

Compare screenshots to detect visual changes.

### Basic Visual Test

```typescript
// tests/visual/homepage.spec.ts
import { test, expect } from '@playwright/test';

test('homepage visual', async ({ page }) => {
	await page.goto('/');
	await expect(page).toHaveScreenshot('homepage.png');
});

test('component visual', async ({ page }) => {
	await page.goto('/components');

	const button = page.getByRole('button', { name: 'Primary' });
	await expect(button).toHaveScreenshot('primary-button.png');
});
```

### Visual Test Options

```typescript
test('dashboard visual', async ({ page }) => {
	await page.goto('/dashboard');

	await expect(page).toHaveScreenshot('dashboard.png', {
		fullPage: true, // Capture entire scrollable page
		maxDiffPixels: 100, // Allow up to 100 different pixels
		maxDiffPixelRatio: 0.01, // Or 1% difference
		threshold: 0.2, // Pixel comparison threshold
		animations: 'disabled', // Disable animations
		mask: [page.getByTestId('date')] // Mask dynamic content
	});
});
```

### Handling Dynamic Content

```typescript
test('page with dynamic content', async ({ page }) => {
	await page.goto('/profile');

	// Mask elements that change
	await expect(page).toHaveScreenshot('profile.png', {
		mask: [page.getByTestId('timestamp'), page.getByTestId('avatar'), page.getByRole('img')]
	});
});

// Or hide elements via CSS
test('page hiding dynamic elements', async ({ page }) => {
	await page.goto('/profile');

	await page.addStyleTag({
		content: `
      .dynamic-content { visibility: hidden !important; }
      [data-testid="ad-banner"] { display: none !important; }
    `
	});

	await expect(page).toHaveScreenshot('profile-stable.png');
});
```

### Visual Test Configuration

```typescript
// playwright.config.ts
export default defineConfig({
	expect: {
		toHaveScreenshot: {
			maxDiffPixels: 50,
			animations: 'disabled'
		}
	},
	projects: [
		{
			name: 'visual-chrome',
			use: {
				...devices['Desktop Chrome'],
				viewport: { width: 1280, height: 720 }
			},
			testMatch: /.*visual.*\.spec\.ts/
		}
	]
});
```

### Update Snapshots

```bash
# Update all snapshots
npx playwright test --update-snapshots

# Update specific test
npx playwright test homepage.spec.ts --update-snapshots
```

## Work Structure

```
tests/
├── e2e/                    # End-to-end tests
│   ├── auth.spec.ts
│   ├── checkout.spec.ts
│   └── dashboard.spec.ts
├── component/              # Component tests
│   ├── Button.spec.tsx
│   └── Modal.spec.tsx
├── api/                    # API tests
│   ├── users.spec.ts
│   └── products.spec.ts
├── visual/                 # Visual regression tests
│   └── homepage.spec.ts
├── fixtures/               # Custom fixtures
│   ├── auth.fixture.ts
│   └── api.fixture.ts
└── pages/                  # Page objects
    ├── login.page.ts
    └── dashboard.page.ts
```

## Anti-Patterns to Avoid

| Anti-Pattern                          | Problem                            | Solution                  |
| ------------------------------------- | ---------------------------------- | ------------------------- |
| Long test files                       | Hard to maintain, slow to navigate | Split by feature, use POM |
| Tests depend on execution order       | Flaky, hard to debug               | Keep tests independent    |
| Testing multiple features in one test | Hard to debug failures             | One feature per test      |

## Related References

- **Component Testing**: See [component-testing.md](../testing-patterns/component-testing.md) for comprehensive CT patterns
- **Projects**: See [projects-dependencies.md](projects-dependencies.md) for project-based filtering
- **Page Objects**: See [page-object-model.md](page-object-model.md) for organizing page interactions
- **Test Data**: See [fixtures-hooks.md](fixtures-hooks.md) for managing test data

## Tagging & Filtering

### Using Tags

```typescript
test('user login @smoke @auth', async ({ page }) => {
	// ...
});

test('checkout flow @e2e @critical', async ({ page }) => {
	// ...
});

test.describe('API tests @api', () => {
	test('create user', async ({ request }) => {
		// ...
	});
});
```

### Running Tagged Tests

```bash
# Run smoke tests
npx playwright test --grep @smoke

# Run all except slow tests
npx playwright test --grep-invert @slow

# Combine tags
npx playwright test --grep "@smoke|@critical"
```

For project-based filtering and advanced project configuration, see **[projects-dependencies.md](projects-dependencies.md)**.
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