1# Test Reports & Artifacts
2 
3## Table of Contents
4 
51. [CLI Commands](#cli-commands)
62. [Reporter Configuration](#reporter-configuration)
73. [Custom Reporter](#custom-reporter)
84. [Trace Configuration](#trace-configuration)
95. [Screenshot & Video Settings](#screenshot--video-settings)
106. [Artifact Directory Structure](#artifact-directory-structure)
117. [CI Artifact Upload](#ci-artifact-upload)
128. [Decision Guide](#decision-guide)
139. [Anti-Patterns](#anti-patterns)
1410. [Troubleshooting](#troubleshooting)
15 
16> **When to use**: Configuring test output for debugging, CI dashboards, and team visibility.
17 
18## CLI Commands
19 
20```bash
21# Display last HTML report
22npx playwright show-report
23 
24# Specify reporter
25npx playwright test --reporter=html
26npx playwright test --reporter=dot           # minimal CI output
27npx playwright test --reporter=line          # one line per test
28npx playwright test --reporter=json          # machine-readable
29npx playwright test --reporter=junit         # CI integration
30 
31# Combine reporters
32npx playwright test --reporter=dot,html
33 
34# Merge sharded reports
35npx playwright merge-reports --reporter=html ./blob-report
36```
37 
38## Reporter Configuration
39 
40### Environment-Based Setup
41 
42```typescript
43// playwright.config.ts
44import { defineConfig } from '@playwright/test';
45 
46export default defineConfig({
47  reporter: process.env.CI
48    ? [
49        ['dot'],
50        ['html', { open: 'never' }],
51        ['junit', { outputFile: 'results/junit.xml' }],
52        ['github'],
53      ]
54    : [
55        ['list'],
56        ['html', { open: 'on-failure' }],
57      ],
58});
59```
60 
61### Reporter Types
62 
63| Reporter | Output | Use Case |
64|---|---|---|
65| `list` | One line per test | Local development |
66| `line` | Single updating line | Local, less verbose |
67| `dot` | `.` pass, `F` fail | CI logs |
68| `html` | Interactive HTML page | Post-run analysis |
69| `json` | Machine-readable JSON | Custom tooling |
70| `junit` | JUnit XML | CI platforms |
71| `github` | PR annotations | GitHub Actions |
72| `blob` | Binary archive | Shard merging |
73 
74### JSON Output to File
75 
76```typescript
77import { defineConfig } from '@playwright/test';
78 
79export default defineConfig({
80  reporter: [
81    ['json', { outputFile: 'results/output.json' }],
82  ],
83});
84```
85 
86### JUnit Customization
87 
88```typescript
89import { defineConfig } from '@playwright/test';
90 
91export default defineConfig({
92  reporter: [
93    ['junit', {
94      outputFile: 'results/junit.xml',
95      stripANSIControlSequences: true,
96      includeProjectInTestName: true,
97    }],
98  ],
99});
100```
101 
102## Custom Reporter
103 
104Build custom reporters for Slack notifications, database logging, or dashboards.
105 
106```typescript
107// reporters/notification-reporter.ts
108import type {
109  FullResult,
110  Reporter,
111  TestCase,
112  TestResult,
113} from '@playwright/test/reporter';
114 
115class NotificationReporter implements Reporter {
116  private passed = 0;
117  private failed = 0;
118  private skipped = 0;
119  private failures: string[] = [];
120 
121  onTestEnd(test: TestCase, result: TestResult) {
122    switch (result.status) {
123      case 'passed':
124        this.passed++;
125        break;
126      case 'failed':
127      case 'timedOut':
128        this.failed++;
129        this.failures.push(`${test.title}: ${result.error?.message?.split('\n')[0]}`);
130        break;
131      case 'skipped':
132        this.skipped++;
133        break;
134    }
135  }
136 
137  async onEnd(result: FullResult) {
138    const total = this.passed + this.failed + this.skipped;
139    const status = this.failed > 0 ? 'FAILED' : 'PASSED';
140    const message = [
141      `Tests ${status}`,
142      `Passed: ${this.passed} | Failed: ${this.failed} | Skipped: ${this.skipped}`,
143      `Duration: ${(result.duration / 1000).toFixed(1)}s`,
144    ];
145 
146    if (this.failures.length > 0) {
147      message.push('', 'Failures:');
148      this.failures.slice(0, 5).forEach((f) => message.push(`  - ${f}`));
149      if (this.failures.length > 5) {
150        message.push(`  ...and ${this.failures.length - 5} more`);
151      }
152    }
153 
154    const webhookUrl = process.env.NOTIFICATION_WEBHOOK;
155    if (webhookUrl) {
156      const controller = new AbortController();
157      const timeout = setTimeout(() => controller.abort(), 5000);
158      try {
159        await fetch(webhookUrl, {
160          method: 'POST',
161          headers: { 'Content-Type': 'application/json' },
162          body: JSON.stringify({ text: message.join('\n') }),
163          signal: controller.signal,
164        });
165      } catch (error) {
166        // Intentionally swallow notifier failures to avoid blocking test completion
167        console.warn('Webhook notification failed:', error.message);
168      } finally {
169        clearTimeout(timeout);
170      }
171    }
172  }
173}
174 
175export default NotificationReporter;
176```
177 
178**Register custom reporter:**
179 
180```typescript
181import { defineConfig } from '@playwright/test';
182 
183export default defineConfig({
184  reporter: [
185    ['dot'],
186    ['html', { open: 'never' }],
187    ['./reporters/notification-reporter.ts'],
188  ],
189});
190```
191 
192## Trace Configuration
193 
194Traces capture actions, network requests, DOM snapshots, and console logs.
195 
196```typescript
197import { defineConfig } from '@playwright/test';
198 
199export default defineConfig({
200  retries: process.env.CI ? 2 : 0,
201  use: {
202    trace: 'on-first-retry',
203  },
204});
205```
206 
207### Trace Options
208 
209| Value | Behavior | Overhead |
210|---|---|---|
211| `'off'` | Never records | None |
212| `'on'` | Every test | High |
213| `'on-first-retry'` | On first retry after failure | Minimal |
214| `'retain-on-failure'` | Records all, keeps failures | Medium |
215| `'retain-on-first-failure'` | Records all, keeps first failure | Medium |
216 
217### Viewing Traces
218 
219```bash
220# Local trace viewer
221npx playwright show-trace results/my-test/trace.zip
222 
223# From HTML report (click Traces tab)
224npx playwright show-report
225 
226# Online viewer: https://trace.playwright.dev
227```
228 
229## Screenshot & Video Settings
230 
231```typescript
232import { defineConfig } from '@playwright/test';
233 
234export default defineConfig({
235  use: {
236    screenshot: 'only-on-failure',
237    video: 'retain-on-failure',
238  },
239});
240```
241 
242### Video with Custom Size
243 
244```typescript
245use: {
246  video: {
247    mode: 'retain-on-failure',
248    size: { width: 1280, height: 720 },
249  },
250},
251```
252 
253### Screenshot Options
254 
255| Value | Captures | Disk Cost |
256|---|---|---|
257| `'off'` | Never | None |
258| `'on'` | Every test | High |
259| `'only-on-failure'` | Failed tests | Low |
260 
261### Video Options
262 
263| Value | Records | Keeps | Disk Cost |
264|---|---|---|---|
265| `'off'` | Never | — | None |
266| `'on'` | Every test | All | Very high |
267| `'on-first-retry'` | On retry | Retried | Low |
268| `'retain-on-failure'` | Every test | Failed | Medium |
269 
270## Artifact Directory Structure
271 
272```text
273test-results/
274├── checkout-test-chromium/
275│   ├── trace.zip
276│   ├── test-failed-1.png
277│   └── video.webm
278├── login-test-firefox/
279│   ├── trace.zip
280│   └── test-failed-1.png
281└── junit.xml
282 
283playwright-report/
284├── index.html
285└── data/
286 
287blob-report/
288└── report-1.zip
289```
290 
291## CI Artifact Upload
292 
293### GitHub Actions
294 
295```yaml
296- uses: actions/upload-artifact@v4
297  if: ${{ !cancelled() }}
298  with:
299    name: playwright-report
300    path: playwright-report/
301    retention-days: 14
302 
303- uses: actions/upload-artifact@v4
304  if: failure()
305  with:
306    name: test-traces
307    path: |
308      test-results/**/trace.zip
309      test-results/**/*.png
310      test-results/**/*.webm
311    retention-days: 7
312```
313 
314## Decision Guide
315 
316| Scenario | Reporter Configuration |
317|---|---|
318| Local development | `[['list'], ['html', { open: 'on-failure' }]]` |
319| GitHub Actions | `[['dot'], ['html'], ['github']]` |
320| GitLab CI | `[['dot'], ['html'], ['junit']]` |
321| Azure DevOps / Jenkins | `[['dot'], ['html'], ['junit']]` |
322| Sharded CI | `[['blob'], ['github']]` |
323| Custom dashboard | `[['json', { outputFile: '...' }]]` + custom reporter |
324 
325| Artifact | When to Collect | Retention | Upload Condition |
326|---|---|---|---|
327| HTML report | Always | 14 days | `if: ${{ !cancelled() }}` |
328| Traces | On failure | 7 days | `if: failure()` |
329| Screenshots | On failure | 7 days | `if: failure()` |
330| Videos | On failure | 7 days | `if: failure()` |
331| JUnit XML | Always | 14 days | `if: ${{ !cancelled() }}` |
332| Blob report | Always (sharded) | 1 day | `if: ${{ !cancelled() }}` |
333 
334## Anti-Patterns
335 
336| Anti-Pattern | Problem | Solution |
337|---|---|---|
338| No reporter configured | Default `list` only; no persistent report | Configure `html` + CI reporter |
339| `trace: 'on'` in CI | Massive artifacts, slow uploads | Use `trace: 'on-first-retry'` |
340| `video: 'on'` in CI | Enormous storage, slower tests | Use `video: 'retain-on-failure'` |
341| Upload artifacts only on failure | No report when tests pass | Upload with `if: ${{ !cancelled() }}` |
342| No retention limits | CI storage fills quickly | Set `retention-days: 7-14` |
343| Only `dot` reporter | Cannot drill into failures | Pair `dot` with `html` |
344| JUnit to stdout | Interferes with console output | Write to file |
345| Blocking `onEnd` in custom reporter | Slow HTTP calls delay pipeline | Use `Promise.race` with timeout |
346 
347## Troubleshooting
348 
349### Empty HTML Report
350 
351Check reporter config. HTML report defaults to `playwright-report/`:
352 
353```typescript
354import { defineConfig } from '@playwright/test';
355 
356export default defineConfig({
357  reporter: [['html', { outputFolder: 'playwright-report', open: 'never' }]],
358});
359```
360 
361### Traces Too Large
362 
363Switch from `trace: 'on'` to `'on-first-retry'` with retries enabled:
364 
365```typescript
366import { defineConfig } from '@playwright/test';
367 
368export default defineConfig({
369  retries: process.env.CI ? 2 : 0,
370  use: {
371    trace: 'on-first-retry',
372  },
373});
374```
375 
376### JUnit XML Not Recognized
377 
378Ensure path matches CI configuration:
379 
380```typescript
381reporter: [['junit', { outputFile: 'results/junit.xml' }]],
382```
383 
384```yaml
385# GitHub Actions
386- uses: dorny/test-reporter@latest
387  with:
388    path: results/junit.xml
389    reporter: java-junit
390 
391# Azure DevOps
392- task: PublishTestResults@latest
393  inputs:
394    testResultsFiles: 'results/junit.xml'
395 
396# Jenkins
397junit 'results/junit.xml'
398```
399 
400### Empty Merged Report
401 
402Use `blob` reporter for sharded runs (not `html`):
403 
404```typescript
405import { defineConfig } from '@playwright/test';
406 
407export default defineConfig({
408  reporter: process.env.CI
409    ? [['blob'], ['dot']]
410    : [['html', { open: 'on-failure' }]],
411});
412```
413 
414### Missing Screenshots in Report
415 
416Enable screenshots and keep both directories:
417 
418```typescript
419use: {
420  screenshot: 'only-on-failure',
421},
422```
423 
424The HTML report embeds screenshots from `test-results/`. Deleting that directory removes screenshots from the report.
425