The Tool Desk
Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →To open the Playwright Inspector for an existing Playwright Test project, run npx playwright test --debug. It launches a headed browser and the Inspector, where you can pause, step through test actions, inspect why an action is waiting, and refine locators. To focus on one test, specify its file and optionally a line number; to stop at a chosen point, add await page.pause(); to the test.
Open the Inspector with the shortest command
From your Playwright project directory, run:
npx playwright test --debugThis starts the test in a headed browser and opens the Playwright Inspector. Playwright’s debug mode sets the default timeout to zero, so actions do not stop merely because the normal default timeout expires. A test can still wait indefinitely if it is blocked; use the Inspector controls and action log to investigate rather than assuming the test has frozen. See Playwright’s running and debugging guide.
The Inspector toolbar lets you play or pause execution and step through test actions. As you step, the current action is highlighted in the code and corresponding page elements are highlighted in the browser.
Focus debugging on one test or execution point
Run one test file
Pass a test file before --debug to avoid running the whole suite:
#1 Best Overall
npx playwright test example.spec.ts --debugStart at a particular line
Add a colon and line number after the file name to focus on the test located there:
npx playwright test example.spec.ts:10 --debugReplace the example filename and line number with the path and line for your test.
Pause at a chosen point with page.pause()
If the relevant state occurs after many setup steps, put this call where you want execution to stop:
await page.pause();Then run the test in debug mode, for example with npx playwright test example.spec.ts --debug. The test stops at the pause call; choose Resume in the Inspector to continue. This lets you inspect the page at that point without stepping manually through every earlier action. Remove the pause call when you have finished debugging so it does not interrupt later runs.
PC 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 & 11Outdated 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 matchUse actionability logs to diagnose a waiting action
When a click or other action is pending, inspect its actionability log in the Inspector before changing the test. The log can show whether the locator resolved and whether the element was visible, enabled, stable, and scrolled into view. If an action cannot meet its required conditions, it may remain pending until the page changes or the condition becomes true.
- If the locator does not resolve, check that it identifies the element present at this point in the test and that the page has reached the expected state.
- If the element is not visible or enabled, inspect the page for overlays, disabled controls, or a missing prerequisite action.
- If the element is not stable, check whether an animation or layout change is still moving it.
- If scrolling is involved, confirm that the intended element is the one being brought into view.
Use the log to identify the unmet condition; do not add arbitrary sleeps or loosen a locator before you know what is blocking the action.
Pick and refine a locator in the live page
- In the Inspector, select Pick Locator.
- Hover over the intended element in the browser. The Inspector displays a locator for the element under the pointer.
- Click the element to place that locator in the Inspector field.
- Edit the locator and check whether it highlights the intended element. Copy the useful result into your test.
Prefer a locator that expresses the element’s meaning to a user or an explicit test contract: for example, a role with an accessible name, visible text, or a test ID. Playwright’s locator guidance explains these choices. A locator is resolved against the current DOM when an action uses it, so it can find the element again after a re-render instead of relying on a retained reference to an old DOM node.
Consider a generated locator a starting point, not an automatic guarantee of a durable test. Check that it matches the intended control and remains meaningful if the page’s markup changes. When several elements match, make the locator specific enough to identify the right one.
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 errorsChoose Inspector, Codegen, UI Mode, or VS Code for the job
| Workflow | Best fit | What it provides |
|---|---|---|
| Inspector debug mode | Debug an existing test | Step through test API calls, inspect actionability logs, and pick or edit locators live. |
| Codegen | Start a test from browser interactions | Records actions and can generate locators and assertions. Start it with npx playwright codegen <url>; the browser and Inspector open together. |
| UI Mode | Broader test debugging and monitoring | A broader debugging experience with a locator picker and watch mode. |
| VS Code extension | Debug from the IDE | Its own breakpoint and live-debugging workflows. |
Codegen can generate visibility, text, or value assertions. After recording, stop the recording and use Pick Locator to select and copy locators. It can also be opened from custom browser setup by launching headed and calling page.pause(). See the official Codegen guide and Playwright best practices. Use Inspector debug mode when you need to understand an existing test’s execution; choose Codegen to record new interactions, or UI Mode and VS Code when their broader or IDE-integrated workflows suit the task. Playwright’s workflows can overlap, but they start from different needs.
Troubleshooting common Inspector problems
The command does not open the browser or Inspector
Run the command from the project that uses Playwright Test and confirm the test file is included by that project’s setup. If you intended to debug one test, pass its file path before --debug. Command-line behavior can vary with Playwright versions; consult the Playwright Test CLI reference for the version installed in your project.
The test appears stuck on an action
Debug mode’s zero default timeout can leave a blocked action waiting rather than timing out at the normal default. Inspect the actionability log for the unmet condition—such as an unresolved locator, invisibility, disabled state, instability, or scrolling—then address the actual page or locator issue.
Pick Locator highlights the wrong element or several elements
Refine the locator in the Inspector until it selects the intended element. Prefer a meaningful role and accessible name, text, or test ID; avoid keeping a broad generated locator that can match multiple controls.
Free tools Windows power users keep installed
One-click scans. No signup required.
page.pause() is not reached
The test must execute the line containing the call. Run the relevant test in debug mode, check that execution reaches the setup and actions before the pause, and use Resume in the Inspector if it is paused earlier. A pause call placed in a branch that is not taken will not stop that run.
Or skip the browser setup
If your goal is to capture a website screenshot rather than step through a Playwright test, ScreenshotNeo offers a one-request screenshot API. For a PNG, JPEG, or WebP image, or a PDF, make a GET request with the page URL. The following cURL example saves a WebP screenshot; replace YOUR_API_KEY with your key and change the target URL as needed. See the ScreenshotNeo API documentation for request options.
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpScreenshotNeo accepts cookie and consent banners before capture and removes more than 60 known consent platforms, newsletter popups, and chat widgets; each step can be turned off. Bot checks or CAPTCHAs, blank pages, timeouts, failed loads, and cache hits are not billed, with the outcome reported in response headers. Its MCP server gives AI agents tools for screenshots, page information, and PDF capture. The Free plan includes 1,000 screenshots a month with no card required; paid plans start at $5 for 3,000 screenshots.
Sign up free for 1,000 screenshots a month, with no card required.
Frequently Asked Questions
Can I use the Playwright Inspector without Playwright Test?
The commands in this guide use Playwright Test. For a custom browser setup, the Codegen documentation describes launching a headed browser and calling page.pause() to open the Inspector.
Does Pick Locator automatically produce the best locator for a test?
No. Check that the locator selects the intended element and reflects a stable user-facing attribute or explicit test contract before keeping it.
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.
