Skip to content

Commit 730d322

Browse files
yury-syury-s
authored
cherry-pick(#17907): docs: improve trace viewer + add video (#18000)
1 parent 384b710 commit 730d322

File tree

1 file changed

+128
-59
lines changed

1 file changed

+128
-59
lines changed

‎docs/src/trace-viewer.md

Lines changed: 128 additions & 59 deletions
Original file line numberDiff line numberDiff line change
@@ -3,15 +3,133 @@ id: trace-viewer
33
title: "Trace Viewer"
44
---
55

6-
Playwright Trace Viewer is a GUI tool that helps exploring recorded Playwright traces after the script ran. Open traces [locally](#viewing-the-trace) or in your browser on [`trace.playwright.dev`](https://trace.playwright.dev).
76

8-
<img width="1212" alt="Playwright Trace Viewer" src="https://user-images.githubusercontent.com/883973/120585896-6a1bca80-c3e7-11eb-951a-bd84002480f5.png"></img>
7+
Playwright Trace Viewer is a GUI tool that helps you explore recorded Playwright traces after the script has ran. You can open traces [locally](#viewing-the-trace) or in your browser on [`trace.playwright.dev`](https://trace.playwright.dev).
98

109

11-
## Recording a trace
10+
<video width="100%" height="100%" controls muted>
11+
<source src="https://user-images.githubusercontent.com/13063165/194582806-a26efd72-746e-40cc-8955-fa65aa3274c3.mp4
12+
" type="video/mp4" />
13+
Your browser does not support the video tag.
14+
</video>
15+
16+
17+
## Viewing the trace
18+
19+
You can open the saved trace using Playwright CLI or in your browser on [`trace.playwright.dev`](https://trace.playwright.dev).
20+
21+
```bash js
22+
npx playwright show-trace trace.zip
23+
```
24+
25+
```bash java
26+
mvn exec:java -e -Dexec.mainClass=com.microsoft.playwright.CLI -Dexec.args="show-trace trace.zip"
27+
```
28+
29+
```bash python
30+
playwright show-trace trace.zip
31+
```
32+
33+
```bash csharp
34+
pwsh bin/Debug/netX/playwright.ps1 show-trace trace.zip
35+
```
36+
37+
## Actions
38+
39+
Once trace is opened, you will see the list of actions Playwright performed on the left hand side:
40+
41+
<img width="300" alt="Trace Viewer Actions Tab" src="https://user-images.githubusercontent.com/13063165/189152329-23e965de-581e-4a20-aed7-12cbf0583c92.png" />
42+
43+
<br/><br/>
44+
45+
**Selecting each action reveals:**
46+
- action snapshots,
47+
- action log,
48+
- source code location,
49+
- network log for this action
50+
51+
In the properties pane you will also see rendered DOM snapshots associated with each action.
52+
53+
## Metadata
54+
55+
See metadata such as the time the action was performed, what browser engine was used, what the viewport was and if it was mobile and how many pages, actions and events were recorded.
56+
57+
<img width="296" alt="Trace Viewer Metadata Tab" src="https://user-images.githubusercontent.com/13063165/189155450-3865a993-cb45-439c-a02f-1ddfe60a1719.png" />
58+
59+
## Screenshots
60+
61+
When tracing with the [`option: screenshots`] option turned on, each trace records a screencast and renders it as a film strip:
62+
63+
<img width="1078" alt="Playwright Trace viewer > Film strip" src="https://user-images.githubusercontent.com/13063165/189174647-3e647d3d-6500-4be2-a237-9191f418eb12.png" />
64+
65+
<br/><br/>
66+
67+
You can hover over the film strip to see a magnified image of for each action and state which helps you easily find the action you want to inspect.
68+
69+
<img width="819" alt="Playwright Trace viewer magnify" src="https://user-images.githubusercontent.com/13063165/189174658-ba218339-2abc-4336-812e-526dbc4d2907.png" />
70+
71+
72+
## Snapshots
73+
74+
When tracing with the [`option: snapshots`] option turned on, Playwright captures a set of complete DOM snapshots for each action. Depending on the type of the action, it will capture:
75+
76+
| Type | Description |
77+
|------|-------------|
78+
|Before|A snapshot at the time action is called.|
79+
|Action|A snapshot at the moment of the performed input. This type of snapshot is especially useful when exploring where exactly Playwright clicked.|
80+
|After|A snapshot after the action.|
81+
82+
<br/>
83+
84+
Here is what the typical Action snapshot looks like:
85+
86+
<img width="634" alt="Playwright Trace Viewer > Snapshots" src="https://user-images.githubusercontent.com/13063165/189153245-0bdcad4d-16a3-4a71-90d8-71a8038c0720.png" />
87+
88+
Notice how it highlights both, the DOM Node as well as the exact click position.
89+
90+
## Call
91+
92+
See what action was called, the time and duration as well as parameters, return value and log.
93+
94+
<img width="321" alt="Trace Viewer Call Tab" src="https://user-images.githubusercontent.com/13063165/189155306-3c9275bc-d4cd-4e91-8b63-225832a66f51.png" />
95+
96+
## Console
97+
98+
See the console output for the action where you can see console logs or errors.
99+
100+
<img width="299" alt="Trace Viewer Console Tab" src="https://user-images.githubusercontent.com/13063165/189173154-41d438dd-9334-4664-8c77-ee85f5040061.png" />
101+
102+
103+
## Network
104+
105+
See any network requests that were made during the action.
106+
107+
<img width="321" alt="Trace Viewer Network Tab" src="https://user-images.githubusercontent.com/13063165/189155367-e19f1c89-4e62-4258-970d-6a740e891711.png" />
108+
109+
## Source
110+
111+
See the source code for your entire test.
112+
113+
<img width="476" alt="Trace Viewer Source Tab" src="https://user-images.githubusercontent.com/13063165/189155239-c0f6045c-ab67-404a-8140-e98f78c58ae1.png" />
114+
115+
116+
## Recording a trace locally
12117
* langs: js
13118

14-
Set the `trace: 'on-first-retry'` option in the test configuration file. This will produce `trace.zip` file for each test that was retried.
119+
To record a trace during development mode set the `--trace` flag to `on` when running your tests.
120+
121+
```bash
122+
npx playwright test --trace on
123+
```
124+
125+
You can then open the HTML report and click on the trace icon to open the trace.
126+
```bash
127+
npx playwright show-report
128+
```
129+
## Recording a trace on CI
130+
131+
Traces should be run on continuous integration on the first retry of a failed test
132+
by setting the `trace: 'on-first-retry'` option in the test configuration file. This will produce a `trace.zip` file for each test that was retried.
15133

16134
```js tab=js-js
17135
// @ts-check
@@ -61,7 +179,7 @@ Available options to record a trace:
61179

62180
You can also use `trace: 'retain-on-failure'` if you do not enable retries but still want traces for failed tests.
63181

64-
If you are not using Playwright Test, use the [`property: BrowserContext.tracing`] API instead.
182+
If you are not using Playwright as a Test Runner, use the [`property: BrowserContext.tracing`] API instead.
65183

66184
## Recording a trace
67185
* langs: java, csharp, python
@@ -156,56 +274,16 @@ playwright show-trace trace.zip
156274
pwsh bin/Debug/netX/playwright.ps1 show-trace trace.zip
157275
```
158276

159-
## Actions
160-
161-
Once trace is opened, you will see the list of actions Playwright performed on the left hand side:
162-
163-
<img width="301" alt="Actions" src="https://user-images.githubusercontent.com/883973/120588303-d39dd800-c3eb-11eb-9e8b-bfea8b775354.png"></img>
164-
165-
Selecting each action reveals:
166-
- action snapshots,
167-
- action log,
168-
- source code location,
169-
- network log for this action
170-
171-
in the properties pane. You will also see rendered DOM snapshots associated with each action.
172-
173-
## Screenshots
174-
175-
When tracing with the [`option: screenshots`] option turned on, each trace records screencast and renders it as a film strip:
176-
177-
<img width="353" alt="Film strip" src="https://user-images.githubusercontent.com/883973/120588069-5d997100-c3eb-11eb-97a3-acbd5e0eb358.png"></img>
178-
179-
You can hover over the film strip to see a magnified image:
180-
181-
<img width="617" alt="Magnify" src="https://user-images.githubusercontent.com/883973/120588147-8f123c80-c3eb-11eb-864b-19d800619234.png"></img>
182-
183-
That helps locating the action of interest very quickly.
184-
185-
## Snapshots
186-
187-
When tracing with the [`option: snapshots`] option turned on, Playwright captures a set of complete DOM snapshots for each action. Depending on the type of the action, it will capture:
188-
189-
| Type | Description |
190-
|------|-------------|
191-
|Before|A snapshot at the time action is called.|
192-
|Action|A snapshot at the moment of the performed input. This type of snapshot is especially useful when exploring where exactly Playwright clicked.|
193-
|After|A snapshot after the action.|
194-
195-
<br/>
196-
197-
Here is what the typical Action snapshot looks like:
277+
## Using [trace.playwright.dev](https://trace.playwright.dev)
198278

199-
<img width="682" alt="Snapshots" src="https://user-images.githubusercontent.com/883973/120588728-879f6300-c3ec-11eb-85d6-e67b0e92e4e3.png">
200-
</img>
279+
[trace.playwright.dev](https://trace.playwright.dev) is a statically hosted variant of the Trace Viewer. You can upload trace files using drag and drop.
201280

202-
Notice how it highlights both, the DOM Node as well as the exact click position.
203281

282+
<img width="1119" alt="Drop Playwright Trace to load" src="https://user-images.githubusercontent.com/13063165/194577918-b4d45726-2692-4093-8a28-9e73552617ef.png" />
204283

205-
## Viewing remote Traces
284+
## Viewing remote traces
206285

207-
You can open remote traces using it's URL.
208-
They could be generated in a CI run and makes it easy to view the remote trace without having to manually download the file.
286+
You can open remote traces using it's URL. They could be generated on a CI run which makes it easy to view the remote trace without having to manually download the file.
209287

210288
```bash js
211289
npx playwright show-trace https://example.com/trace.zip
@@ -223,15 +301,6 @@ playwright show-trace https://example.com/trace.zip
223301
pwsh bin/Debug/netX/playwright.ps1 show-trace https://example.com/trace.zip
224302
```
225303

226-
## Using [trace.playwright.dev](https://trace.playwright.dev)
227-
228-
[trace.playwright.dev](https://trace.playwright.dev) is a statically hosted variant of the Trace Viewer.
229-
230-
### Viewing local traces
231-
232-
When navigating to [trace.playwright.dev](https://trace.playwright.dev), you can upload trace files using drag and drop.
233-
234-
### Remote traces
235304

236305
You can also pass the URL of your uploaded trace (e.g. inside your CI) from some accessible storage as a parameter. CORS (Cross-Origin Resource Sharing) rules might apply.
237306

0 commit comments

Comments
 (0)