diff --git a/docs/src/trace-viewer.md b/docs/src/trace-viewer.md
index 4afe692df7e2b..c1cae4f537078 100644
--- a/docs/src/trace-viewer.md
+++ b/docs/src/trace-viewer.md
@@ -3,15 +3,133 @@ id: trace-viewer
title: "Trace Viewer"
---
-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).
-
+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).
-## Recording a trace
+
+
+
+## Viewing the trace
+
+You can open the saved trace using Playwright CLI or in your browser on [`trace.playwright.dev`](https://trace.playwright.dev).
+
+```bash js
+npx playwright show-trace trace.zip
+```
+
+```bash java
+mvn exec:java -e -Dexec.mainClass=com.microsoft.playwright.CLI -Dexec.args="show-trace trace.zip"
+```
+
+```bash python
+playwright show-trace trace.zip
+```
+
+```bash csharp
+pwsh bin/Debug/netX/playwright.ps1 show-trace trace.zip
+```
+
+## Actions
+
+Once trace is opened, you will see the list of actions Playwright performed on the left hand side:
+
+
+
+
+
+**Selecting each action reveals:**
+- action snapshots,
+- action log,
+- source code location,
+- network log for this action
+
+In the properties pane you will also see rendered DOM snapshots associated with each action.
+
+## Metadata
+
+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.
+
+
+
+## Screenshots
+
+When tracing with the [`option: screenshots`] option turned on, each trace records a screencast and renders it as a film strip:
+
+
+
+
+
+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.
+
+
+
+
+## Snapshots
+
+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:
+
+| Type | Description |
+|------|-------------|
+|Before|A snapshot at the time action is called.|
+|Action|A snapshot at the moment of the performed input. This type of snapshot is especially useful when exploring where exactly Playwright clicked.|
+|After|A snapshot after the action.|
+
+
+
+Here is what the typical Action snapshot looks like:
+
+
+
+Notice how it highlights both, the DOM Node as well as the exact click position.
+
+## Call
+
+See what action was called, the time and duration as well as parameters, return value and log.
+
+
+
+## Console
+
+See the console output for the action where you can see console logs or errors.
+
+
+
+
+## Network
+
+See any network requests that were made during the action.
+
+
+
+## Source
+
+See the source code for your entire test.
+
+
+
+
+## Recording a trace locally
* langs: js
-Set the `trace: 'on-first-retry'` option in the test configuration file. This will produce `trace.zip` file for each test that was retried.
+To record a trace during development mode set the `--trace` flag to `on` when running your tests.
+
+```bash
+npx playwright test --trace on
+```
+
+You can then open the HTML report and click on the trace icon to open the trace.
+```bash
+npx playwright show-report
+```
+## Recording a trace on CI
+
+Traces should be run on continuous integration on the first retry of a failed test
+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.
```js tab=js-js
// @ts-check
@@ -61,7 +179,7 @@ Available options to record a trace:
You can also use `trace: 'retain-on-failure'` if you do not enable retries but still want traces for failed tests.
-If you are not using Playwright Test, use the [`property: BrowserContext.tracing`] API instead.
+If you are not using Playwright as a Test Runner, use the [`property: BrowserContext.tracing`] API instead.
## Recording a trace
* langs: java, csharp, python
@@ -156,56 +274,16 @@ playwright show-trace trace.zip
pwsh bin/Debug/netX/playwright.ps1 show-trace trace.zip
```
-## Actions
-
-Once trace is opened, you will see the list of actions Playwright performed on the left hand side:
-
-
-
-Selecting each action reveals:
-- action snapshots,
-- action log,
-- source code location,
-- network log for this action
-
-in the properties pane. You will also see rendered DOM snapshots associated with each action.
-
-## Screenshots
-
-When tracing with the [`option: screenshots`] option turned on, each trace records screencast and renders it as a film strip:
-
-
-
-You can hover over the film strip to see a magnified image:
-
-
-
-That helps locating the action of interest very quickly.
-
-## Snapshots
-
-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:
-
-| Type | Description |
-|------|-------------|
-|Before|A snapshot at the time action is called.|
-|Action|A snapshot at the moment of the performed input. This type of snapshot is especially useful when exploring where exactly Playwright clicked.|
-|After|A snapshot after the action.|
-
-
-
-Here is what the typical Action snapshot looks like:
+## Using [trace.playwright.dev](https://trace.playwright.dev)
-
-
+[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.
-Notice how it highlights both, the DOM Node as well as the exact click position.
+
-## Viewing remote Traces
+## Viewing remote traces
-You can open remote traces using it's URL.
-They could be generated in a CI run and makes it easy to view the remote trace without having to manually download the file.
+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.
```bash js
npx playwright show-trace https://example.com/trace.zip
@@ -223,15 +301,6 @@ playwright show-trace https://example.com/trace.zip
pwsh bin/Debug/netX/playwright.ps1 show-trace https://example.com/trace.zip
```
-## Using [trace.playwright.dev](https://trace.playwright.dev)
-
-[trace.playwright.dev](https://trace.playwright.dev) is a statically hosted variant of the Trace Viewer.
-
-### Viewing local traces
-
-When navigating to [trace.playwright.dev](https://trace.playwright.dev), you can upload trace files using drag and drop.
-
-### Remote traces
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.
+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).
-## Recording a trace
+
+
+
+## Viewing the trace
+
+You can open the saved trace using Playwright CLI or in your browser on [`trace.playwright.dev`](https://trace.playwright.dev).
+
+```bash js
+npx playwright show-trace trace.zip
+```
+
+```bash java
+mvn exec:java -e -Dexec.mainClass=com.microsoft.playwright.CLI -Dexec.args="show-trace trace.zip"
+```
+
+```bash python
+playwright show-trace trace.zip
+```
+
+```bash csharp
+pwsh bin/Debug/netX/playwright.ps1 show-trace trace.zip
+```
+
+## Actions
+
+Once trace is opened, you will see the list of actions Playwright performed on the left hand side:
+
+
+
+
+
+## Screenshots
+
+When tracing with the [`option: screenshots`] option turned on, each trace records a screencast and renders it as a film strip:
+
+
+
+
+
+
+## Snapshots
+
+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:
+
+| Type | Description |
+|------|-------------|
+|Before|A snapshot at the time action is called.|
+|Action|A snapshot at the moment of the performed input. This type of snapshot is especially useful when exploring where exactly Playwright clicked.|
+|After|A snapshot after the action.|
+
+
+
+Notice how it highlights both, the DOM Node as well as the exact click position.
+
+## Call
+
+See what action was called, the time and duration as well as parameters, return value and log.
+
+
+
+## Console
+
+See the console output for the action where you can see console logs or errors.
+
+
+
+
+## Network
+
+See any network requests that were made during the action.
+
+
+
+## Source
+
+See the source code for your entire test.
+
+
+
+
+## Recording a trace locally
* langs: js
-Set the `trace: 'on-first-retry'` option in the test configuration file. This will produce `trace.zip` file for each test that was retried.
+To record a trace during development mode set the `--trace` flag to `on` when running your tests.
+
+```bash
+npx playwright test --trace on
+```
+
+You can then open the HTML report and click on the trace icon to open the trace.
+```bash
+npx playwright show-report
+```
+## Recording a trace on CI
+
+Traces should be run on continuous integration on the first retry of a failed test
+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.
```js tab=js-js
// @ts-check
@@ -61,7 +179,7 @@ Available options to record a trace:
You can also use `trace: 'retain-on-failure'` if you do not enable retries but still want traces for failed tests.
-If you are not using Playwright Test, use the [`property: BrowserContext.tracing`] API instead.
+If you are not using Playwright as a Test Runner, use the [`property: BrowserContext.tracing`] API instead.
## Recording a trace
* langs: java, csharp, python
@@ -156,56 +274,16 @@ playwright show-trace trace.zip
pwsh bin/Debug/netX/playwright.ps1 show-trace trace.zip
```
-## Actions
-
-Once trace is opened, you will see the list of actions Playwright performed on the left hand side:
-
-
-
-Selecting each action reveals:
-- action snapshots,
-- action log,
-- source code location,
-- network log for this action
-
-in the properties pane. You will also see rendered DOM snapshots associated with each action.
-
-## Screenshots
-
-When tracing with the [`option: screenshots`] option turned on, each trace records screencast and renders it as a film strip:
-
-
-
-You can hover over the film strip to see a magnified image:
-
-
-
-That helps locating the action of interest very quickly.
-
-## Snapshots
-
-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:
-
-| Type | Description |
-|------|-------------|
-|Before|A snapshot at the time action is called.|
-|Action|A snapshot at the moment of the performed input. This type of snapshot is especially useful when exploring where exactly Playwright clicked.|
-|After|A snapshot after the action.|
-
-
-
+[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.
-Notice how it highlights both, the DOM Node as well as the exact click position.
+
-## Viewing remote Traces
+## Viewing remote traces
-You can open remote traces using it's URL.
-They could be generated in a CI run and makes it easy to view the remote trace without having to manually download the file.
+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.
```bash js
npx playwright show-trace https://example.com/trace.zip
@@ -223,15 +301,6 @@ playwright show-trace https://example.com/trace.zip
pwsh bin/Debug/netX/playwright.ps1 show-trace https://example.com/trace.zip
```
-## Using [trace.playwright.dev](https://trace.playwright.dev)
-
-[trace.playwright.dev](https://trace.playwright.dev) is a statically hosted variant of the Trace Viewer.
-
-### Viewing local traces
-
-When navigating to [trace.playwright.dev](https://trace.playwright.dev), you can upload trace files using drag and drop.
-
-### Remote traces
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.