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/configuration.md

View on GitHub
# Playwright Configuration

## Table of Contents

1. [CLI Quick Reference](#cli-quick-reference)
2. [Decision Guide](#decision-guide)
3. [Production-Ready Config](#production-ready-config)
4. [Patterns](#patterns)
5. [Anti-Patterns](#anti-patterns)
6. [Troubleshooting](#troubleshooting)
7. [Related](#related)

> **When to use**: Setting up a new project, adjusting timeouts, adding browser targets, configuring CI behavior, or managing environment-specific settings.

## CLI Quick Reference

```bash
npx playwright init                           # scaffold config + first test
npx playwright test --config=custom.config.ts # use alternate config
npx playwright test --project=chromium        # run single project
npx playwright test --reporter=html           # override reporter
npx playwright test --grep @smoke             # run tests tagged @smoke
npx playwright test --grep-invert @slow       # exclude @slow tests
npx playwright show-report                    # open last HTML report
DEBUG=pw:api npx playwright test              # verbose logging
```

## Decision Guide

### Timeout Selection

| Symptom                                   | Setting             | Default       | Recommended       |
| ----------------------------------------- | ------------------- | ------------- | ----------------- |
| Test takes too long overall               | `timeout`           | 30s           | 30-60s (max 120s) |
| Assertion retries too long/short          | `expect.timeout`    | 5s            | 5-10s             |
| `page.goto()` or `waitForURL()` times out | `navigationTimeout` | 30s           | 10-30s            |
| `click()`, `fill()` time out              | `actionTimeout`     | 0 (unlimited) | 10-15s            |
| Dev server slow to start                  | `webServer.timeout` | 60s           | 60-180s           |

### Server Management

| Scenario                     | Approach                                                |
| ---------------------------- | ------------------------------------------------------- |
| App in same repo             | `webServer` with `reuseExistingServer: !process.env.CI` |
| Separate repos               | Manual start or Docker Compose                          |
| Testing deployed environment | No `webServer`; set `baseURL` via env                   |
| Multiple services            | Array of `webServer` entries                            |

### Single vs Multi-Project

| Scenario               | Approach                                   |
| ---------------------- | ------------------------------------------ |
| Early development      | Single project (chromium only)             |
| Pre-release validation | Multi-project: chromium + firefox + webkit |
| Mobile-responsive app  | Add mobile projects alongside desktop      |
| Auth + non-auth tests  | Setup project with dependencies            |
| Tight CI budget        | Chromium on PRs; all browsers on main      |

### globalSetup vs Setup Projects vs Fixtures

| Need                    | Use                                |
| ----------------------- | ---------------------------------- |
| One-time DB seed        | `globalSetup`                      |
| Shared browser auth     | Setup project with `dependencies`  |
| Per-test isolated state | Custom fixture via `test.extend()` |
| Cleanup after all tests | `globalTeardown`                   |

## Production-Ready Config

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

dotenv.config({ path: path.resolve(__dirname, '.env') });

export default defineConfig({
	testDir: './e2e',
	testMatch: '**/*.spec.ts',

	fullyParallel: true,
	forbidOnly: !!process.env.CI,
	retries: process.env.CI ? 2 : 0,
	workers: process.env.CI ? '50%' : undefined,

	reporter: process.env.CI ? [['html', { open: 'never' }], ['github']] : [['html', { open: 'on-failure' }]],

	timeout: 30_000,
	expect: { timeout: 5_000 },

	use: {
		baseURL: process.env.BASE_URL || 'http://localhost:4000',
		actionTimeout: 10_000,
		navigationTimeout: 15_000,
		trace: 'on-first-retry',
		screenshot: 'only-on-failure',
		video: 'retain-on-failure',
		locale: 'en-US',
		timezoneId: 'America/Los_Angeles'
	},

	projects: [
		{ name: 'chromium', use: { ...devices['Desktop Chrome'] } },
		{ name: 'firefox', use: { ...devices['Desktop Firefox'] } },
		{ name: 'webkit', use: { ...devices['Desktop Safari'] } },
		{ name: 'mobile-chrome', use: { ...devices['Pixel 7'] } },
		{ name: 'mobile-safari', use: { ...devices['iPhone 14'] } }
	],

	webServer: {
		command: 'npm run start',
		url: 'http://localhost:4000',
		reuseExistingServer: !process.env.CI,
		timeout: 120_000,
		stdout: 'pipe',
		stderr: 'pipe'
	}
});
```

## Patterns

### Environment-Specific Configuration

**Use when**: Tests run against dev, staging, and production environments.

```ts
// playwright.config.ts
import { defineConfig } from '@playwright/test';
import dotenv from 'dotenv';
import path from 'path';

const ENV = process.env.TEST_ENV || 'local';
dotenv.config({ path: path.resolve(__dirname, `.env.${ENV}`) });

const envConfig: Record<string, { baseURL: string; retries: number }> = {
	local: { baseURL: 'http://localhost:4000', retries: 0 },
	staging: { baseURL: 'https://staging.myapp.com', retries: 2 },
	prod: { baseURL: 'https://myapp.com', retries: 2 }
};

export default defineConfig({
	testDir: './e2e',
	retries: envConfig[ENV].retries,
	use: { baseURL: envConfig[ENV].baseURL }
});
```

```bash
TEST_ENV=staging npx playwright test
TEST_ENV=prod npx playwright test --grep @smoke
```

### Setup Project with Dependencies

**Use when**: Tests need shared authentication state before running.

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

export default defineConfig({
	testDir: './e2e',
	projects: [
		{
			name: 'setup',
			testMatch: /auth\.setup\.ts/
		},
		{
			name: 'chromium',
			use: {
				...devices['Desktop Chrome'],
				storageState: 'playwright/.auth/session.json'
			},
			dependencies: ['setup']
		},
		{
			name: 'firefox',
			use: {
				...devices['Desktop Firefox'],
				storageState: 'playwright/.auth/session.json'
			},
			dependencies: ['setup']
		}
	]
});
```

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

const authFile = 'playwright/.auth/session.json';

setup('authenticate', async ({ page }) => {
	await page.goto('/login');
	await page.getByLabel('Username').fill('testuser@example.com');
	await page.getByLabel('Password').fill(process.env.TEST_PASSWORD!);
	await page.getByRole('button', { name: 'Log in' }).click();
	await expect(page.getByRole('heading', { name: 'Home' })).toBeVisible();
	await page.context().storageState({ path: authFile });
});
```

### webServer with Build Step

**Use when**: Tests need a running application server managed by Playwright.

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

export default defineConfig({
	testDir: './e2e',
	use: { baseURL: 'http://localhost:4000' },
	webServer: {
		command: process.env.CI ? 'npm run build && npm run preview' : 'npm run dev',
		url: 'http://localhost:4000',
		reuseExistingServer: !process.env.CI,
		timeout: 120_000,
		env: {
			NODE_ENV: 'test',
			DB_URL: process.env.DB_URL || 'postgresql://localhost:5432/testdb'
		}
	}
});
```

### globalSetup / globalTeardown

**Use when**: One-time non-browser work like seeding a database. Runs once per test run.

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

export default defineConfig({
	testDir: './e2e',
	globalSetup: './e2e/setup.ts',
	globalTeardown: './e2e/teardown.ts'
});
```

```ts
// e2e/setup.ts
import { FullConfig } from '@playwright/test';

export default async function globalSetup(config: FullConfig) {
	const { execSync } = await import('child_process');
	execSync('npx prisma db seed', { stdio: 'inherit' });
	process.env.TEST_RUN_ID = `run-${Date.now()}`;
}
```

```ts
// e2e/teardown.ts
import { FullConfig } from '@playwright/test';

export default async function globalTeardown(config: FullConfig) {
	const { execSync } = await import('child_process');
	execSync('npx prisma db push --force-reset', { stdio: 'inherit' });
}
```

### Environment Variables with .env

**Use when**: Managing secrets, URLs, or feature flags without hardcoding.

```bash
# .env.example (commit this)
BASE_URL=http://localhost:4000
TEST_PASSWORD=
API_KEY=

# .env.local (gitignored)
BASE_URL=http://localhost:4000
TEST_PASSWORD=secret123
API_KEY=dev-key-abc

# .env.staging (gitignored)
BASE_URL=https://staging.myapp.com
TEST_PASSWORD=staging-pass
API_KEY=staging-key-xyz
```

```bash
# .gitignore
.env
.env.local
.env.staging
.env.production
playwright/.auth/
```

Install dotenv:

```bash
npm install -D dotenv
```

### Tag-Based Test Filtering

**Use when**: Running subsets of tests in different CI stages (PR vs nightly).

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

export default defineConfig({
	testDir: './e2e',

	// Filter by tags in CI
	grep: process.env.CI ? /@smoke|@critical/ : undefined,
	grepInvert: process.env.CI ? /@flaky/ : undefined
});
```

**Project-specific filtering:**

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

export default defineConfig({
	testDir: './e2e',
	projects: [
		{
			name: 'smoke',
			grep: /@smoke/,
			use: { ...devices['Desktop Chrome'] }
		},
		{
			name: 'regression',
			grepInvert: /@smoke/,
			use: { ...devices['Desktop Chrome'] }
		},
		{
			name: 'critical-only',
			grep: /@critical/,
			use: { ...devices['Desktop Chrome'] }
		}
	]
});
```

```bash
# Run specific project
npx playwright test --project=smoke
npx playwright test --project=regression
```

### Artifact Collection Strategy

| Setting      | Local   | CI                    | Reason                                    |
| ------------ | ------- | --------------------- | ----------------------------------------- |
| `trace`      | `'off'` | `'on-first-retry'`    | Traces are large; collect on failure only |
| `screenshot` | `'off'` | `'only-on-failure'`   | Useful for CI debugging                   |
| `video`      | `'off'` | `'retain-on-failure'` | Recording slows tests                     |

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

export default defineConfig({
	testDir: './e2e',
	use: {
		trace: process.env.CI ? 'on-first-retry' : 'off',
		screenshot: process.env.CI ? 'only-on-failure' : 'off',
		video: process.env.CI ? 'retain-on-failure' : 'off'
	}
});
```

## Anti-Patterns

| Don't                                                            | Problem                                | Do Instead                          |
| ---------------------------------------------------------------- | -------------------------------------- | ----------------------------------- |
| `timeout: 300_000` globally                                      | Masks flaky tests; slow CI             | Fix root cause; keep 30s default    |
| Hardcoded URLs: `page.goto('http://localhost:4000/login')`       | Breaks in other environments           | Use `baseURL` + relative paths      |
| All browsers on every PR                                         | 3x CI time                             | Chromium on PRs; all on main        |
| `trace: 'on'` always                                             | Huge artifacts, slow uploads           | `trace: 'on-first-retry'`           |
| `video: 'on'` always                                             | Massive storage; slow tests            | `video: 'retain-on-failure'`        |
| Config in test files: `test.use({ viewport: {...} })` everywhere | Scattered, inconsistent                | Define once in project config       |
| `retries: 3` locally                                             | Hides flakiness                        | `retries: 0` local, `retries: 2` CI |
| No `forbidOnly` in CI                                            | Committed `test.only` runs single test | `forbidOnly: !!process.env.CI`      |
| `globalSetup` for browser auth                                   | No browser context available           | Use setup project with dependencies |
| Committing `.env` with credentials                               | Security risk                          | Commit `.env.example` only          |

## Troubleshooting

### baseURL Not Working

**Cause**: Using absolute URL in `page.goto()` ignores `baseURL`.

```ts
// Wrong - ignores baseURL
await page.goto('http://localhost:4000/dashboard');

// Correct - uses baseURL
await page.goto('/dashboard');
```

### webServer Starts But Tests Get Connection Refused

**Cause**: `webServer.url` doesn't match actual server address or health check returns non-200.

```ts
webServer: {
  command: 'npm run dev',
  url: 'http://localhost:4000/api/health',  // use real endpoint
  reuseExistingServer: !process.env.CI,
  timeout: 120_000,
},
```

### Tests Pass Locally But Timeout in CI

**Cause**: CI machines are slower. Increase timeouts and reduce workers:

```ts
export default defineConfig({
	workers: process.env.CI ? '50%' : undefined,
	use: {
		navigationTimeout: process.env.CI ? 30_000 : 15_000,
		actionTimeout: process.env.CI ? 15_000 : 10_000
	}
});
```

### "Target page, context or browser has been closed"

**Cause**: Test exceeded `timeout` and Playwright tore down browser during action.

**Fix**: Don't increase global timeout. Find slow step using trace:

```bash
npx playwright test --trace on
npx playwright show-report
```

## Related

- [test-tags.md](./test-tags.md) - tagging and filtering tests with `--grep`
- [fixtures-hooks.md](./fixtures-hooks.md) - custom fixtures for per-test state
- [test-suite-structure.md](test-suite-structure.md) - file structure and naming
- [authentication.md](../advanced/authentication.md) - setup projects for shared auth
- [projects-dependencies.md](./projects-dependencies.md) - advanced multi-project patterns
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