Use Playwright Test’s CLI to run tests, projects to cover different browser configurations, UI Mode or the Inspector to debug, and reports and traces to understand failures. A reliable workflow starts with a user-visible assertion, then narrows each run to the test or browser project you need; generated code and retries help investigation, but neither proves a test is correct.
Write and run your first Playwright Test
A Playwright Test file imports the runner’s test and expect functions. The runner supplies fixtures such as page, which gives a test a browser page to control. Fixtures provide isolated setup for tests, so write each test around the behavior it needs to verify.
import { test, expect } from '@playwright/test';
test('home page has the expected title', async ({ page }) => {
await page.goto('https://example.com');
await expect(page).toHaveTitle(/Example Domain/);
});The navigation opens the page; the web-first assertion waits for the expected title to appear, up to the assertion timeout. This is generally more resilient than checking immediately after navigation: pages often need time to render or update.
Run the suite or narrow the target
Run the configured suite from the project directory with:
#1 Best Overall
npx playwright testThe CLI guide documents headless execution and parallel tests as defaults. Results appear in the terminal. To watch a browser interact with the page, use npx playwright test --headed. For a focused run, pass a test file or directory, a line number, a title filter, or a project name:
npx playwright test tests/home.spec.ts
npx playwright test tests/
npx playwright test tests/home.spec.ts:3
npx playwright test -g "home page has the expected title"
npx playwright test --project=chromiumUse --workers=1 to run with one worker. This can make a run easier to follow when investigating order-dependent behavior, though a single-worker run does not by itself identify or fix the cause.
Generate a test, then make it yours
npx playwright codegen opens a browser and records interactions as code. Supply a URL to begin at a page:
npx playwright codegen https://example.comCode generation can target languages including JavaScript, Playwright Test, and Python. Its CLI options include an output file and a test-ID attribute setting. Consult Playwright’s code-generation guide for current option syntax and supported targets.
Treat generated code as a draft. Check that its steps represent the user behavior you intend to protect, that its locators are meaningful and stable, and that it asserts a meaningful outcome. A recorded click sequence without an assertion may replay successfully while failing to detect a broken feature. Locator suggestions also need review: prefer locators that reflect robust, user-facing attributes and behavior rather than incidental page structure. See Playwright’s best-practices guidance.
Choose an interface for authoring and debugging
UI Mode for interactive work
Run npx playwright test --ui to open UI Mode. It presents the test tree and lets you run a file, block, or individual test; filter by text, tag, project, or status; watch for changes; and use a locator picker. Its timeline and action views help you inspect snapshots, logs, and network activity around a particular action.
Use it when you are iterating on a test or need context around an interaction. UI Mode records traces during interactive work, so you can inspect actions without separately setting up retry-triggered trace collection.
Inspector for step-through debugging
For a command-line debugging session, run:
npx playwright test --debugThe Playwright Inspector opens alongside a browser so you can step through execution. Narrow the target by adding a file and line, for example npx playwright test tests/home.spec.ts:3 --debug. Use headed mode when you want to observe browser behavior without the Inspector’s step-through workflow; use a normal CLI run for quick, repeatable checks.
Do these 3 things before closing this tab:
1Scan for outdated or missing drivers - takes under a minute2Clear out junk files and repair common Windows errors3Fix the driver behind crashes, sound loss and screen glitchesVS Code
The official Playwright extension for VS Code can run tests from the Testing sidebar. This is a convenient way to launch a selected test while editing; use the CLI when you want a command you can repeat in a terminal or CI workflow. The official running-tests guide describes the available run and debug paths.
Use projects to cover browsers and configurations
A project is a named group of tests with a configuration. Define projects in playwright.config.ts, then run all configured projects or select one with --project=<name>. Projects can represent different browsers or devices, but can also vary test matching, retries, timeouts, setup dependencies, and environments.
The documented examples include Chromium, Firefox, WebKit, branded Chrome and Edge, and emulated mobile or tablet devices. Choose a project matrix based on the browsers and environments your application supports; the names are not interchangeable browser installations.
| Project dimension | What to decide |
|---|---|
| Engine or browser | Whether coverage should use Chromium, Firefox, WebKit, or a branded browser such as Chrome or Edge. |
| Device profile | Whether the suite needs desktop coverage, emulated mobile or tablet configurations, or both. |
| Environment and setup | Which environment a project targets and whether it depends on setup tests or another project. |
| Execution policy | Whether project-specific retry and timeout settings suit the tests and how much runtime the matrix can use. |
Run one project while diagnosing a browser-specific failure, then run the intended matrix before treating the change as covered across configurations. If projects use setup dependencies, account for them when working in UI Mode: its project-filtering workflow does not automatically account for setup tests.
Free tools Windows power users keep installed
One-click scans. No signup required.
Project configuration and the current UI Mode workflow are documented in the projects guide and UI Mode guide.
Inspect reports and traces after a run
HTML report
After a test run, open the HTML report with:
npx playwright show-reportThe report lets you search and filter results and inspect details such as errors, steps, browser, and trace links. Start with the failing test’s error and steps; open its trace when you need to reconstruct what the browser did around the failure.
Trace Viewer
Open a recorded trace file in the GUI with:
npx playwright show-trace path/to/trace.zipTrace Viewer lets you move through actions and inspect snapshots, source, console output, network activity, and action details. The browser-hosted viewer documentation says the trace is loaded in the browser without being transmitted externally. That does not decide where your trace file is stored or who can access it; handle trace artifacts according to your team’s data-access and retention practices.
Collect traces selectively in CI
A common documented configuration is to capture a trace on the first retry, paired in the guide’s example with two retries in CI and zero locally:
import { defineConfig } from '@playwright/test';
export default defineConfig({
retries: process.env.CI ? 2 : 0,
use: {
trace: 'on-first-retry',
},
});This policy preserves a useful artifact when a CI failure is retried, without recording a trace for every ordinary run. The right capture and retention settings depend on your workflow. A retry can expose intermittent behavior and provide diagnostic evidence; a passing retry does not establish that the original failure was harmless or that the test is sound.
See the official Trace Viewer guide for trace inspection and collection options.
Keep runs useful and failures diagnosable
- Make assertions describe outcomes. Assert a title, visible state, or other relevant user-facing result rather than stopping after navigation or an interaction.
- Start narrow, then expand. Reproduce with one file or project, inspect the error and trace, and then run the broader configured suite to check for regressions.
- Use parallelism deliberately. Parallel execution is the documented default. If a failure is hard to follow, try
--workers=1as a diagnostic; investigate shared state or ordering rather than assuming serial execution is the final fix. - Keep traces useful and controlled. Retry-triggered capture can reduce routine artifact volume, but traces still need appropriate storage, access, and retention choices.
- Review generated locators. A locator that happens to work on one page state may be brittle. Align it with the intended behavior and keep assertions tied to the feature requirement.
Troubleshoot common Playwright Test problems
The test passes locally but fails in CI
Open the HTML report and the trace for the failed attempt, if one was recorded. Compare the action sequence, snapshots, console, and network details to identify whether the page state, timing, or environment differed. If the run has no trace, consider retry-triggered tracing for CI. Avoid increasing timeouts or retries without evidence about the failure mechanism.
A test times out waiting for an assertion
Check whether the expected state actually appears, whether navigation reached the intended page, and whether the locator identifies the intended element. Web-first assertions retry only until their assertion timeout; they cannot make an incorrect expectation or locator valid. Use UI Mode or Trace Viewer to inspect the snapshots around the failed action.
Quick wins for a faster PC:
Repair Windows errors before they cause bigger problemsFix Now →Scan for outdated or missing drivers - takes under a minuteDriver Scan →Clear out junk files and repair common Windows errorsFree Scan →A locator from codegen is unreliable
Review the generated locator against the live page and intended user behavior. Replace incidental selectors with a locator tied to a stable, user-facing attribute or a deliberately maintained test ID where appropriate. Re-run the focused test and then the relevant project matrix.
Project filtering misses required setup
Check whether the selected project depends on setup tests. UI Mode’s project filtering does not automatically account for setup tests in that workflow. Run the needed setup as configured or select a workflow that includes the dependency before interpreting the test result.
You cannot find a report or trace
Confirm that the test run completed and that the report or trace was configured or generated for that run. show-report opens the HTML report; show-trace requires the path to a trace ZIP. A trace policy such as on-first-retry does not produce a trace for every test attempt.
Or skip the browser setup
Playwright is the right tool when you need to exercise application behavior and assertions. If the task is simply to capture a website screenshot, ScreenshotNeo provides a one-request API instead of a browser automation setup. Its capture flow accepts cookie or consent banners and removes more than 60 known consent platforms, newsletter popups, and chat widgets before the shot; each cleanup step can be turned off. Bot checks or CAPTCHAs, blank pages, timeouts, failed loads, and cache hits are not billed, and the response identifies the page verdict and billing status in headers.
Windows Errors? Fix Them Before They Spread
Repair common Windows errors and clear accumulated junk for a smoother, more stable PC - no reinstall needed.Free scan · no reinstallOutdated Drivers Are Slowing You Down
One free scan finds every outdated or missing driver and matches the right update for your exact hardware.Free scan · exact hardware matchFor example, this cURL request saves a WebP screenshot of Stripe:
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpSee the ScreenshotNeo API documentation for request options. ScreenshotNeo also has an MCP server with take_screenshot, get_page_info, and capture_pdf tools 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. ScreenshotNeo is made by Yorker Media. Sign up free to get 1,000 screenshots a month with no card.
Frequently Asked Questions
Does Playwright Test require UI Mode?
No. UI Mode is an interactive option; the CLI can run and report tests without opening it.
Does a passing retry mean the failure can be ignored?
No. A retry is a diagnostic opportunity, not proof that the first failure or the test itself is safe.
The Tool Desk
Outbyte PC Repair FREEClear out junk files and repair common Windows errorsFree Scan →Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
