ever-co/ever-works / .agents/skills/playwright-best-practices
playwright-best-practices
VerifiedUse 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.
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
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| 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: 471k | Updated | Claude CodeCodex | Verified | Install |
| 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: 471k | Updated | Claude CodeCodex | Verified | Install |
| rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |