How to Use the Playwright Inspector

To open Playwright Inspector while running Playwright Test, use:

npx playwright test --debug

This launches the browser in headed mode and opens the Inspector. To focus on a test file or a particular line, add it before --debug:

npx playwright test example.spec.ts --debug
npx playwright test example.spec.ts:10 --debug

Use the Inspector to play, pause, and step through an existing test, review actionability logs, and try locators against the live page. For a deliberate stop at a point in the test, add await page.pause() and run in debug mode. [Playwright: Running and debugging tests]

1. Open the Inspector for an existing test

Run commands from the project directory that contains your Playwright configuration and tests. Use npx to run the Playwright Test CLI installed in the project:

npx playwright test --debug

This starts tests with a visible browser and opens the Inspector. The documented debug defaults include a zero default timeout, so a test does not use the usual default timeout while you inspect it. This is useful while stepping manually, but it also means a test may keep waiting until you act or stop it. [Running and debugging tests]

For a smaller debugging session, specify a file:

npx playwright test tests/checkout.spec.ts --debug

To focus on the test associated with a source line, append a colon and line number to the file path:

npx playwright test tests/checkout.spec.ts:10 --debug

Replace the path and line number with the ones in your project. A focused run helps when the problem is in a particular test and you do not need to step through the rest of the suite.

2. Step through the test

The Inspector toolbar has controls to play, pause, and step. Start or resume execution, pause when you want to examine the current state, and advance through actions one at a time. As you step, the current action is highlighted in the test code and the corresponding page elements are highlighted in the browser. [Running and debugging tests]

1. Start with npx playwright test --debug, or select a test file or line as shown above.
2. Use the Inspector controls to pause at the point you want to inspect.
3. Compare the highlighted test action with the browser state.
4. Check the actionability log if an action is waiting or does not complete.
5. Resume or step again after you have identified the state or condition to investigate.

Inspector debug mode is for examining an existing test. If you want to record browser interactions to start a test, use Codegen instead; it has a separate workflow described below.

3. Stop at a chosen point with page.pause()

When the relevant page state occurs well into a test, add a pause at the point you want to reach. For example:

import { test, expect } from '@playwright/test';

test('checkout shows the delivery step', async ({ page }) => {
  await page.goto('https://example.com/checkout');
  await page.getByRole('button', { name: 'Continue' }).click();

  // The debug session will stop here.
  await page.pause();

  await expect(page.getByRole('heading', { name: 'Delivery' })).toBeVisible();
});

Run the test in debug mode:

npx playwright test tests/checkout.spec.ts --debug

When execution reaches page.pause(), the Inspector pauses. Use Resume to continue. This lets you examine the page at that specific point without manually stepping through all the preceding actions. Remove the pause after debugging if you do not want normal runs to stop there. [Running and debugging tests]

4. Diagnose a waiting action with actionability logs

When an action such as click() is pending, use the Inspector log to see what Playwright is checking. Depending on the action, the log can show whether the locator resolved and whether the target is visible, enabled, stable, or scrolled into view. If the necessary actionability conditions are not met, the action can remain pending. [Running and debugging tests]

Read the log as evidence about the state at that moment, then investigate the specific failed or pending check:

• The locator does not resolve as intended: inspect the live page and use Pick Locator to check which element your locator identifies.
• The target is not visible: check whether the intended page state has loaded and whether the locator points to the visible control.
• The target is disabled: inspect the page state and prerequisites for enabling that control.
• The target is not stable: inspect whether the page is still changing before the action.
• The target must be scrolled into view: use the log to understand whether scrolling is part of the action progress or whether the target is obscured or otherwise not ready.

Do not change a locator merely because a click waits. First determine which check is preventing the action, then decide whether the page state, test sequence, or locator needs attention.

5. Pick and refine a locator

In the Inspector, select Pick Locator, hover over an element in the browser, then click the intended element. The Inspector shows the locator under the pointer and places the selected locator in its field. Edit it there and watch which element is highlighted; copy the locator into the test when it identifies the intended control. [Running and debugging tests]

Prefer locators that describe the intended element in terms of how a user or your test contract identifies it. Playwright recommends user-facing attributes and explicit contracts such as role and accessible name, text, and test IDs. [Playwright: Locators]

// Role and accessible name
page.getByRole('button', { name: 'Continue' })

// Visible text
page.getByText('Order confirmed')

// Explicit test contract
page.getByTestId('checkout-submit')

Use the locator that best expresses the element’s purpose in your application. A generated or picked locator is a starting point: check that it selects the intended element and remains meaningful if the page changes. Codegen also prioritizes role, text, and test IDs and tries to make a locator unique when multiple elements match. [Playwright: Test generator]

Playwright resolves a locator against the current DOM when it is used for an action. This allows the locator to find the element again after a page re-render, rather than depending on an old element reference. [Locators]

6. Choose Inspector, Codegen, UI Mode, or VS Code

Workflow	Use it for	Starting point
Inspector debug mode	Stepping through an existing test, examining actionability, and live-editing locators	npx playwright test --debug, a file or line, or page.pause()
Codegen	Recording browser interactions to create a test and generate locators or assertions	npx playwright codegen <url>
UI Mode	A broader debugging experience with a locator picker and watch mode	Start the UI Mode workflow documented by Playwright
VS Code extension	Breakpoint and live-debugging workflows within the editor	Use the Playwright VS Code extension workflow

Codegen opens a browser and Inspector, records actions, and can generate visibility, text, or value assertions. When recording stops, use Pick Locator to select and copy locators. Codegen can also be opened from custom browser setup by launching headed and calling page.pause(). [Test generator]

Use Inspector when the question is “why is this existing test doing this or waiting here?” Use Codegen when the question is “how do I turn these browser interactions into a test?” UI Mode and the VS Code extension offer other debugging routes with overlapping but distinct workflows. [Playwright: Best Practices]

7. Troubleshooting

Symptom	Likely cause	What to do
The browser or Inspector does not open.	The command was not run through the project’s Playwright Test CLI, or the test selection did not match the intended test.	Run npx playwright test --debug from the project directory. Then try the explicit test file command and verify its path.
The wrong test runs or too much of the suite runs.	The file or line selection is missing or points elsewhere.	Use npx playwright test path/to/test.spec.ts:10 --debug with the actual test path and line.
The test appears stuck on an action.	A locator may not resolve to the intended target, or an actionability condition such as visibility, enabled state, stability, or scrolling is not met.	Read the actionability log and inspect the page. Use Pick Locator to confirm the target before changing the test.
The test waits indefinitely during debugging.	Debug mode documents a zero default timeout, so a wait may continue while you inspect it.	Use the Inspector to diagnose the wait, resume or stop the session as needed, and rerun the test without debug mode to observe its normal timeout behavior.
page.pause() is not reached.	Execution did not reach that line, or the run was not started in debug mode.	Start the correct test with --debug; step through earlier actions or inspect the preceding pending action.
A picked locator highlights multiple or unexpected elements.	The locator may not uniquely express the intended control.	Refine it in the Inspector, try a role and accessible name, text, or a test ID, and confirm the intended element is highlighted before copying it.

Commands and CLI behavior can vary by Playwright version. Check the documentation for the version used by your project when a command behaves differently. [Playwright: Command line]

8. Performance, reliability, and cost

The Inspector is a local debugging workflow for Playwright tests. Debug mode launches browsers headed and changes the documented default timeout to zero; use it to investigate a test interactively, then run the test normally to evaluate its regular behavior. [Running and debugging tests]

For reliable locator behavior, choose locators that express the intended control and verify them against the live page. Locators resolve against the current DOM when used, which supports re-rendered pages. The official guidance favors user-facing attributes and explicit test contracts; it does not provide a speed benchmark for Inspector use. [Locators]

Playwright Inspector itself is not a hosted screenshot API and the cited Playwright guides do not specify a price for it. If your separate task is to capture website screenshots through an API, ScreenshotNeo offers a one-request screenshot API and an MCP server for AI agents. Its plans include 1,000 free shots per month without a card, with paid plans starting at $5 for 3,000 shots. [ScreenshotNeo]

Or skip the browser setup

If you need a website screenshot rather than an interactive Playwright debugging session, ScreenshotNeo can return an image or PDF from one GET request. The API and options are documented at ScreenshotNeo docs.

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp

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)

const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);

• Cookie banners and consent prompts are handled before capture; ScreenshotNeo also removes known consent platforms, newsletter popups, and chat widgets. Each step can be turned off.
• Bot checks, blank pages, failed loads, timeouts, and cache hits cost nothing; response headers say the page verdict and whether the shot was billed.
• An MCP server gives AI agents tools for screenshots, page information, and PDF capture.
• 1,000 screenshots a month are free with no card. Paid plans start at $5 for 3,000 shots.

Create a free ScreenshotNeo account for 1,000 screenshots a month with no card.

FAQ

Does the Inspector record a new test?

No. Use Inspector debug mode to examine an existing test. Use npx playwright codegen <url> to record browser interactions and generate test code. [Test generator]

Can I open the Inspector at a particular point without stepping from the start?

Yes. Add await page.pause() where you want execution to stop, then run the test with --debug. [Running and debugging tests]

Should I keep a locator copied from Pick Locator exactly as generated?

Review it first. Confirm it identifies the intended element and expresses a useful user-facing attribute or explicit test contract. [Locators]