How to View the HTML Report in Playwright
Run Playwright’s HTML reporter, open the report locally or in CI, troubleshoot common errors, and inspect tests, traces, and sharded results.
After a Playwright test run creates an HTML report, open it from your project directory with:
npx playwright show-reportPlaywright serves the report locally and opens it in your browser. The default report directory is playwright-report. If you saved the report somewhere else, pass that directory name:
npx playwright show-report my-reportYou can also open a report ZIP when index.html is at the archive root:
npx playwright show-report playwright-report.zipThis guide covers generating, opening, configuring, sharing, and troubleshooting Playwright HTML reports, including reports produced in CI and by sharded test runs.
1. Generate an HTML report
Run your tests with Playwright’s HTML reporter:
npx playwright test --reporter=htmlUnless you configure another location, Playwright writes the report to playwright-report. The report contains test outcomes, filters, searchable test names, errors, and recorded steps. If traces were collected, an individual test can link to its trace.
Configure the reporter in Playwright
For a project-wide configuration, set the reporter in playwright.config.ts:
import { defineConfig } from '@playwright/test';
export default defineConfig({
reporter: [['html', { open: 'on-failure' }]],
});The HTML reporter’s open setting accepts:
| Value | Behavior |
|---|---|
on-failure |
Open the report automatically when tests fail. This is the default. |
always |
Open the report after every run. |
never |
Generate the report without opening a browser. |
You can set the same behavior with the PLAYWRIGHT_HTML_OPEN environment variable. The output directory can be changed with the reporter’s outputFolder option or the PLAYWRIGHT_HTML_OUTPUT_DIR environment variable.
2. Open the default report
- Open a terminal in the project that has Playwright installed.
- Run
npx playwright show-report. - Visit the address printed by Playwright if the browser does not open automatically.
The documented default host is localhost, and the documented default port is 9323. If that port is already occupied, Playwright uses another available port.
Choose a host or port
Use --host or --port when you need a particular bind address or port:
npx playwright show-report --host 127.0.0.1 --port 9323A custom host or port is useful when accessing the report from another process, when a local port is already in use, or when a development environment forwards a specific port.
3. Open a report in a custom directory
If the HTML reporter wrote to a custom folder, pass that folder to show-report:
npx playwright show-report artifacts/playwright-reportThe argument must point to the report directory containing the generated HTML report. Run the command from a directory where Playwright is installed, or use the equivalent Playwright CLI available in your project.
4. View a downloaded report ZIP
Playwright can serve a report ZIP when its top level contains index.html:
npx playwright show-report playwright-report.zipPlaywright extracts the archive to a temporary directory and serves it. If the archive contains an extra wrapper directory, such as artifact/playwright-report/index.html, extract it first and pass the extracted report directory:
unzip playwright-report.zip -d extracted-report
npx playwright show-report extracted-report5. View a report produced in CI
CI systems usually upload the report directory or ZIP as an artifact. Download the artifact, then either pass the ZIP directly or extract it and pass the directory:
npx playwright show-report playwright-report.zip
# Or, for an extracted artifact:
npx playwright show-report downloaded-playwright-reportKeep the report’s supporting files together. Moving only index.html can make linked assets, test details, or traces unavailable.
6. Merge reports from sharded test runs
When tests run in shards, configure the runs to produce blob reports, collect those reports, and merge them into one HTML report:
npx playwright merge-reports --reporter html ./all-blob-reportsThe merge command writes the combined HTML report to playwright-report by default. Open it normally:
npx playwright show-reportMerge only compatible blob reports from the same test run. A missing shard can make the combined report incomplete, while mixing unrelated runs can produce confusing results.
7. What you can inspect in the HTML report
- Filters: narrow results by browser and outcome, including passed, failed, skipped, and flaky tests.
- Search: find a test by its name or location.
- Errors: inspect failure messages and stack details.
- Steps: open an individual test to review its recorded actions.
- Traces: open a trace when the test run collected one.
HTML reports are generated artifacts. If you need trace inspection, collect traces during the test run using your project’s trace configuration before opening the report.
8. Common problems and fixes
| Problem | Likely cause | Fix |
|---|---|---|
show-report cannot find the report |
The command is running in the wrong directory, or the report uses a custom output folder. | Run it from the project directory or pass the exact report directory: npx playwright show-report path/to/report. |
| The command opens an empty or incomplete report | The test run did not finish, the artifact is incomplete, or shard reports were mixed. | Regenerate or re-download the complete artifact. For shards, merge the complete set of blob reports from one run. |
| The browser does not open automatically | Automatic opening is disabled, the environment has no graphical browser, or the command is running remotely. | Open the printed localhost URL manually. Check the open setting and use --host or --port when needed. |
Port 9323 is unavailable |
Another process is using the port. | Pass another port, for example npx playwright show-report --port 9400. |
| A ZIP is rejected | index.html is not at the archive’s top level. |
Extract the ZIP, locate the directory containing index.html, and pass that directory to show-report. |
| Trace links do not work | Trace files were not included in the artifact or were separated from the report. | Upload the trace files with the report and preserve the generated directory structure. |
| Environment-variable settings appear ignored | The variable name is misspelled or overridden by explicit reporter configuration. | Check PLAYWRIGHT_HTML_OPEN and PLAYWRIGHT_HTML_OUTPUT_DIR, then inspect playwright.config.ts for explicit options. |
9. Performance, reliability, and artifact costs
- Keep reports local when debugging: serving a local directory avoids uploading large artifacts repeatedly.
- Control artifact size: traces, screenshots, and videos can increase CI artifact size. Collect them according to the failures you need to diagnose.
- Use one report per run: merge shard outputs from the same run so filters and totals describe one test execution.
- Preserve directory structure: report assets and trace links depend on files remaining together.
- Pin the Playwright version in CI: CLI options and report behavior are version-sensitive. Check the documentation matching the version installed by your project.
10. Or skip the browser setup
If your goal is to capture a website image or PDF rather than inspect Playwright test results, ScreenshotNeo provides a direct screenshot API and an MCP server for AI agents. It accepts a URL and returns a PNG, JPEG, WebP, or PDF.
One request is enough:
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpPython:
import requests
r = requests.get("https://api.screenshotneo.com/v1/shot", params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"}, timeout=90)
open("shot.webp", "wb").write(r.content)Node.js:
const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);See the ScreenshotNeo documentation for request options. Cookie banners, newsletter popups, and chat widgets are removed before the shot. Bot checks, blank pages, timeouts, failed loads, and cache hits are not billed, and response headers identify the page verdict and billing status. Its MCP server includes take_screenshot, get_page_info, and capture_pdf for Claude, Cursor, and other MCP clients. The free plan includes 1,000 screenshots per month with no card; paid plans start at $5 for 3,000 shots.
Start with 1,000 free screenshots a month—no card required.
11. FAQ
What command opens the latest Playwright HTML report?
Run npx playwright show-report from the project directory.
What is the default report folder?
The HTML reporter writes to playwright-report unless you configure another output folder.
Can I use a different port?
Yes. Pass --port, such as npx playwright show-report --port 9400.
Can Playwright open a report ZIP?
Yes, when index.html is at the ZIP’s top level. Otherwise extract the archive and pass the correct directory.
How do I combine reports from shards?
Use npx playwright merge-reports --reporter html ./all-blob-reports, then open the resulting playwright-report directory.
Why did Playwright not open a browser?
Automatic opening may be disabled, or the command may be running in a headless or remote environment. Open the printed URL manually or set the reporter’s open option to always.
