Developer Tools

Relevant source files

• docs/src/test-api/class-fullconfig.md
• docs/src/test-cli-js.md
• packages/html-reporter/src/testErrorView.css
• packages/html-reporter/src/testErrorView.tsx
• packages/injected/src/recorder/pollingRecorder.ts
• packages/injected/src/recorder/recorder.ts
• packages/playwright-core/src/server/codegen/languages.ts
• packages/playwright-core/src/server/debugController.ts
• packages/playwright-core/src/server/dispatchers/debugControllerDispatcher.ts
• packages/playwright-core/src/server/index.ts
• packages/playwright-core/src/server/recorder.ts
• packages/playwright-core/src/server/recorder/recorderApp.ts
• packages/playwright-core/src/server/trace/viewer/traceViewer.ts
• packages/playwright/src/common/config.ts
• packages/playwright/src/isomorphic/testServerConnection.ts
• packages/playwright/src/isomorphic/testServerInterface.ts
• packages/playwright/src/program.ts
• packages/playwright/src/runner/loadUtils.ts
• packages/playwright/src/runner/projectUtils.ts
• packages/playwright/src/runner/reporters.ts
• packages/playwright/src/runner/taskRunner.ts
• packages/playwright/src/runner/tasks.ts
• packages/playwright/src/runner/testRunner.ts
• packages/playwright/src/runner/testServer.ts
• packages/playwright/src/runner/vcs.ts
• packages/playwright/src/util.ts
• packages/recorder/src/actions.d.ts
• packages/recorder/src/recorder.css
• packages/recorder/src/recorder.tsx
• packages/recorder/src/recorderTypes.d.ts
• packages/trace-viewer/src/sw/main.ts
• packages/trace-viewer/src/ui/actionList.css
• packages/trace-viewer/src/ui/actionList.tsx
• packages/trace-viewer/src/ui/errorsTab.tsx
• packages/trace-viewer/src/ui/filmStrip.css
• packages/trace-viewer/src/ui/filmStrip.tsx
• packages/trace-viewer/src/ui/snapshotTab.css
• packages/trace-viewer/src/ui/snapshotTab.tsx
• packages/trace-viewer/src/ui/sourceTab.tsx
• packages/trace-viewer/src/ui/timeline.css
• packages/trace-viewer/src/ui/timeline.tsx
• packages/trace-viewer/src/ui/uiModeTraceView.tsx
• packages/trace-viewer/src/ui/uiModeView.tsx
• packages/trace-viewer/src/ui/workbench.tsx
• packages/trace-viewer/src/ui/workbenchLoader.css
• packages/trace-viewer/src/ui/workbenchLoader.tsx
• packages/trace-viewer/src/vite-env.d.ts
• packages/web/src/components/codeMirrorModule.tsx
• packages/web/src/components/codeMirrorWrapper.css
• packages/web/src/components/codeMirrorWrapper.tsx
• packages/web/src/components/listView.css
• packages/web/src/components/listView.tsx
• packages/web/src/components/sourceChooser.tsx
• packages/web/src/components/treeView.tsx
• tests/config/debugControllerBackend.ts
• tests/config/traceViewerFixtures.ts
• tests/library/debug-controller.spec.ts
• tests/library/inspector/cli-codegen-aria.spec.ts
• tests/library/inspector/cli-codegen-pick-locator.spec.ts
• tests/library/inspector/pause-helper.ts
• tests/library/inspector/pause.spec.ts
• tests/library/trace-viewer.spec.ts
• tests/playwright-test/only-changed.spec.ts
• tests/playwright-test/test-list.spec.ts
• tests/playwright-test/ui-mode-trace.spec.ts

Playwright provides a comprehensive suite of developer tools for debugging, analyzing, and interacting with tests during development and debugging. These tools enable developers to inspect test execution in real-time, analyze recorded traces, and debug failing tests efficiently.

This page covers the interactive debugging and analysis tools provided by Playwright. For information about test execution architecture, see Test Execution Architecture. For details about reporting test results, see Reporting System.

Overview

Playwright's developer tools consist of three main components:

1. Inspector/Recorder — An interactive debugging window attached to a BrowserContext. Activated via --debug, PWDEBUG=1, or page.pause(). Used for recording user interactions as test code, picking element locators, recording assertions, and stepping through test execution. See page 5.1 for details.
2. UI Mode — A browser-based interactive test runner launched via npx playwright test --ui. Provides test tree navigation, live trace preview, status filtering, project selection, and file-watch-triggered re-runs. See page 5.2 for details.
3. Trace Viewer — A standalone application for post-run analysis of recorded .zip trace archives, launched via npx playwright show-trace. Shows DOM snapshots, action timelines, network traffic, console output, and source context. See page 5.3 for details.

Developer Tools: Entry Points and Code Entities

Sources: packages/playwright-core/src/server/recorder.ts72-169 packages/playwright-core/src/server/recorder/recorderApp.ts48-131 packages/playwright/src/runner/testServer.ts45-63 packages/playwright-core/src/server/trace/viewer/traceViewer.ts81-119 packages/trace-viewer/src/ui/uiModeView.tsx77-553 packages/trace-viewer/src/ui/workbench.tsx65-404

UI Mode Architecture

UI Mode is an interactive web-based test runner that enables developers to run, debug, and watch tests through a browser interface. It is launched via the --ui command-line option.

UI Mode System Components

Sources: packages/playwright/src/program.ts219-236 packages/playwright/src/runner/testServer.ts273-291 packages/trace-viewer/src/ui/uiModeView.tsx77-553

Test Server Protocol

The test server exposes a typed interface for test operations through WebSocket communication:

Sources: packages/playwright/src/isomorphic/testServerInterface.ts25-138 packages/playwright/src/runner/testServer.ts90-271 packages/playwright/src/isomorphic/testServerConnection.ts88-282

Key protocol methods:

Method	Purpose	Parameters	Return
initialize()	Setup connection and options	interceptStdio, watchTestDirs	void
listTests()	Enumerate test cases	projects, locations, grep	report[], status
runTests()	Execute selected tests	testIds, locations, trace, workers	status
stopTests()	Interrupt test execution	none	void
watch()	Enable file watching	fileNames	void

Sources: packages/playwright/src/isomorphic/testServerInterface.ts25-121 packages/playwright/src/runner/testServer.ts127-233

UI Mode State Management

The UIModeView component manages the UI state and coordinates between the test list, filters, and trace viewer:

Sources: packages/trace-viewer/src/ui/uiModeView.tsx79-112 packages/trace-viewer/src/ui/uiModeView.tsx248-258

Watch Mode Implementation

UI Mode supports automatic test re-execution when files change:

Sources: packages/trace-viewer/src/ui/uiModeView.tsx316-378 packages/playwright/src/runner/testServer.ts214-216

Trace Viewer Architecture

The Trace Viewer is a standalone application for analyzing recorded test traces. It can be launched via npx playwright show-trace or accessed at https://trace.playwright.dev.

Trace Viewer Components

Sources: packages/playwright-core/src/server/trace/viewer/traceViewer.ts81-162 packages/trace-viewer/src/ui/workbenchLoader.tsx26-246 packages/trace-viewer/src/sw/main.ts54-262

Service Worker Architecture

The Trace Viewer uses a service worker to enable offline operation and efficient trace loading:

Sources: packages/trace-viewer/src/sw/main.ts61-262 packages/trace-viewer/src/sw/traceLoaderBackends.ts

Snapshot Rendering System

The Trace Viewer captures and renders DOM snapshots at various points during test execution:

Snapshot Type	When Captured	Purpose
beforeSnapshot	Before action execution	Shows initial state
inputSnapshot	During input actions	Shows target element
afterSnapshot	After action completes	Shows result state

Sources: packages/trace-viewer/src/ui/snapshotTab.tsx323-416

The snapshot rendering process:

Sources: packages/trace-viewer/src/ui/snapshotTab.tsx102-192 packages/playwright-core/src/server/trace/recorder/snapshotterInjected.ts34-570

The frameSnapshotStreamer function (injected into snapshot iframes) handles:

• Shadow DOM reconstruction via kShadowAttribute
• Form input value restoration via kValueAttribute, kCheckedAttribute, kSelectedAttribute
• Scroll position restoration via kScrollTopAttribute, kScrollLeftAttribute
• Adopted stylesheets via kStyleSheetAttribute
• Custom element registry via kCustomElementsAttribute

Sources: packages/playwright-core/src/server/trace/recorder/snapshotterInjected.ts40-53

Inspector and Recorder

The Playwright Inspector is an interactive window that attaches to an inspected BrowserContext. It provides code recording, element picking, locator generation, assertion recording, and step-through debugging.

Activation:

Method	Mechanism
npx playwright test --debug	Sets overrides.debug = true and PWDEBUG=1; pauses before first action
PWDEBUG=1 env variable	Detected at BrowserContext creation; opens Inspector automatically
page.pause()	Calls Debugger.pauseOnNextStatement(); blocks execution until resumed

Inspector Component Architecture

Sources: packages/playwright-core/src/server/recorder.ts72-235 packages/playwright-core/src/server/recorder/recorderApp.ts48-131 packages/playwright-core/src/server/debugController.ts1-50 packages/recorder/src/recorder.tsx37-101

Recorder Modes

The Recorder class tracks the current mode in this._mode. The injected pollingRecorderSource polls __pw_recorderState() each animation frame to keep the in-page overlay synchronized.

Mode	Description
'none'	Inactive, overlay hidden
'standby'	Overlay visible, not recording
'inspecting'	Element picker active
'recording'	Capturing user actions to generate code
'recording-inspecting'	Recording + element picker simultaneously
'assertingText'	Waiting for click to record a text assertion
'assertingVisibility'	Waiting for click to record a visibility assertion
'assertingValue'	Waiting for click to record a value assertion
'assertingSnapshot'	Waiting for click to record an ARIA snapshot assertion

Sources: packages/playwright-core/src/server/recorder.ts248-263 packages/recorder/src/recorder.tsx158-178

Key Classes

Class	File	Responsibility
Recorder	packages/playwright-core/src/server/recorder.ts	Attaches to BrowserContext as an InstrumentationListener; manages mode, processes in-page actions via bindings, fires RecorderEvent.* to listeners
RecorderApp	packages/playwright-core/src/server/recorder/recorderApp.ts	Launches the Inspector browser window; wires Recorder events to RecorderFrontend and handles RecorderBackend dispatcher commands
DebugController	packages/playwright-core/src/server/debugController.ts	Manages Recorder instances across multiple contexts; exposes setRecorderMode, resetForReuse, highlight; used by the VS Code extension
Recorder (React)	packages/recorder/src/recorder.tsx	Inspector UI: toolbar (Record, Pick locator, Assert *), code editor (CodeMirrorWrapper), call log (CallLogView), locator/ARIA-snapshot tabs

Sources: packages/playwright-core/src/server/recorder.ts72-113 packages/playwright-core/src/server/recorder/recorderApp.ts48-82 packages/playwright-core/src/server/debugController.ts1-50 packages/recorder/src/recorder.tsx37-50

For details on language-specific code generators, the RecorderSignalProcessor, and the injected script internals, see page 5.1.

Command-Line Interface

The Playwright CLI provides commands for launching developer tools:

Trace Viewer Commands

Sources: docs/src/test-cli-js.md262-292

The show-trace command is implemented by runTraceViewerApp() which:

1. Starts an HTTP server via startTraceViewerServer()
2. Installs root redirect via installRootRedirect()
3. Launches a browser via openTraceViewerApp()
4. Loads the trace viewer UI

Sources: packages/playwright-core/src/server/trace/viewer/traceViewer.ts154-162

UI Mode Commands

Sources: docs/src/test-cli-js.md60-64 packages/playwright/src/program.ts219-236

The --ui option triggers runUIMode() which:

1. Resolves config location
2. Starts test server via innerRunTestServer()
3. Opens browser with UI or serves on specified host/port
4. Installs root redirect to /trace/uiMode.html

Sources: packages/playwright/src/runner/testServer.ts273-291

Trace Recording

Traces are recorded during test execution via the tracing API on BrowserContext:

The trace recording system uses:

• Snapshotter - Captures DOM snapshots via frameSnapshotStreamer injected script
• Tracing - Records events, network activity, and console output
• TraceWriter - Serializes trace data to ZIP format

Sources: tests/library/trace-viewer.spec.ts40-93 packages/playwright-core/src/server/trace/recorder/snapshotter.ts

Trace File Format

Trace files are ZIP archives containing:

File	Content
trace.trace	Action events and metadata (JSON lines)
trace.network	Network request/response data
resources/	Screenshots, snapshots, network bodies
src/	Source code files (when sources: true)

Sources: packages/trace-viewer/src/sw/main.ts91-109

Integration with Test Runner

Developer tools integrate with the test runner through several mechanisms:

Automatic Trace Generation

When tests are run in UI Mode, tracing is automatically enabled:

Sources: packages/trace-viewer/src/ui/uiModeView.tsx293-303

Live Trace Viewing

UI Mode can display traces for running tests by polling the trace directory:

Sources: packages/trace-viewer/src/ui/uiModeTraceView.tsx44-91

Console and Error Interception

The test server intercepts stdio to display in UI Mode:

Sources: packages/playwright/src/runner/testServer.ts235-270

This allows UI Mode to display console output and errors in real-time while tests are executing.