bradtaylorsf Playwright Debugging Skill
Techniques for debugging Playwright tests.
Debug Mode
Using --debug
# Run with inspector
npx playwright test --debug
# Debug specific test
npx playwright test tests/login.spec.ts --debug
# Debug specific line
npx playwright test tests/login.spec.ts:15 --debug
PWDEBUG Environment Variable
# Enable Playwright Inspector
PWDEBUG=1 npx playwright test
# Console debug mode
PWDEBUG=console npx playwright test
In-Code Debugging
test('debug this test', async ({ page }) => {
await page.goto('/')
// Pause and open inspector
await page.pause()
await page.click('button')
})
Playwright Inspector
Inspector Features
// Inspector opens automatically with --debug
// Features:
// - Step through actions
// - View selectors
// - Record new steps
// - Explore elements
// - View console logs
Recording Actions
# Start codegen to record tests
npx playwright codegen https://example.com
# With specific viewport
npx playwright codegen --viewport-size=800,600 https://example.com
# Save to file
npx playwright codegen -o tests/recorded.spec.ts https://example.com
Trace Viewer
Enabling Traces
// playwright.config.ts
export default defineConfig({
use: {
trace: 'on-first-retry', // Only on retry
// trace: 'on', // Always
// trace: 'retain-on-failure', // Keep on failure
},
})
// Or per test
test.use({ trace: 'on' })
// Or in beforeAll
test.beforeAll(async ({ browser }, testInfo) => {
testInfo.config.use.trace = 'on'
})
Viewing Traces
# Open trace viewer
npx playwright show-trace trace.zip
# View from test results
npx playwright show-report
# Click on test, then "Traces" tab
Trace Contents
Trace includes:
- Screenshots at each action
- DOM snapshots
- Network requests
- Console logs
- Test source
- Action timeline
Screenshots
Capture Screenshots
// Full page
await page.screenshot({ path: 'screenshot.png' })
// Full page including scrollable content
await page.screenshot({ path: 'full.png', fullPage: true })
// Element only
await page.locator('.card').screenshot({ path: 'card.png' })
// With options
await page.screenshot({
path: 'screenshot.png',
type: 'png', // 'png' or 'jpeg'
quality: 80, // For jpeg
clip: { x: 0, y: 0, width: 800, height: 600 },
})
Auto Screenshots on Failure
// playwright.config.ts
export default defineConfig({
use: {
screenshot: 'only-on-failure',
// screenshot: 'on', // Always
// screenshot: 'off', // Never
},
})
Videos
Enable Video Recording
// playwright.config.ts
export default defineConfig({
use: {
video: 'on-first-retry',
// video: 'on', // Always record
// video: 'retain-on-failure', // Keep on failure
},
})
// With options
export default defineConfig({
use: {
video: {
mode: 'on',
size: { width: 1280, height: 720 },
},
},
})
Access Video Path
test.afterEach(async ({}, testInfo) => {
if (testInfo.status === 'failed') {
const videoPath = testInfo.attachments.find(a => a.name === 'video')?.path
console.log('Video saved to:', videoPath)
}
})
Console Logs
Capture Browser Console
test('capture console', async ({ page }) => {
const logs: string[] = []
page.on('console', msg => {
logs.push(`${msg.type()}: ${msg.text()}`)
})
await page.goto('/')
// Check logs
expect(logs).not.toContain('error')
})
Log Page Errors
test.beforeEach(async ({ page }) => {
page.on('pageerror', error => {
console.error('Page error:', error.message)
})
page.on('console', msg => {
if (msg.type() === 'error') {
console.error('Console error:', msg.text())
}
})
})
Network Debugging
Capture Network
test('debug network', async ({ page }) => {
const requests: string[] = []
page.on('request', request => {
requests.push(`${request.method()} ${request.url()}`)
})
page.on('response', response => {
if (!response.ok()) {
console.log(`Failed: ${response.status()} ${response.url()}`)
}
})
await page.goto('/')
})
HAR Recording
// Record HAR file
const context = await browser.newContext({
recordHar: { path: 'network.har' },
})
const page = await context.newPage()
await page.goto('/')
await context.close() // HAR saved on close
// Replay HAR in tests
await page.routeFromHAR('network.har', {
update: false,
notFound: 'fallback',
})
Slow Motion
Slow Down Execution
// playwright.config.ts
export default defineConfig({
use: {
launchOptions: {
slowMo: 500, // 500ms between actions
},
},
})
// Or per test
test.use({
launchOptions: {
slowMo: 1000,
},
})
Headed Mode
Run with Browser Window
# Run headed
npx playwright test --headed
# Keep browser open on failure
npx playwright test --headed --timeout=0
// playwright.config.ts
export default defineConfig({
use: {
headless: false,
},
})
Test Isolation
Debug Test Isolation
// Run tests serially for debugging
test.describe.configure({ mode: 'serial' })
test('first', async ({ page }) => {
// ...
})
test('second depends on first', async ({ page }) => {
// ...
})
Preserve Context
// Keep context between tests
let context: BrowserContext
let page: Page
test.beforeAll(async ({ browser }) => {
context = await browser.newContext()
page = await context.newPage()
})
test.afterAll(async () => {
await context.close()
})
test('test 1', async () => {
await page.goto('/step1')
})
test('test 2', async () => {
// Continues from test 1
await page.goto('/step2')
})
Verbose Logging
Enable Verbose Output
# Debug all logs
DEBUG=pw:* npx playwright test
# Specific categories
DEBUG=pw:api npx playwright test
DEBUG=pw:browser npx playwright test
DEBUG=pw:protocol npx playwright test
Interactive Commands
In Test Commands
test('debug', async ({ page }) => {
await page.goto('/')
// Evaluate in page context
const title = await page.evaluate(() => document.title)
console.log('Title:', title)
// Get element properties
const button = page.getByRole('button')
console.log('Button text:', await button.textContent())
console.log('Button visible:', await button.isVisible())
console.log('Button enabled:', await button.isEnabled())
// Pause for manual inspection
await page.pause()
})
Integration
Used by:
frontend-developeragentfullstack-developeragent