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/projects-dependencies.md

View on GitHub
# Projects & Dependencies

## Table of Contents

1. [Project Configuration](#project-configuration)
2. [Project Dependencies](#project-dependencies)
3. [Setup Projects](#setup-projects)
4. [Filtering & Running Projects](#filtering--running-projects)
5. [Sharing Configuration](#sharing-configuration)
6. [Advanced Patterns](#advanced-patterns)

## Project Configuration

### Basic Multi-Browser Setup

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

export default defineConfig({
	projects: [
		{
			name: 'chromium',
			use: { ...devices['Desktop Chrome'] }
		},
		{
			name: 'firefox',
			use: { ...devices['Desktop Firefox'] }
		},
		{
			name: 'webkit',
			use: { ...devices['Desktop Safari'] }
		}
	]
});
```

### Environment-Based Projects

```typescript
export default defineConfig({
	projects: [
		{
			name: 'staging',
			use: {
				baseURL: 'https://staging.example.com'
			}
		},
		{
			name: 'production',
			use: {
				baseURL: 'https://example.com'
			}
		},
		{
			name: 'local',
			use: {
				baseURL: 'http://localhost:3000'
			}
		}
	]
});
```

### Test Type Projects

```typescript
export default defineConfig({
	projects: [
		{
			name: 'e2e',
			testDir: './tests/e2e',
			use: { ...devices['Desktop Chrome'] }
		},
		{
			name: 'api',
			testDir: './tests/api',
			use: { baseURL: 'http://localhost:3000' }
		},
		{
			name: 'visual',
			testDir: './tests/visual',
			use: {
				...devices['Desktop Chrome'],
				viewport: { width: 1280, height: 720 }
			}
		}
	]
});
```

## Project Dependencies

### Setup Dependency

```typescript
export default defineConfig({
	projects: [
		// Setup project runs first
		{
			name: 'setup',
			testMatch: /.*\.setup\.ts/
		},

		// Browser projects depend on setup
		{
			name: 'chromium',
			use: {
				...devices['Desktop Chrome'],
				storageState: '.auth/user.json'
			},
			dependencies: ['setup']
		},
		{
			name: 'firefox',
			use: {
				...devices['Desktop Firefox'],
				storageState: '.auth/user.json'
			},
			dependencies: ['setup']
		}
	]
});
```

### Multiple Auth States

```typescript
export default defineConfig({
	projects: [
		// Auth setup projects
		{
			name: 'setup-admin',
			testMatch: /admin\.setup\.ts/
		},
		{
			name: 'setup-user',
			testMatch: /user\.setup\.ts/
		},

		// Admin tests
		{
			name: 'admin-tests',
			testDir: './tests/admin',
			use: { storageState: '.auth/admin.json' },
			dependencies: ['setup-admin']
		},

		// User tests
		{
			name: 'user-tests',
			testDir: './tests/user',
			use: { storageState: '.auth/user.json' },
			dependencies: ['setup-user']
		},

		// Tests that need both
		{
			name: 'integration-tests',
			testDir: './tests/integration',
			dependencies: ['setup-admin', 'setup-user']
		}
	]
});
```

### Chained Dependencies

```typescript
export default defineConfig({
	projects: [
		// Step 1: Database setup
		{
			name: 'db-setup',
			testMatch: /db\.setup\.ts/
		},

		// Step 2: Auth setup (needs DB)
		{
			name: 'auth-setup',
			testMatch: /auth\.setup\.ts/,
			dependencies: ['db-setup']
		},

		// Step 3: Seed data (needs auth)
		{
			name: 'seed-setup',
			testMatch: /seed\.setup\.ts/,
			dependencies: ['auth-setup']
		},

		// Tests (need everything)
		{
			name: 'tests',
			testDir: './tests',
			dependencies: ['seed-setup']
		}
	]
});
```

## Setup Projects

### Authentication Setup

Setup projects are the recommended way to handle authentication. They run before your main test projects and can use Playwright fixtures.

> **For complete authentication patterns** (storage state, multiple auth states, auth fixtures), see [fixtures-hooks.md](fixtures-hooks.md#authentication-patterns).

### Data Seeding Setup

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

setup('seed test data', async ({ request }) => {
	// Create test data via API
	await request.post('/api/test/seed', {
		data: {
			users: 10,
			products: 50,
			orders: 100
		}
	});
});
```

### Cleanup Setup

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

setup('cleanup previous run', async ({ request }) => {
	// Clean up data from previous test runs
	await request.delete('/api/test/cleanup');
});
```

## Filtering & Running Projects

### Run Specific Project

```bash
# Run single project
npx playwright test --project=chromium

# Run multiple projects
npx playwright test --project=chromium --project=firefox
```

### Run by Grep

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

# Run project with grep
npx playwright test --project=chromium --grep @critical

# Exclude pattern
npx playwright test --grep-invert @slow
```

### Project-Specific Grep

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

## Sharing Configuration

### Base Configuration

```typescript
// playwright.config.ts
const baseConfig = {
	timeout: 30000,
	expect: { timeout: 5000 },
	use: {
		trace: 'on-first-retry',
		screenshot: 'only-on-failure'
	}
};

export default defineConfig({
	...baseConfig,
	projects: [
		{
			name: 'chromium',
			use: {
				...baseConfig.use,
				...devices['Desktop Chrome']
			}
		},
		{
			name: 'firefox',
			use: {
				...baseConfig.use,
				...devices['Desktop Firefox']
			}
		}
	]
});
```

### Shared Project Settings

```typescript
const sharedBrowserConfig = {
	timeout: 60000,
	retries: 2,
	use: {
		video: 'on-first-retry',
		trace: 'on-first-retry'
	}
};

export default defineConfig({
	projects: [
		{
			name: 'chromium',
			...sharedBrowserConfig,
			use: {
				...sharedBrowserConfig.use,
				...devices['Desktop Chrome']
			}
		},
		{
			name: 'firefox',
			...sharedBrowserConfig,
			use: {
				...sharedBrowserConfig.use,
				...devices['Desktop Firefox']
			}
		}
	]
});
```

## Advanced Patterns

### Conditional Projects

```typescript
const projects = [
	{
		name: 'chromium',
		use: { ...devices['Desktop Chrome'] }
	}
];

// Add Firefox only in CI
if (process.env.CI) {
	projects.push({
		name: 'firefox',
		use: { ...devices['Desktop Firefox'] }
	});
}

// Add mobile only for specific test dirs
if (process.env.TEST_MOBILE) {
	projects.push({
		name: 'mobile',
		use: { ...devices['iPhone 14'] }
	});
}

export default defineConfig({ projects });
```

### Project Metadata

```typescript
export default defineConfig({
	projects: [
		{
			name: 'chromium',
			use: { ...devices['Desktop Chrome'] },
			metadata: {
				platform: 'desktop',
				browser: 'chromium',
				priority: 'high'
			}
		}
	]
});

// Access in test
test('example', async ({ page }, testInfo) => {
	const { platform, priority } = testInfo.project.metadata;
	console.log(`Running on ${platform} with ${priority} priority`);
});
```

### Teardown Projects

```typescript
export default defineConfig({
	projects: [
		{
			name: 'setup',
			testMatch: /.*\.setup\.ts/,
			teardown: 'teardown' // Run teardown after this completes
		},
		{
			name: 'teardown',
			testMatch: /.*\.teardown\.ts/
		},
		{
			name: 'tests',
			dependencies: ['setup']
		}
	]
});
```

```typescript
// cleanup.teardown.ts
import { test as teardown } from '@playwright/test';

teardown('cleanup', async ({ request }) => {
	await request.delete('/api/test/data');
});
```

## Anti-Patterns to Avoid

| Anti-Pattern               | Problem                | Solution                            |
| -------------------------- | ---------------------- | ----------------------------------- |
| Too many browser projects  | Slow CI, expensive     | Focus on critical browsers          |
| Missing setup dependencies | Tests fail randomly    | Declare all dependencies explicitly |
| Duplicated configuration   | Hard to maintain       | Extract shared config               |
| Not using setup projects   | Repeated auth in tests | Use setup project + storageState    |

## Related References

- **Global Setup**: See [global-setup.md](global-setup.md) for globalSetup vs setup projects
- **Fixtures**: See [fixtures-hooks.md](fixtures-hooks.md) for authentication patterns
- **CI/CD**: See [ci-cd.md](../infrastructure-ci-cd/ci-cd.md) for running projects in CI
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