Debugging Playwright Tests: Inspector, page.pause, UI Mode and VS Code

Every automation engineer spends time debugging. Playwright makes it fast with excellent error messages, the Inspector, UI mode and VS Code integration. In this lesson you will learn a step-by-step debugging workflow and the right tool for each kind of failure.

---

🐞 A Debugging Mindset

When a Playwright test fails, ask three questions in order:

1. What did the error say? Playwright errors include the locator, the expected and received values, and a call log of what it tried.
2. What did the page look like? Use screenshots, UI mode or the trace.
3. What happened step by step? Step through the test with the Inspector or a breakpoint.

Playwright gives you a tool for each question. This lesson covers all of them; the most powerful one, the Trace Viewer, has its own lesson.

---

📜 Step 1: Read the Error Message and Call Log

Error: expect(locator).toHaveText(expected) failed

Locator: locator('.title')
Expected string: "Product"
Received string: "Products"
Timeout: 5000ms

Call log:
  - Expect "toHaveText" with timeout 5000ms
  - waiting for locator('.title')
    9 × locator resolved to <span class="title" data-test="title">Products</span>
      - unexpected value "Products"

The call log shows that the element was found nine times and its text was always “Products”. The test, not the app, is wrong. For actions you will see entries such as “element is not visible” or “another element would receive the click”, which point straight at the cause.

---

🧭 Step 2: Playwright Inspector with –debug

Run a test in debug mode:

npx playwright test tests/login.spec.ts --debug           # debug a file
npx playwright test tests/login.spec.ts:12 --debug        # debug the test on line 12
npx playwright test -g "locked out user" --debug          # debug by title

A headed browser and the Playwright Inspector open, paused before the first action. In the Inspector you can:

Control	What it does
Step over	Run the next action only
Resume	Continue until the next page.pause() or the end
Pick locator	Click an element to see the best locator for it
Locator box	Edit a locator and see live which elements it highlights
Call log	Watch Playwright’s actionability checks for the current step

The element the next action targets is highlighted in the browser, so you immediately see whether the locator points at the right element.

---

⏸️ Step 3: Pause Exactly Where You Need with page.pause()

Add await page.pause() anywhere in a test and run it headed. Execution stops there with the Inspector open:

test('checkout total', async ({ page }) => {
  await page.goto('https://www.saucedemo.com/');
  await page.getByPlaceholder('Username').fill('standard_user');
  await page.getByPlaceholder('Password').fill('secret_sauce');
  await page.getByRole('button', { name: 'Login' }).click();

  await page.pause();   // inspect the products page here

  await page.locator('[data-test="add-to-cart-sauce-labs-backpack"]').click();
});

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

Remove page.pause() before committing; with forbidOnly-style discipline, a lint rule such as playwright/no-page-pause catches leftovers.

---

🖥️ Step 4: UI Mode for Day-to-Day Debugging

npx playwright test --ui

UI mode is the most comfortable way to develop and debug tests:

• Run any test, file or tag with one click; watch mode re-runs on save.
• A timeline of every action with before and after DOM snapshots you can inspect like DevTools.
• Network, console, errors and source tabs for the selected step.
• Pick locator directly on the snapshot.

Most “why did it click the wrong thing?” questions are answered by clicking the step in the timeline and looking at the highlighted element.

---

🧑‍💻 Step 5: Debug in VS Code with Breakpoints

With the Playwright Test for VSCode extension:

1. Click in the gutter next to a line to set a breakpoint.
2. Right-click the green ▶ next to the test and choose Debug Test.
3. Execution stops at the breakpoint; hover variables, use the Debug Console, step with F10.
4. Tick Show browser to watch the page; while paused, editing a locator in the code highlights the matching element in the browser.

This combines normal TypeScript debugging (variables, call stack) with live browser feedback.

---

🐢 Step 6: Slow Down and Watch

Sometimes you simply need to see what happens:

npx playwright test --headed --workers=1 --project=chromium

// playwright.config.ts: slow every action down by 500 ms (debugging only)
use: {
  launchOptions: { slowMo: 500 },
},

---

📢 Step 7: Capture Browser Console and Network Errors

Front-end JavaScript errors often explain UI failures. Print them during the test:

test.beforeEach(async ({ page }) => {
  page.on('console', msg => {
    if (msg.type() === 'error') console.log('Browser console error:', msg.text());
  });
  page.on('pageerror', err => console.log('Uncaught page error:', err.message));
  page.on('requestfailed', req => console.log('Request failed:', req.url(), req.failure()?.errorText));
});

For very detailed Playwright internals, enable debug logs:

# macOS / Linux
DEBUG=pw:api npx playwright test tests/login.spec.ts

# Windows PowerShell
$env:DEBUG='pw:api'; npx playwright test tests/login.spec.ts

---

🧰 Debugging Toolbox Summary

Tool	Best for	Command
Error + call log	First look at any failure	Always printed
Inspector	Stepping through actions, fixing locators	--debug
page.pause()	Stopping at one exact point	Add to code, run --headed
UI mode	Developing and exploring tests	--ui
VS Code debugger	Variables, logic, breakpoints	Debug Test
Trace Viewer	Failures in CI, after the fact	trace: 'on-first-retry'
Screenshots and video	Quick visual evidence	screenshot, video in config

---

🔎 Common Failures and Where to Look

Symptom	Likely cause	Debug with
“strict mode violation”	Locator matches several elements	Inspector locator box
“element is not visible”	Hidden, wrong tab, not yet rendered	UI mode snapshot
“intercepts pointer events”	Overlay, modal or cookie banner	UI mode snapshot, trace
Assertion timeout with wrong value	Test data or app logic	Error + call log
Passes locally, fails in CI	Timing, environment, data	Trace Viewer, flaky tests

---

📝 Assignment

1. Break a locator in one of your Sauce Demo tests on purpose, read the error and call log, and write down what they told you.
2. Run the test with --debug, step through it, and fix the locator using the Inspector’s locator box.
3. Add page.pause() after login, run headed, and use Pick locator on three elements.
4. Open UI mode, run your suite, and inspect the before and after snapshots of a click.
5. Set a breakpoint in VS Code inside a test, run Debug Test, and inspect a variable.
6. Add console and page-error listeners in a beforeEach and visit a page that logs errors.
7. Bonus: run one test with DEBUG=pw:api and find the line where Playwright waits for the element to be visible.

---

❓ FAQ

🤔 How do I debug a Playwright test?

Run it with npx playwright test --debug to open the Inspector, use --ui for UI mode, add await page.pause() to stop at a point, or use Debug Test in VS Code with breakpoints.

🤔 What does page.pause() do in Playwright?

It stops the test and opens the Playwright Inspector so you can explore the page, pick locators and continue step by step. It only works in headed mode.

🤔 How do I run Playwright in slow motion?

Set launchOptions: { slowMo: 500 } in the config (for local debugging only), or use --debug and step through actions.

🤔 How do I see browser console logs in Playwright?

Listen to the console event: page.on('console', msg => console.log(msg.text())), and to pageerror for uncaught exceptions.

🤔 What is the difference between UI mode and the Trace Viewer?

UI mode runs tests interactively on your machine with a live timeline. The Trace Viewer opens recorded traces after a run, which is ideal for failures that happened in CI.

---

🎯 Next Steps

• 🎭 Trace Viewer Step by Step
• 🎭 Reporters and the HTML Report
• 🎭 Retries and Fixing Flaky Tests
• 🎭 Playwright Tutorial with TypeScript