Debugging Tests

Start with UI mode

UI mode is the first tool I open when a test fails. It shows a timeline of every action, a DOM snapshot at each step, network requests, and console output — all in one view. You can rewind to any point and see exactly what the page looked like.

npx playwright test --ui

# Або конкретний файл
npx playwright test tests/orders.spec.ts --ui

Run headed with --debug

--debug opens Playwright Inspector alongside a visible browser. The test pauses at the start and you step through it manually — action by action. Useful when you need to see exactly which element gets clicked or what state the page is in at a specific moment.

# Запустити з дебагером
npx playwright test tests/orders.spec.ts --debug

# Або конкретний тест
npx playwright test --debug -g "filter shows pending orders"

Breakpoints in the test

await page.pause() stops the test at that exact line and opens Playwright Inspector. Unlike --debug (which pauses at the start), pause() lets you run until a specific moment — skip the boring setup and stop right where the problem is.

test('filter orders', async ({ page }) => {
  await page.goto('/orders')
  await page.getByRole('combobox', { name: 'Статус' }).selectOption('pending')

  // Зупинити тут і подивитися що відбулося
  await page.pause()

  await expect(page.getByRole('row')).toHaveCount(5)
})

VS Code extension

With the Playwright VS Code extension, you can run and debug tests without leaving the editor. Click the triangle next to a test name to run it, or right-click for "Debug test" to step through with breakpoints. The extension also has a Pick locator button — click it, then click any element in the browser, and the best locator is copied to your clipboard.

Traces for CI failures

When a test fails on CI and you can't reproduce locally, traces are the answer. A trace is a zip file containing every action, DOM snapshot, screenshot, network call and console log from the test run. Enable it in the config and Playwright saves it automatically on failure.

Open a saved trace with npx playwright show-trace path/to/trace.zip — it opens the same Trace Viewer you know from UI mode, but for the CI run.

// playwright.config.ts
export default defineConfig({
  use: {
    // Зберігати trace тільки при першому retry (найефективніший варіант)
    trace: 'on-first-retry',

    // Або завжди (більший розмір артефактів)
    // trace: 'on',
  },
})

# Відкрити trace локально
npx playwright show-trace test-results/orders-filter/trace.zip

# Або завантажити на trace.playwright.dev (публічний перегляд)

Check console and network in tests

You can listen to console messages and network requests directly in a test. This helps when the UI looks correct but something in the background is going wrong — an error logged to console, a failed API call, or a redirect that shouldn't happen.

test('no JS errors on dashboard load', async ({ page }) => {
  const errors: string[] = []

  // Збираємо JS помилки
  page.on('console', msg => {
    if (msg.type() === 'error') {
      errors.push(msg.text())
    }
  })

  // Збираємо failed запити
  page.on('response', res => {
    if (!res.ok()) {
      errors.push(`${res.status()} ${res.url()}`)
    }
  })

  await page.goto('/dashboard')
  await expect(page.getByRole('main')).toBeVisible()

  expect(errors).toHaveLength(0)
})