How to Run a Playwright Script in Debug Mode
Run Playwright tests interactively with Inspector, UI Mode, breakpoints, browser logs, and practical fixes for local and Linux CI debugging.
The quickest way to run a Playwright Test script in debug mode is:
npx playwright test --debugThis starts Playwright Inspector with a headed browser, disables the test timeout, uses one worker, and stops after the first failure. To focus on one test file and line, run:
npx playwright test tests/example.spec.ts:10 --debugYou can also limit the run to a configured browser project:
npx playwright test --project=chromium --debugThese commands use the JavaScript or TypeScript Playwright Test runner. The --debug shortcut is documented as equivalent to enabling PWDEBUG=1, setting --timeout=0, --max-failures=1, --headed, and --workers=1. See the official Playwright command-line documentation and debugging guide.
Run one Playwright test in Inspector
- Open a terminal in your Playwright project.
- Choose the narrowest target: the whole suite, a file, a file and line, or a configured project.
- Run the target with
--debug. - Use Inspector controls to step through actions, resume execution, inspect locators, and edit or pick selectors.
# Entire configured suite
npx playwright test --debug
# One file
npx playwright test tests/example.spec.ts --debug
# A test near a declaration line
npx playwright test tests/example.spec.ts:10 --debug
# One browser project
npx playwright test --project=chromium tests/example.spec.ts --debugThe file and line selector must match a test in your configured suite. A line number is a filter for the test declaration; it is not a JavaScript breakpoint on every statement.
Understand what --debug changes
| Setting | Debug behavior | Why it helps |
|---|---|---|
| Browser | Headed | You can see the page while actions run. |
| Timeout | Zero | Interactive inspection is not cut off by the normal test timeout. |
| Workers | One | Actions from multiple workers do not overlap while you investigate. |
| Failures | Stop after one failure | The first problem receives your attention before later failures add noise. |
Because timeout is disabled for this mode, remember to restore a normal timeout when you run the suite for CI or regression checking.
Pause at an exact point with page.pause()
For a breakpoint in test code, add await page.pause() immediately before the action you want to inspect:
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('Payment complete')).toBeVisible();
});Start that test with npx playwright test tests/checkout.spec.ts --debug. Inspector pauses at the statement and lets you inspect the current page before resuming. Remove the pause after diagnosing the issue.
Use UI Mode when you need a timeline
Inspector is best for stepping through live actions. UI Mode is better when you need to select tests and review what happened around a failure:
npx playwright test --uiAccording to the UI Mode documentation, it provides test filters, project and status selection, watch mode, a time-oriented view, action details, DOM snapshots, console output, and network activity. Use it when the question is “what happened before and after this action?” rather than “what happens if I step past this line?”
Debug from VS Code
The Playwright VS Code extension adds test controls, breakpoints, a visible browser, browser-profile selection, and locator inspection in the editor. The Playwright team recommends the extension for debugging. Follow the official VS Code guide, open the Testing view, select the test or project, and start it with debugging enabled.
Inspect browser logs and API calls
Playwright API logging
Set DEBUG=pw:api to print verbose Playwright API calls:
DEBUG=pw:api npx playwright test tests/example.spec.tsOn Windows PowerShell, set the variable for the command:
$env:DEBUG="pw:api"; npx playwright test tests/example.spec.tsBrowser launch diagnostics
If the browser fails before the test starts, use:
DEBUG=pw:browser npx playwright testThese logs help distinguish a test failure from a browser executable, dependency, or launch problem. The Playwright CI documentation covers this diagnostic setting.
DevTools with PWDEBUG=console
Run with PWDEBUG=console to expose a playwright helper in browser DevTools. The documented helpers include:
playwright.$('button')
playwright.$$('a')
playwright.inspect('button')You can query matching elements, inspect one, create a locator, and derive a selector from an element selected in DevTools. Keep this mode for browser-side inspection; use DEBUG=pw:api for Playwright’s operation log.
Debug a standalone Playwright script
If you use Playwright outside the Test runner, launch a headed browser and slow actions down:
import { chromium } from 'playwright';
const browser = await chromium.launch({
headless: false,
slowMo: 250
});
const page = await browser.newPage();
await page.goto('https://example.com');
await page.pause();
await browser.close();headless: false opens a visible browser. slowMo adds a delay to operations so you can observe them. For a standalone script, use your own breakpoint or page.pause(); the npx playwright test --debug shortcut applies to the Playwright Test runner.
Run headed debugging on Linux CI
Linux agents normally run browsers headlessly. Headed execution needs an X server; the documented approach is Xvfb:
xvfb-run npx playwright test --debugIf this fails, first run DEBUG=pw:browser npx playwright test to capture browser-launch diagnostics, then verify that the CI image has the required browser dependencies and Xvfb. Headed debugging is usually most useful on a local desktop; in CI, UI Mode traces and logs are often easier to collect.
Choose the right debugging workflow
| Need | Use | Command or action |
|---|---|---|
| Step through a failing test live | Inspector | npx playwright test --debug |
| Target one test | Inspector with scope | npx playwright test file.spec.ts:10 --debug |
| Pause at a statement | Code pause | await page.pause() |
| Review actions, snapshots, console, and network | UI Mode | npx playwright test --ui |
| Use editor breakpoints | VS Code extension | Testing view and debug controls |
| See Playwright operations | API logs | DEBUG=pw:api |
| Investigate browser startup | Browser logs | DEBUG=pw:browser |
| Inspect from browser DevTools | Console helper | PWDEBUG=console |
Common errors and fixes
“The browser window does not appear”
Cause: the run is still headless, the process is running on a Linux machine without a display, or the browser exited during launch.
Fix: use --debug or headless: false. On Linux, run under xvfb-run. Add DEBUG=pw:browser to see launch details.
“The test times out while I inspect it”
Cause: the test was not started in debug mode and still has its normal timeout.
Fix: rerun with --debug, or set a deliberate timeout while diagnosing. The debug shortcut sets timeout to zero.
“My line filter runs no test”
Cause: the file path or line does not identify a configured test declaration.
Fix: run the file alone first, confirm the path, then use a line near the test(...) declaration. Check the configured projects if the test is excluded.
“Several tests interfere with each other”
Cause: parallel workers or shared state make the failure non-deterministic.
Fix: use --debug, which sets one worker, and narrow the run to one file or project.
“Inspector cannot connect in a Linux job”
Cause: headed browsers need a display server.
Fix: use xvfb-run for headed execution, or collect UI Mode evidence and logs in a headless environment.
“The browser starts but the selector is wrong”
Cause: the locator does not match the current DOM, or the page has not reached the expected state.
Fix: pause before the action, inspect the DOM in Inspector or DevTools, try role and label locators, and use playwright.$ or playwright.$$ with PWDEBUG=console.
Performance, reliability, and cost notes
- Debug mode deliberately trades speed for visibility: one worker, a headed browser, and an unlimited timeout make a run slower than normal.
- Scope the command to a file, line, or project so unrelated tests do not add startup time or confusing failures.
- Use UI Mode or collected traces when you need repeatable evidence from a headless environment instead of leaving a browser paused.
- Keep
--debug,page.pause(), and diagnostic environment variables out of regular CI commands unless the job is specifically a debugging job. - These Playwright commands run on your machines and do not add a ScreenshotNeo charge. ScreenshotNeo billing applies only when you use its screenshot API.
Or skip the browser setup
If your goal is a clean screenshot rather than debugging a browser test, ScreenshotNeo returns a PNG, JPEG, WebP, or PDF from one GET request. Its capture pipeline accepts cookie and consent banners like a visitor, then removes more than 60 known consent platforms, newsletter popups, and chat widgets before the shot. Each step can be turned off.
Failed loads, bot checks or CAPTCHAs, blank pages, timeouts, and cache hits are not billed, and response headers report the page verdict and billing status. ScreenshotNeo also provides an MCP server with take_screenshot, get_page_info, and capture_pdf tools for Claude, Cursor, and other MCP clients.
Read the ScreenshotNeo API documentation for options such as full-page capture, CSS element selection, device presets, dark mode, custom CSS and JavaScript, waits, request blocking, headers, cookies, geolocation, caching, signed links, async jobs, bulk capture, and usage reporting.
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}`);The Free plan includes 1,000 screenshots each month with no card. Paid plans start at $5 for 3,000 shots, and every feature is available on every plan. Create a free ScreenshotNeo account.
FAQ
How do I debug one Playwright test?
Pass its file and, when useful, a declaration line: npx playwright test tests/example.spec.ts:10 --debug.
How do I pause a Playwright test at a specific line?
Insert await page.pause() before the action, then run the test with --debug.
Is UI Mode the same as Inspector?
No. Inspector is for live step-through debugging; UI Mode is for selecting tests and reviewing timelines, snapshots, logs, console output, and network activity.
Can I debug a selected browser?
Yes. Use the configured project name, for example npx playwright test --project=chromium --debug.
Why does headed mode need Xvfb?
Linux CI agents usually lack a display server. Xvfb supplies the virtual display required by a headed browser.
