Outdated 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 matchPC Slower Than It Used to Be?
A free scan shows the junk files, broken settings and background clutter dragging Windows down - then fixes them in one click.Free scan · Windows 10 & 11The quickest way to run a Playwright Test script interactively is npx playwright test --debug. It opens the Playwright Inspector, launches a headed browser, removes the normal timeout, uses one worker, and stops after the first failure. Narrow the command to a file, line, or configured project when you already know where the problem is.
Start with the standard debug command
From the directory containing your Playwright configuration and tests, run:
npx playwright test --debugThe --debug shortcut combines several settings documented by Playwright: PWDEBUG=1, a zero test timeout, headed browser execution, one worker, and a maximum of one failure. The browser becomes visible and the Inspector lets you step through actions, pause execution, and inspect or edit locators. See the Playwright command-line documentation for the current option behavior.
Debug one file or one test location
Put the test file, and optionally its declaration line, before --debug:
Free tools Windows power users keep installed
One-click scans. No signup required.
#1 Best Overall
npx playwright test tests/example.spec.ts:10 --debugThe line suffix selects a test associated with that location; it is not a JavaScript statement breakpoint. Use the path and line that actually exist in your configured suite.
Debug one browser project
If your playwright.config defines multiple projects, add the project name:
npx playwright test --project=chromium --debugThis prevents unrelated Firefox, WebKit, or device projects from running while you investigate a Chromium-specific failure.
What the Inspector does
Inspector is the step-through interface opened by --debug. Start the run, then use its controls to resume, pause, and advance through test actions. You can pick an element in the browser and refine the locator shown by the Inspector before putting it in your test. Because the test timeout is disabled for this mode, you can stop at a breakpoint without a normal timeout terminating the test.
The Tool Desk
Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →Debug mode still executes your test code and fixtures. It does not automatically make assertions correct or bypass authentication, permissions, network failures, or application bugs. Keep the test data and environment stable so that each step represents the failure you are trying to understand.
Pause at an exact point with page.pause()
When you know the setup that must run first, insert a pause immediately before the suspicious action:
import { test, expect } from '@playwright/test';
test('checkout flow', async ({ page }) => {
await page.goto('https://example.com/checkout');
await page.pause();
await page.getByRole('button', { name: 'Pay now' }).click();
await expect(page.getByText('Confirmation')).toBeVisible();
});Run that test with npx playwright test --debug (or a narrowed file/project command). Inspector opens at the pause; resume when you have inspected the page, locator, or network state. Remove the pause after diagnosis so it does not stop ordinary runs.
Choose the right Playwright debugging interface
| Interface | Best for | What you can inspect | Typical command or entry point |
|---|---|---|---|
| Inspector | Interactive, step-by-step debugging | Actions, locator picking and editing, live headed browser | npx playwright test --debug |
| UI Mode | Selecting tests and reviewing a run over time | Timeline, action history, DOM snapshots, console, network, watch mode | npx playwright test --ui |
| VS Code extension | Breakpoints and test work inside the editor | Breakpoints, visible browser, locator matches, selected browser profile | Playwright Test sidebar and the extension’s debug controls |
| DevTools and logs | Browser or protocol-level failures | Console, network requests, browser launch diagnostics, verbose API calls | PWDEBUG=console, DEBUG=pw:api, or DEBUG=pw:browser |
UI Mode is a separate workflow, not an alias for Inspector. Start it with:
npx playwright test --uiUse its filters to select a project, tag, status, or test, then inspect the time-ordered trace-like view. It is particularly useful when you need to compare what happened immediately before and after a failure. Playwright documents its filters, snapshots, logs, network panel, and watch mode in the UI Mode guide.
For editor-centered work, the official VS Code integration provides test discovery, breakpoints, a visible browser, and locator inspection. Playwright’s documentation recommends the VS Code extension for a better debugging experience. Use it when the defect is easiest to understand alongside source code rather than in a separate Inspector window.
Use environment variables for specialized inspection
Expose the Playwright helper in Chromium DevTools
Run with:
PWDEBUG=console npx playwright test tests/example.spec.tsWith this setting, Chromium DevTools gains a playwright helper. The documented commands include playwright.$ and playwright.$$ for querying matches, inspecting an element, creating a locator, and deriving a selector from an element selected in DevTools. This is useful when the page looks right but a selector resolves to the wrong node.
Print every Playwright API call
DEBUG=pw:api npx playwright test tests/example.spec.tsThe output shows the sequence of Playwright calls and helps reveal where a wait, navigation, or assertion stalls. On Windows PowerShell, set the variable for the command’s process with $env:DEBUG="pw:api"; npx playwright test. In Command Prompt, use set DEBUG=pw:api && npx playwright test.
Quick wins for a faster PC:
Scan for outdated or missing drivers - takes under a minuteDriver Scan →Clear out junk files and repair common Windows errorsFree Scan →Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →Diagnose browser launch failures
DEBUG=pw:browser npx playwright testUse this when the browser never starts, a required executable is missing, or launch arguments are rejected. The browser-focused log is different from API tracing: it targets process startup and launch diagnostics.
Headed debugging outside the test runner
If you launch Playwright directly with the library rather than the Test runner, use a visible browser and, when useful, a small delay between operations:
import { chromium } from 'playwright';
const browser = await chromium.launch({ headless: false, slowMo: 150 });
const page = await browser.newPage();
await page.goto('https://example.com');
await page.pause();
await browser.close();headless: false makes the browser visible. slowMo slows operations so you can watch sequencing; it does not replace a breakpoint or a reliable wait. If you need fixtures, retries, projects, reporters, or parallel test management, use the Test runner command instead.
Linux and CI: headed browsers need a display
Playwright browsers are headless by default. A headed run on a Linux agent needs an X server; the documented approach is Xvfb:
Do these 3 things before closing this tab:
1Repair Windows errors before they cause bigger problems2Fix the driver behind crashes, sound loss and screen glitches3Clear out junk files and repair common Windows errorsxvfb-run npx playwright testIn CI, interactive Inspector windows are usually impractical. Prefer a focused test, trace artifacts, API logs, and browser launch diagnostics. If a headed launch fails on Linux, first confirm that Xvfb is installed and that the command is wrapped with xvfb-run. The Continuous Integration guide covers this requirement and pw:browser diagnostics.
A repeatable debugging workflow
- Reproduce narrowly. Start with
npx playwright test path/to/test.spec.ts:line --project=chromium --debugrather than the entire suite. - Stop before the failure. Add
await page.pause()after navigation, login, or data setup, whichever establishes the state you need to inspect. - Check the locator. Use Inspector’s picker or DevTools’
playwright.$helpers to see how many elements match and whether the accessible name is what the test expects. - Separate timing from correctness. Run once with
DEBUG=pw:api. A long wait may indicate a missing state transition, a blocked request, or a selector that never matches. - Inspect browser evidence. Open console and network tools for JavaScript errors, failed requests, redirects, blocked resources, and unexpected responses.
- Remove temporary controls. Delete pauses, restore normal timeouts and workers, and rerun the focused test without debug flags before changing the test permanently.
Troubleshooting common debug-mode problems
The command says Playwright is not found
Run it from the project that declares @playwright/test, or use the package runner shown above so the local dependency is selected. If browser binaries are missing, install the browsers with the Playwright installation command appropriate to your project, then retry.
The browser opens and closes immediately
Confirm that you used --debug on the Test runner command and that the targeted file actually contains a matching test. For a deliberate stopping point, add await page.pause(). A test that finishes successfully has no reason to remain open.
A locator works manually but fails in the test
Pause after the page reaches the expected state and inspect the matching elements. Check frames, role and accessible name, strict-mode multiple matches, and whether the element is covered or disabled. Prefer a semantic locator such as getByRole when its name is stable; do not “fix” a timing problem by adding an arbitrary sleep.
Best Value
Debug mode still times out
--debug sets the test timeout to zero, but an application-level wait, navigation timeout, fixture timeout, or external process can still be the bottleneck. Use DEBUG=pw:api to identify the call that is waiting and inspect network activity for a request that never completes.
Headed mode fails on a Linux runner
Run the command through Xvfb: xvfb-run npx playwright test. If the browser process itself fails, collect DEBUG=pw:browser output and check the runner’s installed browser dependencies.
Only one browser is failing
Reproduce with the corresponding configured project, for example --project=webkit --debug. Compare viewport, user agent, permissions, and browser-specific console or network errors before changing shared test code.
Or skip the browser setup
If your goal is a clean image of a page rather than interactive test diagnosis, ScreenshotNeo returns a screenshot or PDF through one request. Its cleanup step accepts cookie or consent banners and removes more than 60 known consent platforms, newsletter popups, and chat widgets; each cleanup action can be disabled. Bot checks, CAPTCHAs, blank pages, timeouts, failed loads, and cache hits are not billed, and response headers identify the page verdict and whether it was billed. It also provides an MCP server for Claude, Cursor, and other MCP clients, with take_screenshot, get_page_info, and capture_pdf tools.
Recommended Free Tools
cURL:
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. It supports full-page and element captures, device presets or custom viewports, retina scale, dark mode, PDFs, HTML/CSS rendering, custom JavaScript and CSS, clicks, waits, blocking rules, headers, cookies, user agents, authorization, timezone and geolocation, transparent backgrounds, resizing, chosen cache TTLs, signed links, asynchronous webhooks, bulk capture of up to 100 URLs per call, usage reporting, and an OpenAPI specification. The parameter names used by other screenshot APIs also work, which can simplify migration.
Every plan includes those features: 1,000 screenshots per month free with no card; paid plans start at $5 for 3,000 shots, with yearly billing giving two months free. Sign up free for ScreenshotNeo and get the 1,000 monthly screenshots without a card.
Further reading
- Playwright Debugging Tests for Inspector, pauses, console mode, and API logging.
- Running and debugging tests for command usage and runner workflows.
- Command line for the exact
--debugdefaults and selectors. - Continuous Integration for Linux display requirements and launch diagnostics.
Frequently Asked Questions
How do I debug one Playwright test?
Pass its file and, when useful, declaration line before the flag: npx playwright test tests/example.spec.ts:10 --debug. Add --project=chromium to select one configured browser project.
How do I pause a Playwright test at a specific line?
Insert await page.pause() at that point, then run the test with npx playwright test --debug. Inspector opens at the pause and resumes when you continue.
What is the difference between –debug and –ui?
--debug opens Inspector for live step-through interaction; --ui provides test selection plus a timeline with snapshots, logs, console, and network information.
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.
