1# Playwright Configuration
2 
3## Table of Contents
4 
51. [CLI Quick Reference](#cli-quick-reference)
62. [Decision Guide](#decision-guide)
73. [Production-Ready Config](#production-ready-config)
84. [Patterns](#patterns)
95. [Anti-Patterns](#anti-patterns)
106. [Troubleshooting](#troubleshooting)
117. [Related](#related)
12 
13> **When to use**: Setting up a new project, adjusting timeouts, adding browser targets, configuring CI behavior, or managing environment-specific settings.
14 
15## CLI Quick Reference
16 
17```bash
18npx playwright init                           # scaffold config + first test
19npx playwright test --config=custom.config.ts # use alternate config
20npx playwright test --project=chromium        # run single project
21npx playwright test --reporter=html           # override reporter
22npx playwright test --grep @smoke             # run tests tagged @smoke
23npx playwright test --grep-invert @slow       # exclude @slow tests
24npx playwright show-report                    # open last HTML report
25DEBUG=pw:api npx playwright test              # verbose logging
26```
27 
28## Decision Guide
29 
30### Timeout Selection
31 
32| Symptom | Setting | Default | Recommended |
33|---------|---------|---------|-------------|
34| Test takes too long overall | `timeout` | 30s | 30-60s (max 120s) |
35| Assertion retries too long/short | `expect.timeout` | 5s | 5-10s |
36| `page.goto()` or `waitForURL()` times out | `navigationTimeout` | 30s | 10-30s |
37| `click()`, `fill()` time out | `actionTimeout` | 0 (unlimited) | 10-15s |
38| Dev server slow to start | `webServer.timeout` | 60s | 60-180s |
39 
40### Server Management
41 
42| Scenario | Approach |
43|----------|----------|
44| App in same repo | `webServer` with `reuseExistingServer: !process.env.CI` |
45| Separate repos | Manual start or Docker Compose |
46| Testing deployed environment | No `webServer`; set `baseURL` via env |
47| Multiple services | Array of `webServer` entries |
48 
49### Single vs Multi-Project
50 
51| Scenario | Approach |
52|----------|----------|
53| Early development | Single project (chromium only) |
54| Pre-release validation | Multi-project: chromium + firefox + webkit |
55| Mobile-responsive app | Add mobile projects alongside desktop |
56| Auth + non-auth tests | Setup project with dependencies |
57| Tight CI budget | Chromium on PRs; all browsers on main |
58 
59### globalSetup vs Setup Projects vs Fixtures
60 
61| Need | Use |
62|------|-----|
63| One-time DB seed | `globalSetup` |
64| Shared browser auth | Setup project with `dependencies` |
65| Per-test isolated state | Custom fixture via `test.extend()` |
66| Cleanup after all tests | `globalTeardown` |
67 
68## Production-Ready Config
69 
70```ts
71// playwright.config.ts
72import { defineConfig, devices } from '@playwright/test';
73import dotenv from 'dotenv';
74import path from 'path';
75 
76dotenv.config({ path: path.resolve(__dirname, '.env') });
77 
78export default defineConfig({
79  testDir: './e2e',
80  testMatch: '**/*.spec.ts',
81 
82  fullyParallel: true,
83  forbidOnly: !!process.env.CI,
84  retries: process.env.CI ? 2 : 0,
85  workers: process.env.CI ? '50%' : undefined,
86 
87  reporter: process.env.CI
88    ? [['html', { open: 'never' }], ['github']]
89    : [['html', { open: 'on-failure' }]],
90 
91  timeout: 30_000,
92  expect: { timeout: 5_000 },
93 
94  use: {
95    baseURL: process.env.BASE_URL || 'http://localhost:4000',
96    actionTimeout: 10_000,
97    navigationTimeout: 15_000,
98    trace: 'on-first-retry',
99    screenshot: 'only-on-failure',
100    video: 'retain-on-failure',
101    locale: 'en-US',
102    timezoneId: 'America/Los_Angeles',
103  },
104 
105  projects: [
106    { name: 'chromium', use: { ...devices['Desktop Chrome'] } },
107    { name: 'firefox', use: { ...devices['Desktop Firefox'] } },
108    { name: 'webkit', use: { ...devices['Desktop Safari'] } },
109    { name: 'mobile-chrome', use: { ...devices['Pixel 7'] } },
110    { name: 'mobile-safari', use: { ...devices['iPhone 14'] } },
111  ],
112 
113  webServer: {
114    command: 'npm run start',
115    url: 'http://localhost:4000',
116    reuseExistingServer: !process.env.CI,
117    timeout: 120_000,
118    stdout: 'pipe',
119    stderr: 'pipe',
120  },
121});
122```
123 
124## Patterns
125 
126### Environment-Specific Configuration
127 
128**Use when**: Tests run against dev, staging, and production environments.
129 
130```ts
131// playwright.config.ts
132import { defineConfig } from '@playwright/test';
133import dotenv from 'dotenv';
134import path from 'path';
135 
136const ENV = process.env.TEST_ENV || 'local';
137dotenv.config({ path: path.resolve(__dirname, `.env.${ENV}`) });
138 
139const envConfig: Record<string, { baseURL: string; retries: number }> = {
140  local:   { baseURL: 'http://localhost:4000',      retries: 0 },
141  staging: { baseURL: 'https://staging.myapp.com',  retries: 2 },
142  prod:    { baseURL: 'https://myapp.com',          retries: 2 },
143};
144 
145export default defineConfig({
146  testDir: './e2e',
147  retries: envConfig[ENV].retries,
148  use: { baseURL: envConfig[ENV].baseURL },
149});
150```
151 
152```bash
153TEST_ENV=staging npx playwright test
154TEST_ENV=prod npx playwright test --grep @smoke
155```
156 
157### Setup Project with Dependencies
158 
159**Use when**: Tests need shared authentication state before running.
160 
161```ts
162// playwright.config.ts
163import { defineConfig, devices } from '@playwright/test';
164 
165export default defineConfig({
166  testDir: './e2e',
167  projects: [
168    {
169      name: 'setup',
170      testMatch: /auth\.setup\.ts/,
171    },
172    {
173      name: 'chromium',
174      use: {
175        ...devices['Desktop Chrome'],
176        storageState: 'playwright/.auth/session.json',
177      },
178      dependencies: ['setup'],
179    },
180    {
181      name: 'firefox',
182      use: {
183        ...devices['Desktop Firefox'],
184        storageState: 'playwright/.auth/session.json',
185      },
186      dependencies: ['setup'],
187    },
188  ],
189});
190```
191 
192```ts
193// e2e/auth.setup.ts
194import { test as setup, expect } from '@playwright/test';
195 
196const authFile = 'playwright/.auth/session.json';
197 
198setup('authenticate', async ({ page }) => {
199  await page.goto('/login');
200  await page.getByLabel('Username').fill('[email protected]');
201  await page.getByLabel('Password').fill(process.env.TEST_PASSWORD!);
202  await page.getByRole('button', { name: 'Log in' }).click();
203  await expect(page.getByRole('heading', { name: 'Home' })).toBeVisible();
204  await page.context().storageState({ path: authFile });
205});
206```
207 
208### webServer with Build Step
209 
210**Use when**: Tests need a running application server managed by Playwright.
211 
212```ts
213// playwright.config.ts
214import { defineConfig } from '@playwright/test';
215 
216export default defineConfig({
217  testDir: './e2e',
218  use: { baseURL: 'http://localhost:4000' },
219  webServer: {
220    command: process.env.CI
221      ? 'npm run build && npm run preview'
222      : 'npm run dev',
223    url: 'http://localhost:4000',
224    reuseExistingServer: !process.env.CI,
225    timeout: 120_000,
226    env: {
227      NODE_ENV: 'test',
228      DB_URL: process.env.DB_URL || 'postgresql://localhost:5432/testdb',
229    },
230  },
231});
232```
233 
234### globalSetup / globalTeardown
235 
236**Use when**: One-time non-browser work like seeding a database. Runs once per test run.
237 
238```ts
239// playwright.config.ts
240import { defineConfig } from '@playwright/test';
241 
242export default defineConfig({
243  testDir: './e2e',
244  globalSetup: './e2e/setup.ts',
245  globalTeardown: './e2e/teardown.ts',
246});
247```
248 
249```ts
250// e2e/setup.ts
251import { FullConfig } from '@playwright/test';
252 
253export default async function globalSetup(config: FullConfig) {
254  const { execSync } = await import('child_process');
255  execSync('npx prisma db seed', { stdio: 'inherit' });
256  process.env.TEST_RUN_ID = `run-${Date.now()}`;
257}
258```
259 
260```ts
261// e2e/teardown.ts
262import { FullConfig } from '@playwright/test';
263 
264export default async function globalTeardown(config: FullConfig) {
265  const { execSync } = await import('child_process');
266  execSync('npx prisma db push --force-reset', { stdio: 'inherit' });
267}
268```
269 
270### Environment Variables with .env
271 
272**Use when**: Managing secrets, URLs, or feature flags without hardcoding.
273 
274```bash
275# .env.example (commit this)
276BASE_URL=http://localhost:4000
277TEST_PASSWORD=
278API_KEY=
279 
280# .env.local (gitignored)
281BASE_URL=http://localhost:4000
282TEST_PASSWORD=secret123
283API_KEY=dev-key-abc
284 
285# .env.staging (gitignored)
286BASE_URL=https://staging.myapp.com
287TEST_PASSWORD=staging-pass
288API_KEY=staging-key-xyz
289```
290 
291```bash
292# .gitignore
293.env
294.env.local
295.env.staging
296.env.production
297playwright/.auth/
298```
299 
300Install dotenv:
301 
302```bash
303npm install -D dotenv
304```
305 
306### Tag-Based Test Filtering
307 
308**Use when**: Running subsets of tests in different CI stages (PR vs nightly).
309 
310```ts
311// playwright.config.ts
312import { defineConfig } from '@playwright/test';
313 
314export default defineConfig({
315  testDir: './e2e',
316 
317  // Filter by tags in CI
318  grep: process.env.CI ? /@smoke|@critical/ : undefined,
319  grepInvert: process.env.CI ? /@flaky/ : undefined,
320});
321```
322 
323**Project-specific filtering:**
324 
325```ts
326// playwright.config.ts
327import { defineConfig, devices } from '@playwright/test';
328 
329export default defineConfig({
330  testDir: './e2e',
331  projects: [
332    {
333      name: 'smoke',
334      grep: /@smoke/,
335      use: { ...devices['Desktop Chrome'] },
336    },
337    {
338      name: 'regression',
339      grepInvert: /@smoke/,
340      use: { ...devices['Desktop Chrome'] },
341    },
342    {
343      name: 'critical-only',
344      grep: /@critical/,
345      use: { ...devices['Desktop Chrome'] },
346    },
347  ],
348});
349```
350 
351```bash
352# Run specific project
353npx playwright test --project=smoke
354npx playwright test --project=regression
355```
356 
357### Artifact Collection Strategy
358 
359| Setting | Local | CI | Reason |
360|---------|-------|-----|--------|
361| `trace` | `'off'` | `'on-first-retry'` | Traces are large; collect on failure only |
362| `screenshot` | `'off'` | `'only-on-failure'` | Useful for CI debugging |
363| `video` | `'off'` | `'retain-on-failure'` | Recording slows tests |
364 
365```ts
366// playwright.config.ts
367import { defineConfig } from '@playwright/test';
368 
369export default defineConfig({
370  testDir: './e2e',
371  use: {
372    trace: process.env.CI ? 'on-first-retry' : 'off',
373    screenshot: process.env.CI ? 'only-on-failure' : 'off',
374    video: process.env.CI ? 'retain-on-failure' : 'off',
375  },
376});
377```
378 
379## Anti-Patterns
380 
381| Don't | Problem | Do Instead |
382|-------|---------|------------|
383| `timeout: 300_000` globally | Masks flaky tests; slow CI | Fix root cause; keep 30s default |
384| Hardcoded URLs: `page.goto('http://localhost:4000/login')` | Breaks in other environments | Use `baseURL` + relative paths |
385| All browsers on every PR | 3x CI time | Chromium on PRs; all on main |
386| `trace: 'on'` always | Huge artifacts, slow uploads | `trace: 'on-first-retry'` |
387| `video: 'on'` always | Massive storage; slow tests | `video: 'retain-on-failure'` |
388| Config in test files: `test.use({ viewport: {...} })` everywhere | Scattered, inconsistent | Define once in project config |
389| `retries: 3` locally | Hides flakiness | `retries: 0` local, `retries: 2` CI |
390| No `forbidOnly` in CI | Committed `test.only` runs single test | `forbidOnly: !!process.env.CI` |
391| `globalSetup` for browser auth | No browser context available | Use setup project with dependencies |
392| Committing `.env` with credentials | Security risk | Commit `.env.example` only |
393 
394## Troubleshooting
395 
396### baseURL Not Working
397 
398**Cause**: Using absolute URL in `page.goto()` ignores `baseURL`.
399 
400```ts
401// Wrong - ignores baseURL
402await page.goto('http://localhost:4000/dashboard');
403 
404// Correct - uses baseURL
405await page.goto('/dashboard');
406```
407 
408### webServer Starts But Tests Get Connection Refused
409 
410**Cause**: `webServer.url` doesn't match actual server address or health check returns non-200.
411 
412```ts
413webServer: {
414  command: 'npm run dev',
415  url: 'http://localhost:4000/api/health',  // use real endpoint
416  reuseExistingServer: !process.env.CI,
417  timeout: 120_000,
418},
419```
420 
421### Tests Pass Locally But Timeout in CI
422 
423**Cause**: CI machines are slower. Increase timeouts and reduce workers:
424 
425```ts
426export default defineConfig({
427  workers: process.env.CI ? '50%' : undefined,
428  use: {
429    navigationTimeout: process.env.CI ? 30_000 : 15_000,
430    actionTimeout: process.env.CI ? 15_000 : 10_000,
431  },
432});
433```
434 
435### "Target page, context or browser has been closed"
436 
437**Cause**: Test exceeded `timeout` and Playwright tore down browser during action.
438 
439**Fix**: Don't increase global timeout. Find slow step using trace:
440 
441```bash
442npx playwright test --trace on
443npx playwright show-report
444```
445 
446## Related
447 
448- [test-tags.md](./test-tags.md) - tagging and filtering tests with `--grep`
449- [fixtures-hooks.md](./fixtures-hooks.md) - custom fixtures for per-test state
450- [test-suite-structure.md](test-suite-structure.md) - file structure and naming
451- [authentication.md](../advanced/authentication.md) - setup projects for shared auth
452- [projects-dependencies.md](./projects-dependencies.md) - advanced multi-project patterns
453