1# Tracing
2 
3Capture detailed execution traces for debugging and analysis. Traces include DOM snapshots, screenshots, network activity, and console logs.
4 
5## Basic Usage
6 
7```bash
8# Start trace recording
9playwright-cli tracing-start
10 
11# Perform actions
12playwright-cli open https://example.com
13playwright-cli click e1
14playwright-cli fill e2 "test"
15 
16# Stop trace recording
17playwright-cli tracing-stop
18```
19 
20## Trace Output Files
21 
22When you start tracing, Playwright creates a `traces/` directory with several files:
23 
24### `trace-{timestamp}.trace`
25 
26**Action log** - The main trace file containing:
27- Every action performed (clicks, fills, navigations)
28- DOM snapshots before and after each action
29- Screenshots at each step
30- Timing information
31- Console messages
32- Source locations
33 
34### `trace-{timestamp}.network`
35 
36**Network log** - Complete network activity:
37- All HTTP requests and responses
38- Request headers and bodies
39- Response headers and bodies
40- Timing (DNS, connect, TLS, TTFB, download)
41- Resource sizes
42- Failed requests and errors
43 
44### `resources/`
45 
46**Resources directory** - Cached resources:
47- Images, fonts, stylesheets, scripts
48- Response bodies for replay
49- Assets needed to reconstruct page state
50 
51## What Traces Capture
52 
53| Category | Details |
54|----------|---------|
55| **Actions** | Clicks, fills, hovers, keyboard input, navigations |
56| **DOM** | Full DOM snapshot before/after each action |
57| **Screenshots** | Visual state at each step |
58| **Network** | All requests, responses, headers, bodies, timing |
59| **Console** | All console.log, warn, error messages |
60| **Timing** | Precise timing for each operation |
61 
62## Use Cases
63 
64### Debugging Failed Actions
65 
66```bash
67playwright-cli tracing-start
68playwright-cli open https://app.example.com
69 
70# This click fails - why?
71playwright-cli click e5
72 
73playwright-cli tracing-stop
74# Open trace to see DOM state when click was attempted
75```
76 
77### Analyzing Performance
78 
79```bash
80playwright-cli tracing-start
81playwright-cli open https://slow-site.com
82playwright-cli tracing-stop
83 
84# View network waterfall to identify slow resources
85```
86 
87### Capturing Evidence
88 
89```bash
90# Record a complete user flow for documentation
91playwright-cli tracing-start
92 
93playwright-cli open https://app.example.com/checkout
94playwright-cli fill e1 "4111111111111111"
95playwright-cli fill e2 "12/25"
96playwright-cli fill e3 "123"
97playwright-cli click e4
98 
99playwright-cli tracing-stop
100# Trace shows exact sequence of events
101```
102 
103## Trace vs Video vs Screenshot
104 
105| Feature | Trace | Video | Screenshot |
106|---------|-------|-------|------------|
107| **Format** | .trace file | .webm video | .png/.jpeg image |
108| **DOM inspection** | Yes | No | No |
109| **Network details** | Yes | No | No |
110| **Step-by-step replay** | Yes | Continuous | Single frame |
111| **File size** | Medium | Large | Small |
112| **Best for** | Debugging | Demos | Quick capture |
113 
114## Best Practices
115 
116### 1. Start Tracing Before the Problem
117 
118```bash
119# Trace the entire flow, not just the failing step
120playwright-cli tracing-start
121playwright-cli open https://example.com
122# ... all steps leading to the issue ...
123playwright-cli tracing-stop
124```
125 
126### 2. Clean Up Old Traces
127 
128Traces can consume significant disk space:
129 
130```bash
131# Remove traces older than 7 days
132find .playwright-cli/traces -mtime +7 -delete
133```
134 
135## Limitations
136 
137- Traces add overhead to automation
138- Large traces can consume significant disk space
139- Some dynamic content may not replay perfectly
140