0
# Reporting
1

2
Comprehensive reporting system with built-in reporters and custom reporter support for various output formats, test result analysis, and CI/CD integration.
3

4
## Capabilities
5

6
### Reporter Configuration
7

8
Configuration options for built-in and custom reporters with support for multiple output formats.
9

10
```typescript { .api }
11
/**
12
 * Reporter configuration description
13
 */
14
type ReporterDescription = 
15
  | 'list' 
16
  | 'dot' 
17
  | 'line' 
18
  | 'json' 
19
  | 'junit' 
20
  | 'html' 
21
  | 'blob' 
22
  | 'github'
23
  | 'null'
24
  | [string]
25
  | [string, any]
26
  | ['list', ListReporterOptions]
27
  | ['junit', JUnitReporterOptions]
28
  | ['json', JsonReporterOptions] 
29
  | ['html', HtmlReporterOptions]
30
  | ['blob', BlobReporterOptions];
31

32
/**
33
 * Built-in reporter option interfaces
34
 */
35
interface ListReporterOptions {
36
  printSteps?: boolean;
37
}
38

39
interface JUnitReporterOptions {
40
  outputFile?: string;
41
  stripANSIControlSequences?: boolean;
42
  includeProjectInTestName?: boolean;
43
}
44

45
interface JsonReporterOptions {
46
  outputFile?: string;
47
}
48

49
interface HtmlReporterOptions {
50
  outputFolder?: string;
51
  open?: 'always' | 'never' | 'on-failure';
52
  host?: string;
53
  port?: number;
54
  attachmentsBaseURL?: string;
55
  title?: string;
56
  noSnippets?: boolean;
57
}
58

59
interface BlobReporterOptions {
60
  outputDir?: string;
61
  fileName?: string;
62
}
63
```
64

65
**Usage Examples:**
66

67
```typescript
68
import { defineConfig } from "@playwright/test";
69

70
export default defineConfig({
71
  // Single reporter
72
  reporter: "html",
73
  
74
  // Multiple reporters
75
  reporter: [
76
    ["html", { outputFolder: "reports/html" }],
77
    ["json", { outputFile: "reports/results.json" }],
78
    ["junit", { outputFile: "reports/junit.xml" }],
79
  ],
80
  
81
  // Custom reporter
82
  reporter: [
83
    ["./custom-reporter.js", { option: "value" }]
84
  ],
85
});
86
```
87

88
### Custom Reporter Interface
89

90
Interface for implementing custom reporters with complete test lifecycle hooks.
91

92
```typescript { .api }
93
/**
94
 * Custom reporter interface for extending test reporting
95
 */
96
interface Reporter {
97
  /**
98
   * Called once before running all tests
99
   * @param config - Full test configuration
100
   * @param suite - Root test suite
101
   */
102
  onBegin?(config: FullConfig, suite: Suite): void;
103
  
104
  /**
105
   * Called for each test when it starts running
106
   * @param test - Test case metadata
107
   * @param result - Test result object (initial state)
108
   */
109
  onTestBegin?(test: TestCase, result: TestResult): void;
110
  
111
  /**
112
   * Called for each test when it finishes
113
   * @param test - Test case metadata
114
   * @param result - Complete test result
115
   */
116
  onTestEnd?(test: TestCase, result: TestResult): void;
117
  
118
  /**
119
   * Called for each step when it starts
120
   * @param test - Test case metadata
121
   * @param result - Test result containing the step
122
   * @param step - Test step metadata
123
   */
124
  onStepBegin?(test: TestCase, result: TestResult, step: TestStep): void;
125
  
126
  /**
127
   * Called for each step when it finishes
128
   * @param test - Test case metadata  
129
   * @param result - Test result containing the step
130
   * @param step - Complete test step result
131
   */
132
  onStepEnd?(test: TestCase, result: TestResult, step: TestStep): void;
133
  
134
  /**
135
   * Called after all tests finish
136
   * @param result - Full test run result
137
   */
138
  onEnd?(result: FullResult): void;
139
  
140
  /**
141
   * Called on unexpected errors during test execution
142
   * @param error - Error information
143
   */
144
  onError?(error: TestError): void;
145
  
146
  /**
147
   * Called when output is written to stdout during test execution
148
   * @param chunk - Output data
149
   * @param test - Test case that produced the output (if any)
150
   * @param result - Test result (if any)
151
   */
152
  onStdOut?(chunk: string | Buffer, test?: TestCase, result?: TestResult): void;
153
  
154
  /**
155
   * Called when output is written to stderr during test execution
156
   * @param chunk - Output data
157
   * @param test - Test case that produced the output (if any)
158
   * @param result - Test result (if any)
159
   */
160
  onStdErr?(chunk: string | Buffer, test?: TestCase, result?: TestResult): void;
161
}
162
```
163

164
### Test Result Interfaces
165

166
Comprehensive result data structures for test execution analysis and reporting.
167

168
```typescript { .api }
169
/**
170
 * Complete test run results
171
 */
172
interface FullResult {
173
  /**
174
   * Overall test run status
175
   */
176
  status: 'passed' | 'failed' | 'timedout' | 'interrupted';
177
  
178
  /**
179
   * Total test run duration in milliseconds
180
   */
181
  startTime: Date;
182
  
183
  /**
184
   * Test execution statistics
185
   */
186
  duration: number;
187
}
188

189
/**
190
 * Individual test case metadata and configuration
191
 */
192
interface TestCase {
193
  /**
194
   * Test case title
195
   */
196
  title: string;
197
  
198
  /**
199
   * Full test title including parent suite names
200
   */
201
  titlePath(): string[];
202
  
203
  /**
204
   * Test file location
205
   */
206
  location: { file: string; line: number; column: number };
207
  
208
  /**
209
   * Parent test suite
210
   */
211
  parent: Suite;
212
  
213
  /**
214
   * Test expected status
215
   */
216
  expectedStatus: 'passed' | 'failed' | 'skipped';
217
  
218
  /**
219
   * Test timeout in milliseconds
220
   */
221
  timeout: number;
222
  
223
  /**
224
   * Test annotations
225
   */
226
  annotations: { type: string; description?: string }[];
227
  
228
  /**
229
   * Test retry count
230
   */
231
  retries: number;
232
  
233
  /**
234
   * Associated test project
235
   */
236
  project(): FullProject;
237
  
238
  /**
239
   * Test case results across all retries
240
   */
241
  results: TestResult[];
242
  
243
  /**
244
   * Outcome of the last test result
245
   */
246
  outcome(): 'skipped' | 'expected' | 'unexpected' | 'flaky';
247
}
248

249
/**
250
 * Single test execution result
251
 */
252
interface TestResult {
253
  /**
254
   * Test execution status
255
   */
256
  status: 'passed' | 'failed' | 'timedOut' | 'skipped' | 'interrupted';
257
  
258
  /**
259
   * Test execution duration in milliseconds
260
   */
261
  duration: number;
262
  
263
  /**
264
   * Test start time
265
   */
266
  startTime: Date;
267
  
268
  /**
269
   * Test retry attempt number
270
   */
271
  retry: number;
272
  
273
  /**
274
   * Test execution parallelism index
275
   */
276
  parallelIndex: number;
277
  
278
  /**
279
   * Worker process index
280
   */
281
  workerIndex: number;
282
  
283
  /**
284
   * Test execution errors
285
   */
286
  errors: TestError[];
287
  
288
  /**
289
   * Test result attachments
290
   */
291
  attachments: Attachment[];
292
  
293
  /**
294
   * Test execution steps
295
   */
296
  steps: TestStep[];
297
  
298
  /**
299
   * Standard output during test execution
300
   */
301
  stdout: { text: string; timestamp: Date }[];
302
  
303
  /**
304
   * Standard error during test execution
305
   */
306
  stderr: { text: string; timestamp: Date }[];
307
}
308

309
/**
310
 * Test suite hierarchy representation
311
 */
312
interface Suite {
313
  /**
314
   * Suite title
315
   */
316
  title: string;
317
  
318
  /**
319
   * Parent suite (undefined for root)
320
   */
321
  parent?: Suite;
322
  
323
  /**
324
   * Child test suites
325
   */
326
  suites: Suite[];
327
  
328
  /**
329
   * Test cases in this suite
330
   */
331
  tests: TestCase[];
332
  
333
  /**
334
   * Full suite title path
335
   */
336
  titlePath(): string[];
337
  
338
  /**
339
   * All tests in this suite and child suites
340
   */
341
  allTests(): TestCase[];
342
  
343
  /**
344
   * Suite location in source file
345
   */
346
  location?: { file: string; line: number; column: number };
347
}
348

349
/**
350
 * Test step information for hierarchical test organization
351
 */
352
interface TestStep {
353
  /**
354
   * Step title
355
   */
356
  title: string;
357
  
358
  /**
359
   * Step category
360
   */
361
  category: string;
362
  
363
  /**
364
   * Step start time
365
   */
366
  startTime: Date;
367
  
368
  /**
369
   * Step duration in milliseconds
370
   */
371
  duration: number;
372
  
373
  /**
374
   * Step execution error (if any)
375
   */
376
  error?: TestError;
377
  
378
  /**
379
   * Parent step (for nested steps)
380
   */
381
  parent?: TestStep;
382
  
383
  /**
384
   * Child steps
385
   */
386
  steps: TestStep[];
387
  
388
  /**
389
   * Step location in source code
390
   */
391
  location?: { file: string; line: number; column: number };
392
}
393
```
394

395
### Error and Attachment Types
396

397
Data structures for test failures, debugging information, and test artifacts.
398

399
```typescript { .api }
400
/**
401
 * Test execution error information
402
 */
403
interface TestError {
404
  /**
405
   * Error message
406
   */
407
  message?: string;
408
  
409
  /**
410
   * Stack trace
411
   */
412
  stack?: string;
413
  
414
  /**
415
   * Error location in source code
416
   */
417
  location?: { file: string; line: number; column: number };
418
  
419
  /**
420
   * Associated test step (if any)
421
   */
422
  snippet?: string;
423
}
424

425
/**
426
 * Test result attachment (screenshot, video, trace, etc.)
427
 */
428
interface Attachment {
429
  /**
430
   * Attachment name
431
   */
432
  name: string;
433
  
434
  /**
435
   * MIME content type
436
   */
437
  contentType: string;
438
  
439
  /**
440
   * File path to attachment
441
   */
442
  path?: string;
443
  
444
  /**
445
   * Attachment body (for small attachments)
446
   */
447
  body?: Buffer;
448
}
449
```
450

451
### Built-in Reporter Types
452

453
Description of built-in reporters and their output formats.
454

455
```typescript { .api }
456
/**
457
 * List Reporter - Detailed step-by-step output
458
 * Shows test progress with detailed step information
459
 */
460
type ListReporter = 'list';
461

462
/**
463
 * Dot Reporter - Compact progress indicator
464
 * Shows single character per test result
465
 */
466
type DotReporter = 'dot';
467

468
/**
469
 * Line Reporter - Single line progress
470
 * Updates single line with current test status
471
 */
472
type LineReporter = 'line';
473

474
/**
475
 * JSON Reporter - Structured test results
476
 * Outputs complete test results as JSON
477
 */
478
type JsonReporter = 'json';
479

480
/**
481
 * JUnit Reporter - JUnit XML format
482
 * Compatible with CI/CD systems expecting JUnit format
483
 */
484
type JUnitReporter = 'junit';
485

486
/**
487
 * HTML Reporter - Interactive web report
488
 * Generates browsable HTML report with filtering and trace viewer
489
 */
490
type HtmlReporter = 'html';
491

492
/**
493
 * Blob Reporter - Binary blob format
494
 * Efficient format for report merging and storage
495
 */
496
type BlobReporter = 'blob';
497

498
/**
499
 * GitHub Reporter - GitHub Actions integration
500
 * Optimized output for GitHub Actions CI environment
501
 */
502
type GitHubReporter = 'github';
503

504
/**
505
 * Null Reporter - No output
506
 * Suppresses all test output
507
 */
508
type NullReporter = 'null';
509
```
510

511
**Usage Examples:**
512

513
```typescript
514
// Custom reporter implementation
515
class CustomReporter implements Reporter {
516
  onBegin(config: FullConfig, suite: Suite) {
517
    console.log(`Starting test run with ${suite.allTests().length} tests`);
518
  }
519
  
520
  onTestEnd(test: TestCase, result: TestResult) {
521
    const status = result.status;
522
    const duration = result.duration;
523
    console.log(`${test.title}: ${status} (${duration}ms)`);
524
  }
525
  
526
  onEnd(result: FullResult) {
527
    console.log(`Test run ${result.status} after ${result.duration}ms`);
528
  }
529
}
530

531
// Export for use in configuration
532
module.exports = CustomReporter;
533
```
534

535
### Runtime Configuration Access
536

537
Interface for accessing resolved configuration during test execution.
538

539
```typescript { .api }
540
/**
541
 * Complete resolved configuration available at runtime
542
 */
543
interface FullConfig {
544
  /**
545
   * Root directory for tests
546
   */
547
  rootDir: string;
548
  
549
  /**
550
   * Resolved projects configuration
551
   */
552
  projects: FullProject[];
553
  
554
  /**
555
   * Global test timeout
556
   */
557
  timeout: number;
558
  
559
  /**
560
   * Worker count
561
   */
562
  workers: number;
563
  
564
  /**
565
   * Configuration file path
566
   */
567
  configFile?: string;
568
  
569
  /**
570
   * Test report output directory
571
   */
572
  outputDir: string;
573
  
574
  /**
575
   * Reporter configuration
576
   */
577
  reporter: ReporterDescription[];
578
  
579
  /**
580
   * Web server configuration (if any)  
581
   */
582
  webServer?: WebServerConfig;
583
}
584

585
/**
586
 * Resolved project configuration
587
 */
588
interface FullProject {
589
  /**
590
   * Project name
591
   */
592
  name: string;
593
  
594
  /**
595
   * Project test directory
596
   */
597
  testDir: string;
598
  
599
  /**
600
   * Project output directory
601
   */
602
  outputDir: string;
603
  
604
  /**
605
   * Resolved project options
606
   */
607
  use: PlaywrightTestOptions;
608
  
609
  /**
610
   * Project dependencies
611
   */
612
  dependencies: string[];
613
  
614
  /**
615
   * Project timeout
616
   */
617
  timeout: number;
618
}
619
```