0
# Configuration
1

2
Configuration system for test execution, browser options, and project setup with support for multiple environments, parallel execution, and custom reporting.
3

4
## Capabilities
5

6
### Configuration Definition
7

8
Main function for defining Playwright Test configuration with support for multiple projects and shared options.
9

10
```typescript { .api }
11
/**
12
 * Define Playwright Test configuration with type safety
13
 * @param config - Configuration object with test settings
14
 * @returns Typed configuration object
15
 */
16
function defineConfig(config: PlaywrightTestConfig): PlaywrightTestConfig;
17

18
/**
19
 * Define configuration with custom fixtures
20
 * @param config - Configuration object with custom fixture types
21
 * @returns Typed configuration with extended fixtures  
22
 */
23
function defineConfig<TestArgs, WorkerArgs>(
24
  config: PlaywrightTestConfig<TestArgs, WorkerArgs>
25
): PlaywrightTestConfig<TestArgs, WorkerArgs>;
26
```
27

28
**Usage Examples:**
29

30
```typescript
31
import { defineConfig, devices } from "@playwright/test";
32

33
// Basic configuration
34
export default defineConfig({
35
  testDir: "./tests",
36
  timeout: 30000,
37
  use: {
38
    baseURL: "http://localhost:3000",
39
    headless: true,
40
  },
41
});
42

43
// Multi-project configuration
44
export default defineConfig({
45
  projects: [
46
    {
47
      name: "chromium",
48
      use: { ...devices["Desktop Chrome"] },
49
    },
50
    {
51
      name: "firefox", 
52
      use: { ...devices["Desktop Firefox"] },
53
    },
54
  ],
55
});
56
```
57

58
### Test Configuration Interface
59

60
Main configuration interface for global test settings and project definitions.
61

62
```typescript { .api }
63
interface PlaywrightTestConfig<TestArgs = {}, WorkerArgs = {}> {
64
  /**
65
   * Directory containing test files
66
   */
67
  testDir?: string;
68
  
69
  /**
70
   * Test timeout in milliseconds
71
   */
72
  timeout?: number;
73
  
74
  /**
75
   * Maximum number of test retries
76
   */
77
  retries?: number;
78
  
79
  /**
80
   * Number of parallel worker processes
81
   */
82
  workers?: number;
83
  
84
  /**
85
   * Shared options for all tests
86
   */
87
  use?: UseOptions<TestArgs, WorkerArgs>;
88
  
89
  /**
90
   * Project configurations for multi-project setup
91
   */
92
  projects?: TestProject<TestArgs, WorkerArgs>[];
93
  
94
  /**
95
   * Reporter configuration
96
   */
97
  reporter?: ReporterDescription[];
98
  
99
  /**
100
   * Output directory for test artifacts
101
   */
102
  outputDir?: string;
103
  
104
  /**
105
   * Test file patterns to match
106
   */
107
  testMatch?: string | RegExp | (string | RegExp)[];
108
  
109
  /**
110
   * Test file patterns to ignore
111
   */
112
  testIgnore?: string | RegExp | (string | RegExp)[];
113
  
114
  /**
115
   * Global setup file
116
   */
117
  globalSetup?: string;
118
  
119
  /**
120
   * Global teardown file
121
   */
122
  globalTeardown?: string;
123
  
124
  /**
125
   * Maximum number of test failures before stopping
126
   */
127
  maxFailures?: number;
128
  
129
  /**
130
   * Expect configuration
131
   */
132
  expect?: {
133
    timeout?: number;
134
    toHaveScreenshot?: {
135
      threshold?: number;
136
      mode?: 'buffer' | 'base64';
137
    };
138
    toMatchSnapshot?: {
139
      threshold?: number;
140
      mode?: 'buffer' | 'base64';
141
    };
142
  };
143
  
144
  /**
145
   * Web server configuration for development servers
146
   */
147
  webServer?: {
148
    command: string;
149
    port?: number;
150
    url?: string;
151
    timeout?: number;
152
    reuseExistingServer?: boolean;
153
  };
154
}
155
```
156

157
### Project Configuration
158

159
Project-specific configuration for multi-browser and multi-environment testing.
160

161
```typescript { .api }
162
interface TestProject<TestArgs = {}, WorkerArgs = {}> {
163
  /**
164
   * Project identifier name
165
   */
166
  name: string;
167
  
168
  /**
169
   * Project-specific test options
170
   */
171
  use?: UseOptions<TestArgs, WorkerArgs>;
172
  
173
  /**
174
   * Test directory for this project
175
   */
176
  testDir?: string;
177
  
178
  /**
179
   * Test file patterns to match for this project
180
   */
181
  testMatch?: string | RegExp | (string | RegExp)[];
182
  
183
  /**
184
   * Test file patterns to ignore for this project
185
   */
186
  testIgnore?: string | RegExp | (string | RegExp)[];
187
  
188
  /**
189
   * Project dependencies (other projects that must run first)
190
   */
191
  dependencies?: string[];
192
  
193
  /**
194
   * Timeout for tests in this project
195
   */
196
  timeout?: number;
197
  
198
  /**
199
   * Project-specific output directory
200
   */
201
  outputDir?: string;
202
  
203
  /**
204
   * Project-specific retries configuration
205
   */
206
  retries?: number;
207
}
208
```
209

210
### Test Options
211

212
Comprehensive test execution options including browser configuration, debugging tools, and test behavior settings.
213

214
```typescript { .api }
215
interface PlaywrightTestOptions {
216
  /**
217
   * Base URL for page navigation
218
   */
219
  baseURL?: string;
220
  
221
  /**
222
   * Browser execution mode
223
   */
224
  headless?: boolean;
225
  
226
  /**
227
   * Browser viewport size
228
   */
229
  viewport?: { width: number; height: number } | null;
230
  
231
  /**
232
   * Browser type selection
233
   */
234
  browserName?: 'chromium' | 'firefox' | 'webkit';
235
  
236
  /**
237
   * Browser launch options
238
   */
239
  launchOptions?: LaunchOptions;
240
  
241
  /**
242
   * Browser context options
243
   */
244
  contextOptions?: BrowserContextOptions;
245
  
246
  /**
247
   * Ignore HTTPS certificate errors
248
   */
249
  ignoreHTTPSErrors?: boolean;
250
  
251
  /**
252
   * Screenshot capture mode
253
   */
254
  screenshot?: 'off' | 'only-on-failure' | 'on';
255
  
256
  /**
257
   * Video recording mode  
258
   */
259
  video?: 'off' | 'on' | 'retain-on-failure' | 'on-first-retry';
260
  
261
  /**
262
   * Execution trace recording mode
263
   */
264
  trace?: 'off' | 'on' | 'retain-on-failure' | 'on-first-retry';
265
  
266
  /**
267
   * Browser storage state for authentication persistence
268
   */
269
  storageState?: string | { cookies: Cookie[]; origins: Origin[] };
270
  
271
  /**
272
   * User locale for browser
273
   */
274
  locale?: string;
275
  
276
  /**
277
   * Timezone for browser
278
   */
279
  timezoneId?: string;
280
  
281
  /**
282
   * Geolocation coordinates
283
   */
284
  geolocation?: { latitude: number; longitude: number };
285
  
286
  /**
287
   * Browser permissions
288
   */
289
  permissions?: string[];
290
  
291
  /**
292
   * Color scheme preference
293
   */
294
  colorScheme?: 'light' | 'dark' | 'no-preference';
295
  
296
  /**
297
   * Extra HTTP headers
298
   */
299
  extraHTTPHeaders?: { [key: string]: string };
300
  
301
  /**
302
   * HTTP authentication credentials
303
   */
304
  httpCredentials?: { username: string; password: string };
305
  
306
  /**
307
   * Offline mode simulation
308
   */
309
  offline?: boolean;
310
  
311
  /**
312
   * Download behavior
313
   */
314
  acceptDownloads?: boolean;
315
}
316
```
317

318
### Device Configuration
319

320
Pre-configured device settings for mobile and desktop testing.
321

322
```typescript { .api }
323
/**
324
 * Pre-configured device settings
325
 */
326
const devices: {
327
  'Desktop Chrome': PlaywrightTestOptions;
328
  'Desktop Firefox': PlaywrightTestOptions;
329
  'Desktop Safari': PlaywrightTestOptions;
330
  'iPhone 12': PlaywrightTestOptions;
331
  'iPhone 13': PlaywrightTestOptions;
332
  'Pixel 5': PlaywrightTestOptions;
333
  'iPad Pro': PlaywrightTestOptions;
334
  [deviceName: string]: PlaywrightTestOptions;
335
};
336
```
337

338
**Usage Examples:**
339

340
```typescript
341
import { defineConfig, devices } from "@playwright/test";
342

343
export default defineConfig({
344
  projects: [
345
    // Desktop browsers
346
    {
347
      name: "chromium",
348
      use: { ...devices["Desktop Chrome"] },
349
    },
350
    {
351
      name: "firefox",
352
      use: { ...devices["Desktop Firefox"] },
353
    },
354
    // Mobile devices
355
    {
356
      name: "Mobile Chrome",
357
      use: { ...devices["Pixel 5"] },
358
    },
359
    {
360
      name: "Mobile Safari",
361
      use: { ...devices["iPhone 12"] },
362
    },
363
  ],
364
});
365
```
366

367
### Test Utilities
368

369
Helper functions for advanced test configuration scenarios.
370

371
```typescript { .api }
372
/**
373
 * Merge multiple test types with different fixtures
374
 * @param tests - Array of test objects to merge
375
 * @returns Combined test object with merged fixtures
376
 */
377
function mergeTests<T extends Record<string, any>[]>(...tests: T): MergedTest<T>;
378

379
/**
380
 * Merge multiple expect implementations
381
 * @param expects - Array of expect objects to merge
382
 * @returns Combined expect with merged matchers
383
 */
384
function mergeExpects<T extends Record<string, any>[]>(...expects: T): MergedExpect<T>;
385
```
386

387
**Usage Examples:**
388

389
```typescript
390
import { test as base, expect as baseExpect, mergeTests, mergeExpects } from "@playwright/test";
391
import { test as dbTest, expect as dbExpect } from "./fixtures/database";
392
import { test as apiTest, expect as apiExpected } from "./fixtures/api";
393

394
// Merge test fixtures
395
export const test = mergeTests(base, dbTest, apiTest);
396

397
// Merge expect matchers  
398
export const expect = mergeExpects(baseExpected, dbExpect, apiExpected);
399
```
400

401
### Environment Configuration
402

403
Configuration options for test environment setup and teardown.
404

405
```typescript { .api }
406
interface WebServerConfig {
407
  /**
408
   * Command to start the development server
409
   */
410
  command: string;
411
  
412
  /**
413
   * Port number for the server
414
   */
415
  port?: number;
416
  
417
  /**
418
   * URL to check server availability
419
   */
420
  url?: string;
421
  
422
  /**
423
   * Timeout for server startup in milliseconds
424
   */
425
  timeout?: number;
426
  
427
  /**
428
   * Whether to reuse existing server instance
429
   */
430
  reuseExistingServer?: boolean;
431
  
432
  /**
433
   * Working directory for server command
434
   */
435
  cwd?: string;
436
  
437
  /**
438
   * Environment variables for server process
439
   */
440
  env?: { [key: string]: string };
441
}
442
```
443

444
**Usage Examples:**
445

446
```typescript
447
export default defineConfig({
448
  webServer: {
449
    command: "npm run dev",
450
    port: 3000,
451
    reuseExistingServer: !process.env.CI,
452
  },
453
  use: {
454
    baseURL: "http://localhost:3000",
455
  },
456
});
457
```