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/fixtures-hooks.md

View on GitHub
# Fixtures & Hooks

## Table of Contents

1. [Built-in Fixtures](#built-in-fixtures)
2. [Custom Fixtures](#custom-fixtures)
3. [Fixture Scopes](#fixture-scopes)
4. [Hooks](#hooks)
5. [Authentication Patterns](#authentication-patterns)
6. [Database Fixtures](#database-fixtures)

## Built-in Fixtures

### Core Fixtures

```typescript
test('example', async ({
	page, // Isolated page instance
	context, // Browser context (cookies, localStorage)
	browser, // Browser instance
	browserName, // 'chromium', 'firefox', or 'webkit'
	request // API request context
}) => {
	// Each test gets fresh instances
});
```

### Request Fixture

```typescript
test('API call', async ({ request }) => {
	const response = await request.get('/api/users');
	await expect(response).toBeOK();

	const users = await response.json();
	expect(users).toHaveLength(5);
});
```

## Custom Fixtures

### Basic Custom Fixture

```typescript
// fixtures.ts
import { test as base } from '@playwright/test';

// Declare fixture types
type MyFixtures = {
	todoPage: TodoPage;
	apiClient: ApiClient;
};

export const test = base.extend<MyFixtures>({
	// Fixture with setup and teardown
	todoPage: async ({ page }, use) => {
		const todoPage = new TodoPage(page);
		await todoPage.goto();

		await use(todoPage); // Test runs here

		// Teardown (optional)
		await todoPage.clearTodos();
	},

	// Simple fixture
	apiClient: async ({ request }, use) => {
		await use(new ApiClient(request));
	}
});

export { expect } from '@playwright/test';
```

### Fixture with Options

```typescript
type Options = {
	defaultUser: { email: string; password: string };
};

type Fixtures = {
	authenticatedPage: Page;
};

export const test = base.extend<Options & Fixtures>({
	// Define option with default
	defaultUser: [{ email: 'test@example.com', password: 'pass123' }, { option: true }],

	// Use option in fixture
	authenticatedPage: async ({ page, defaultUser }, use) => {
		await page.goto('/login');
		await page.getByLabel('Email').fill(defaultUser.email);
		await page.getByLabel('Password').fill(defaultUser.password);
		await page.getByRole('button', { name: 'Sign in' }).click();
		await use(page);
	}
});

// Override in config
export default defineConfig({
	use: {
		defaultUser: { email: 'admin@example.com', password: 'admin123' }
	}
});
```

### Automatic Fixtures

```typescript
export const test = base.extend<{}, { setupDb: void }>({
	// Auto-fixture runs for every test without explicit usage
	setupDb: [
		async ({}, use) => {
			await seedDatabase();
			await use();
			await cleanDatabase();
		},
		{ auto: true }
	]
});
```

## Fixture Scopes

### Test Scope (Default)

Created fresh for each test:

```typescript
test.extend({
	page: async ({ browser }, use) => {
		const page = await browser.newPage();
		await use(page);
		await page.close();
	}
});
```

### Worker Scope

Shared across tests in the same worker (each worker gets its own instance; tests in different workers do not share it):

```typescript
type WorkerFixtures = {
	sharedAccount: Account;
};

export const test = base.extend<{}, WorkerFixtures>({
	sharedAccount: [
		async ({ browser }, use) => {
			// Expensive setup - runs once per worker
			const account = await createTestAccount();
			await use(account);
			await deleteTestAccount(account);
		},
		{ scope: 'worker' }
	]
});
```

### Isolate test data between parallel workers

When tests in different workers touch the same backend or DB (e.g. same user, same tenant), they can collide and cause flaky failures. Use `testInfo.workerIndex` (or `process.env.TEST_WORKER_INDEX`) in a worker-scoped fixture to create unique data per worker:

```typescript
import { test as baseTest } from '@playwright/test';

type WorkerFixtures = {
	dbUserName: string;
};

export const test = baseTest.extend<{}, WorkerFixtures>({
	dbUserName: [
		async ({}, use, testInfo) => {
			const userName = `user-${testInfo.workerIndex}`;
			await createUserInTestDatabase(userName);
			await use(userName);
			await deleteUserFromTestDatabase(userName);
		},
		{ scope: 'worker' }
	]
});
```

Then each worker uses a distinct user (e.g. `user-1`, `user-2`), so parallel workers do not overwrite each other’s data.

## Hooks

### beforeEach / afterEach

```typescript
test.beforeEach(async ({ page }) => {
	// Runs before each test in file
	await page.goto('/');
});

test.afterEach(async ({ page }, testInfo) => {
	// Runs after each test
	if (testInfo.status !== 'passed') {
		await page.screenshot({ path: `failed-${testInfo.title}.png` });
	}
});
```

### beforeAll / afterAll

```typescript
test.beforeAll(async ({ browser }) => {
	// Runs once before all tests in file
	// Note: Cannot use page fixture here
});

test.afterAll(async () => {
	// Runs once after all tests in file
});
```

### Describe-Level Hooks

```typescript
test.describe('User Management', () => {
	test.beforeEach(async ({ page }) => {
		await page.goto('/users');
	});

	test('can list users', async ({ page }) => {
		// Starts at /users
	});

	test('can add user', async ({ page }) => {
		// Starts at /users
	});
});
```

## Authentication Patterns

### Global Setup with Storage State

```typescript
// auth.setup.ts
import { test as setup, expect } from '@playwright/test';

const authFile = '.auth/user.json';

setup('authenticate', async ({ page }) => {
	await page.goto('/login');
	await page.getByLabel('Email').fill(process.env.TEST_EMAIL!);
	await page.getByLabel('Password').fill(process.env.TEST_PASSWORD!);
	await page.getByRole('button', { name: 'Sign in' }).click();

	await expect(page.getByRole('heading', { name: 'Dashboard' })).toBeVisible();
	await page.context().storageState({ path: authFile });
});
```

```typescript
// playwright.config.ts
export default defineConfig({
	projects: [
		{ name: 'setup', testMatch: /.*\.setup\.ts/ },
		{
			name: 'chromium',
			use: {
				...devices['Desktop Chrome'],
				storageState: '.auth/user.json'
			},
			dependencies: ['setup']
		}
	]
});
```

### Multiple Auth States

```typescript
// auth.setup.ts
setup('admin auth', async ({ page }) => {
	await login(page, 'admin@example.com', 'adminpass');
	await page.context().storageState({ path: '.auth/admin.json' });
});

setup('user auth', async ({ page }) => {
	await login(page, 'user@example.com', 'userpass');
	await page.context().storageState({ path: '.auth/user.json' });
});
```

```typescript
// playwright.config.ts
projects: [
	{
		name: 'admin tests',
		testMatch: /.*admin.*\.spec\.ts/,
		use: { storageState: '.auth/admin.json' },
		dependencies: ['setup']
	},
	{
		name: 'user tests',
		testMatch: /.*user.*\.spec\.ts/,
		use: { storageState: '.auth/user.json' },
		dependencies: ['setup']
	}
];
```

### Auth Fixture

```typescript
// fixtures/auth.fixture.ts
export const test = base.extend<{ adminPage: Page; userPage: Page }>({
	adminPage: async ({ browser }, use) => {
		const context = await browser.newContext({
			storageState: '.auth/admin.json'
		});
		const page = await context.newPage();
		await use(page);
		await context.close();
	},

	userPage: async ({ browser }, use) => {
		const context = await browser.newContext({
			storageState: '.auth/user.json'
		});
		const page = await context.newPage();
		await use(page);
		await context.close();
	}
});
```

## Database Fixtures

This section covers **per-test database fixtures** (isolation, transaction rollback). For related topics:

- **Test data factories** (builders, Faker): See [test-data.md](test-data.md)
- **One-time database setup** (migrations, snapshots): See [global-setup.md](global-setup.md#database-patterns)

### Transaction Rollback Pattern

```typescript
import { test as base } from '@playwright/test';
import { db } from '../db';

export const test = base.extend<{ dbTransaction: Transaction }>({
	dbTransaction: async ({}, use) => {
		const transaction = await db.beginTransaction();

		await use(transaction);

		await transaction.rollback(); // Clean slate for next test
	}
});
```

### Seed Data Fixture

```typescript
type TestData = {
	testUser: User;
	testProducts: Product[];
};

export const test = base.extend<TestData>({
	testUser: async ({}, use) => {
		const user = await db.users.create({
			email: `test-${Date.now()}@example.com`,
			name: 'Test User'
		});

		await use(user);

		await db.users.delete(user.id);
	},

	testProducts: async ({ testUser }, use) => {
		const products = await db.products.createMany([
			{ name: 'Product A', ownerId: testUser.id },
			{ name: 'Product B', ownerId: testUser.id }
		]);

		await use(products);

		await db.products.deleteMany(products.map((p) => p.id));
	}
});
```

## Fixture Tips

| Tip                | Explanation                                 |
| ------------------ | ------------------------------------------- |
| Fixtures are lazy  | Only created when used                      |
| Compose fixtures   | Use other fixtures as dependencies          |
| Keep setup minimal | Do heavy lifting in worker-scoped fixtures  |
| Clean up resources | Use teardown in fixtures, not afterEach     |
| Avoid shared state | Each fixture instance should be independent |

## Anti-Patterns to Avoid

| Anti-Pattern                              | Problem                                                    | Solution                                                                                                                                                                              |
| ----------------------------------------- | ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Shared mutable state between tests        | Race conditions, order dependencies                        | Use fixtures for isolation                                                                                                                                                            |
| Global variables in tests                 | Tests depend on execution order                            | Use fixtures or beforeEach for setup                                                                                                                                                  |
| Not cleaning up test data                 | Tests interfere with each other                            | Use fixtures with teardown or database transactions                                                                                                                                   |
| Shared `page` or `context` in `beforeAll` | State leak between tests; flaky when tests run in parallel | Use default one-context-per-test, or `beforeEach` + fresh page; if serial is required, prefer `test.describe.configure({ mode: 'serial' })` and document that isolation is sacrificed |
| Backend/DB state shared across workers    | Tests in different workers collide on same data            | Use worker-scoped fixture with `testInfo.workerIndex` to create unique data per worker                                                                                                |

## Related References

- **Page Objects with fixtures**: See [page-object-model.md](page-object-model.md) for POM patterns
- **Test organization**: See [test-suite-structure.md](test-suite-structure.md) for test structure
- **Debugging fixture issues**: See [debugging.md](../debugging/debugging.md) for troubleshooting
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: 472kUpdated 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: 472kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 472kUpdated 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