How do I debug a Playwright test step by step?

Run the test with --debug, for example npx playwright test cart.spec.js:8 --debug, which opens the browser and the Playwright Inspector paused before the first action. You then step over one action at a time, or add await page.pause() where you want the test to stop and press Resume to run up to it.

This answer is one piece of Chapter 12: Debugging a Red Test.

Debugging Tools in Playwright
Tracing & Trace Viewer
Which Tool, and When

Reading a failure message tells you which line failed. Stepping through the test shows you what the page looked like when it did.

--debug is a shortcut. The help text shows it sets PWDEBUG=1 and runs headed, with no timeout, one worker and a stop at the first failure. No timeout matters: you can sit on a step as long as you need without the test being killed.

The Inspector is a separate window beside the browser. According to the docs, it highlights the current action in your test code and the matching element in the browser, and lets you play, pause or step over actions one at a time. It also shows actionability logs, explaining what Playwright is waiting for, and has a Pick locator button that gives you a locator for any element you click.

To debug only one test, add its file and line, as in cart.spec.js:8 --debug. To start pausing later in a long test, put await page.pause() before the step you care about and press Resume. Remove it afterwards.

The Inspector is interactive, so it was not opened for this page. The output is the real help text for --debug from this project's install.

terminal

$ npx playwright test before-each.spec.js:11 --debug

# Help text for the flag:
$ npx playwright test --help

Output

  --debug [mode]                   Run tests with Playwright Inspector. Shortcut
                                   for "PWDEBUG=1" environment variable and
                                   "--timeout=0 --max-failures=1 --headed
                                   --workers=1" options (choices: "inspector",
                                   "cli", preset: "inspector")

Test yourself

You add await page.pause() halfway through a test and run it with --debug. In the Inspector you press Resume. What happens?

Practised in the full course: the drill Deprecated devtools launch option.

See the chapter

AI can write the test now. The job is knowing whether it checks anything. That's what the course teaches, one chapter at a time.

163 lessons · 226 drills · start free

How do I debug a Playwright test step by step?

Related questions