doc(tracing): add a trace viewer doc (#6864)

docs/src/api/class-browsercontext.md

@@ -145,7 +145,6 @@ cases).
 :::
 
 ## event: BrowserContext.request
-* langs: js, python, java
 - argument: <[Request]>
 
 Emitted when a request is issued from any pages created through this context.
@@ -156,7 +155,6 @@ In order to intercept and mutate requests, see [`method: BrowserContext.route`]
 or [`method: Page.route`].
 
 ## event: BrowserContext.requestFailed
-* langs: js, python, java
 - argument: <[Request]>
 
 Emitted when a request fails, for example by timing out. To only listen for
@@ -168,7 +166,6 @@ with [`event: BrowserContext.requestFinished`] event and not with [`event: Brows
 :::
 
 ## event: BrowserContext.requestFinished
-* langs: js, python, java
 - argument: <[Request]>
 
 Emitted when a request finishes successfully after downloading the response body. For a successful response, the
@@ -176,7 +173,6 @@ sequence of events is `request`, `response` and `requestfinished`. To listen for
 successful requests from a particular page, use [`event: Page.requestFinished`].
 
 ## event: BrowserContext.response
-* langs: js, python, java
 - argument: <[Response]>
 
 Emitted when [response] status and headers are received for a request. For a successful response, the sequence of events
@@ -1164,7 +1160,6 @@ current working directory. If no path is provided, storage
 state is still returned, but won't be saved to the disk.
 
 ## property: BrowserContext.tracing
-* langs: js, python, java
 - type: <[Tracing]>
 
 ## async method: BrowserContext.unroute

docs/src/api/class-download.md

@@ -78,7 +78,6 @@ Deletes the downloaded file. Will wait for the download to finish if necessary.
 Returns download error if any. Will wait for the download to finish if necessary.
 
 ## method: Download.page
-* langs: js, python, java
 - returns: <[Page]>
 
 Get the page that the download belongs to.

docs/src/api/class-page.md

@@ -993,6 +993,12 @@ Emulates `'prefers-colors-scheme'` media feature, supported values are `'light'`
 
 Emulates `'prefers-reduced-motion'` media feature, supported values are `'reduce'`, `'no-preference'`. Passing `null` disables reduced motion emulation.
 
+### option: Page.emulateMedia.reducedMotion
+* langs: csharp
+- `reducedMotion` <[ReducedMotion]<"reduce"|"no-preference"|"null">>
+
+Emulates `'prefers-reduced-motion'` media feature, supported values are `'reduce'`, `'no-preference'`. Passing `null` disables reduced motion emulation.
+
 ## async method: Page.evalOnSelector
 * langs:
   - alias-python: eval_on_selector

docs/src/api/class-tracing.md

@@ -1,5 +1,4 @@
 # class: Tracing
-* langs: js, python, java
 
 API for collecting and saving Playwright traces. Playwright traces can be opened using the Playwright CLI after
 Playwright script runs.
@@ -18,7 +17,7 @@ await context.tracing.stop({ path: 'trace.zip' });
 ```java
 Browser browser = chromium.launch();
 BrowserContext context = browser.newContext();
-context.tracing.start(page, new Tracing.StartOptions()
+context.tracing.start(new Tracing.StartOptions()
   .setScreenshots(true)
   .setSnapshots(true);
 Page page = context.newPage();
@@ -43,6 +42,22 @@ page.goto("https://playwright.dev")
 context.tracing.stop(path = "trace.zip")
 ```
 
+```csharp
+await using var browser = playwright.Chromium.LaunchAsync();
+await using var context = await browser.NewContextAsync();
+await context.Tracing.StartAsync(new TracingStartOptions
+{
+  Screenshots: true,
+  Snapshots: true
+});
+var page = context.NewPageAsync();
+await page.GotoAsync("https://playwright.dev");
+await context.Tracing.StopAsync(new TracingStopOptions
+{
+  Path: "trace.zip"
+});
+```
+
 ## async method: Tracing.start
 
 Start tracing.
@@ -55,7 +70,7 @@ await context.tracing.stop({ path: 'trace.zip' });
 ```
 
 ```java
-context.tracing.start(page, new Tracing.StartOptions()
+context.tracing.start(new Tracing.StartOptions()
   .setScreenshots(true)
   .setSnapshots(true);
 Page page = context.newPage();
@@ -78,6 +93,22 @@ context.tracing.stop()
 context.tracing.stop(path = "trace.zip")
 ```
 
+```csharp
+await using var browser = playwright.Chromium.LaunchAsync();
+await using var context = await browser.NewContextAsync();
+await context.Tracing.StartAsync(new TracingStartOptions
+{
+  Screenshots: true,
+  Snapshots: true
+});
+var page = context.NewPageAsync();
+await page.GotoAsync("https://playwright.dev");
+await context.Tracing.StopAsync(new TracingStopOptions
+{
+  Path: "trace.zip"
+});
+```
+
 ### option: Tracing.start.name
 - `name` <[string]>
 

docs/src/api/params.md

@@ -367,7 +367,6 @@ Emulates `'prefers-colors-scheme'` media feature, supported values are `'light'`
 [`method: Page.emulateMedia`] for more details. Defaults to `'light'`.
 
 ## context-option-reducedMotion
-* langs: js, python, java
 - `reducedMotion` <[ReducedMotion]<"reduce"|"no-preference">>
 
 Emulates `'prefers-reduced-motion'` media feature, supported values are `'reduce'`, `'no-preference'`. See [`method: Page.emulateMedia`] for more details. Defaults
@@ -676,7 +675,6 @@ Maximum time in milliseconds to wait for the browser instance to start. Defaults
 disable timeout.
 
 ## browser-option-tracesdir
-* langs: js, python, java
 - `tracesDir` <[path]>
 
 If specified, traces are saved into this directory.

docs/src/cli.md

@@ -3,7 +3,7 @@ id: cli
 title: "Command Line Interface"
 ---
 
-Playwright comes with the command line tools that run via `npx` or as a part of the `npm` scripts.
+Playwright comes with the command line tools.
 
 <!-- TOC -->
 
@@ -21,6 +21,13 @@ mvn exec:java -e -Dexec.mainClass=com.microsoft.playwright.CLI
 playwright
 ```
 
+```bash csharp
+# Install the CLI once.
+dotnet add package Microsoft.Playwright.CLI
+# Use the tools.
+playwright
+```
+
 ```json js
 # Running from `package.json` script
 {
@@ -44,6 +51,10 @@ mvn exec:java -e -Dexec.mainClass=com.microsoft.playwright.CLI -Dexec.args="code
 playwright codegen wikipedia.org
 ```
 
+```bash csharp
+playwright codegen wikipedia.org
+```
+
 Run `codegen` and perform actions in the browser. Playwright CLI will generate JavaScript code for the user interactions. `codegen` will attempt to generate resilient text-based selectors.
 
 <img src="https://user-images.githubusercontent.com/284612/92536033-7e7ebe00-f1ed-11ea-9e1a-7cbd912e3391.gif"></img>
@@ -70,6 +81,12 @@ playwright codegen --save-storage=auth.json
 # auth.json will contain the storage state.
 ```
 
+```bash csharp
+playwright codegen --save-storage=auth.json
+# Perform authentication and exit.
+# auth.json will contain the storage state.
+```
+
 Run with `--load-storage` to consume previously loaded storage. This way, all [cookies](https://developer.mozilla.org/en-US/docs/Web/HTTP/Cookies) and [localStorage](https://developer.mozilla.org/en-US/docs/Web/API/Window/localStorage) will be restored, bringing most web apps to the authenticated state.
 
 ```bash js
@@ -91,6 +108,12 @@ playwright codegen --load-storage=auth.json my.web.app
 # Perform actions in authenticated state.
 ```
 
+```bash csharp
+playwright open --load-storage=auth.json my.web.app
+playwright codegen --load-storage=auth.json my.web.app
+# Perform actions in authenticated state.
+```
+
 ### Codegen with custom setup
 
 If you would like to use codegen in some non-standard setup (for example, use [`method: BrowserContext.route`]), it is possible to call [`method: Page.pause`] that will open a separate window with codegen controls.
@@ -211,6 +234,11 @@ mvn exec:java -e -Dexec.mainClass=com.microsoft.playwright.CLI -Dexec.args="open
 playwright open example.com
 ```
 
+```bash csharp
+# Open page in Chromium
+playwright open example.com
+```
+
 ```bash js
 # Open page in WebKit
 npx playwright wk example.com
@@ -226,6 +254,11 @@ mvn exec:java -e -Dexec.mainClass=com.microsoft.playwright.CLI -Dexec.args="wk e
 playwright wk example.com
 ```
 
+```bash csharp
+# Open page in WebKit
+playwright wk example.com
+```
+
 ### Emulate devices
 `open` can emulate mobile and tablet devices from the [`playwright.devices`](https://playwright.dev/docs/api/class-playwright#playwrightdevices) list.
 
@@ -244,37 +277,59 @@ mvn exec:java -e -Dexec.mainClass=com.microsoft.playwright.CLI -Dexec.args='open
 playwright open --device="iPhone 11" wikipedia.org
 ```
 
+```bash csharp
+# Emulate iPhone 11.
+playwright open --device="iPhone 11" wikipedia.org
+```
+
 ### Emulate color scheme and viewport size
+
 ```bash js
 # Emulate screen size and color scheme.
 npx playwright open --viewport-size=800,600 --color-scheme=dark twitter.com
 ```
+
 ```bash java
 # Emulate screen size and color scheme.
 mvn exec:java -e -Dexec.mainClass=com.microsoft.playwright.CLI -Dexec.args="open --viewport-size=800,600 --color-scheme=dark twitter.com"
 ```
+
 ```bash python
 # Emulate screen size and color scheme.
 playwright open --viewport-size=800,600 --color-scheme=dark twitter.com
 ```
 
+```bash csharp
+# Emulate screen size and color scheme.
+playwright open --viewport-size=800,600 --color-scheme=dark twitter.com
+```
+
 ### Emulate geolocation, language and timezone
+
 ```bash js
 # Emulate timezone, language & location
 # Once page opens, click the "my location" button to see geolocation in action
 npx playwright open --timezone="Europe/Rome" --geolocation="41.890221,12.492348" --lang="it-IT" maps.google.com
 ```
+
 ```bash java
 # Emulate timezone, language & location
 # Once page opens, click the "my location" button to see geolocation in action
 mvn exec:java -e -Dexec.mainClass=com.microsoft.playwright.CLI -Dexec.args='open --timezone="Europe/Rome" --geolocation="41.890221,12.492348" --lang="it-IT" maps.google.com'
 ```
+
 ```bash python
 # Emulate timezone, language & location
 # Once page opens, click the "my location" button to see geolocation in action
 playwright open --timezone="Europe/Rome" --geolocation="41.890221,12.492348" --lang="it-IT" maps.google.com
 ```
 
+```bash csharp
+# Emulate timezone, language & location
+# Once page opens, click the "my location" button to see geolocation in action
+playwright open --timezone="Europe/Rome" --geolocation="41.890221,12.492348" --lang="it-IT" maps.google.com
+```
+
 ## Inspect selectors
 During `open` or `codegen`, you can use following API inside the developer tools console of any browser.
 
@@ -358,6 +413,15 @@ playwright screenshot \
     twitter.com twitter-iphone.png
 ```
 
+```bash csharp
+# Wait 3 seconds before capturing a screenshot after page loads ('load' event fires)
+playwright screenshot \
+    --device="iPhone 11" \
+    --color-scheme=dark \
+    --wait-for-timeout=3000 \
+    twitter.com twitter-iphone.png
+```
+
 ```bash js
 # Capture a full page screenshot
 npx playwright screenshot --full-page en.wikipedia.org wiki-full.png
@@ -373,6 +437,11 @@ mvn exec:java -e -Dexec.mainClass=com.microsoft.playwright.CLI -Dexec.args='scre
 playwright screenshot --full-page en.wikipedia.org wiki-full.png
 ```
 
+```bash csharp
+# Capture a full page screenshot
+playwright screenshot --full-page en.wikipedia.org wiki-full.png
+```
+
 ## Generate PDF
 
 PDF generation only works in Headless Chromium.
@@ -392,6 +461,11 @@ mvn exec:java -e -Dexec.mainClass=com.microsoft.playwright.CLI -Dexec.args="pdf
 playwright pdf https://en.wikipedia.org/wiki/PDF wiki.pdf
 ```
 
+```bash csharp
+# See command help
+playwright pdf https://en.wikipedia.org/wiki/PDF wiki.pdf
+```
+
 ## Install system dependencies
 
 Ubuntu 18.04 and Ubuntu 20.04 system dependencies can get installed automatically. This is useful for CI environments.
@@ -411,6 +485,11 @@ mvn exec:java -e -Dexec.mainClass=com.microsoft.playwright.CLI -Dexec.args="inst
 playwright install-deps
 ```
 
+```bash csharp
+# See command help
+playwright install-deps
+```
+
 You can also install the dependencies for a single browser only by passing it as an argument:
 
 ```bash js
@@ -425,5 +504,9 @@ mvn exec:java -e -Dexec.mainClass=com.microsoft.playwright.CLI -Dexec.args="inst
 playwright install-deps chromium
 ```
 
+```bash csharp
+playwright install-deps chromium
+```
+
 ## Known limitations
 Opening WebKit Web Inspector will disconnect Playwright from the browser. In such cases, code generation will stop.

docs/src/core-concepts.md

@@ -117,7 +117,7 @@ context = browser.new_context()
 ```
 
 ```csharp
-await using var browser  = playwright.Chromium.LaunchAsync();
+await using var browser = playwright.Chromium.LaunchAsync();
 var context = await browser.NewContextAsync();
 ```
 

docs/src/debug.md

@@ -16,6 +16,12 @@ for browser automation.
 <img width="712" alt="Playwright Inspector" src="https://user-images.githubusercontent.com/883973/108614092-8c478a80-73ac-11eb-9597-67dfce110e00.png"></img>
 
 
+## Playwright Trace Viewer
+
+[Playwright Trace Viewer](./trace-viewer.md) is a GUI tool that helps troubleshooting test runs in a post-mortem manner.
+
+<img width="1212" alt="Playwright Trace Viewer" src="https://user-images.githubusercontent.com/883973/120585896-6a1bca80-c3e7-11eb-951a-bd84002480f5.png"></img>
+
 ## Run in headed mode
 
 Playwright runs browsers in headless mode by default. To change this behavior,

docs/src/trace-viewer.md

@@ -0,0 +1,159 @@
+---
+id: trace-viewer
+title: "Trace Viewer"
+---
+
+Playwright Trace Viewer is a GUI tool that helps exploring recorded Playwright traces after the script ran.
+
+<img width="1212" alt="Playwright Trace Viewer" src="https://user-images.githubusercontent.com/883973/120585896-6a1bca80-c3e7-11eb-951a-bd84002480f5.png"></img>
+
+<!-- TOC -->
+
+## Recording a trace
+
+Traces can be recorded using the [`property: BrowserContext.tracing`] API as follows:
+
+```js
+const browser = await chromium.launch();
+const context = await browser.newContext();
+
+// Start tracing before creating / navigating a page.
+await context.tracing.start({ screenshots: true, snapshots: true });
+
+const page = await context.newPage();
+await page.goto('https://playwright.dev');
+
+// Stop tracing and export it into a zip archive.
+await context.tracing.stop({ path: 'trace.zip' });
+```
+
+```java
+Browser browser = chromium.launch();
+BrowserContext context = browser.newContext();
+
+// Start tracing before creating / navigating a page.
+context.tracing.start(new Tracing.StartOptions()
+  .setScreenshots(true)
+  .setSnapshots(true);
+
+Page page = context.newPage();
+page.goto("https://playwright.dev");
+
+// Stop tracing and export it into a zip archive.
+context.tracing.stop(new Tracing.StopOptions()
+  .setPath(Paths.get("trace.zip")));
+```
+
+```python async
+browser = await chromium.launch()
+context = await browser.new_context()
+
+# Start tracing before creating / navigating a page.
+await context.tracing.start(screenshots=True, snapshots=True)
+
+await page.goto("https://playwright.dev")
+
+# Stop tracing and export it into a zip archive.
+await context.tracing.stop(path = "trace.zip")
+```
+
+```python sync
+browser = chromium.launch()
+context = browser.new_context()
+
+# Start tracing before creating / navigating a page.
+context.tracing.start(screenshots=True, snapshots=True)
+
+page.goto("https://playwright.dev")
+
+# Stop tracing and export it into a zip archive.
+context.tracing.stop(path = "trace.zip")
+```
+
+```csharp
+await using var browser = playwright.Chromium.LaunchAsync();
+await using var context = await browser.NewContextAsync();
+
+// Start tracing before creating / navigating a page.
+await context.Tracing.StartAsync(new TracingStartOptions
+{
+  Screenshots: true,
+  Snapshots: true
+});
+
+var page = context.NewPageAsync();
+await page.GotoAsync("https://playwright.dev");
+
+// Stop tracing and export it into a zip archive.
+await context.Tracing.StopAsync(new TracingStopOptions
+{
+  Path: "trace.zip"
+});
+```
+
+This will record the trace and place it into the file named `trace.zip`.
+
+## Viewing the trace
+
+You can open the saved trace using Playwright CLI:
+
+```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
+playwright show-trace trace.zip
+```
+
+## Actions
+
+Once trace is opened, you will see the list of actions Playwright performed on the left hand side:
+
+<img width="301" alt="Actions" src="https://user-images.githubusercontent.com/883973/120588303-d39dd800-c3eb-11eb-9e8b-bfea8b775354.png"></img>
+
+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:
+
+<img width="353" alt="Film strip" src="https://user-images.githubusercontent.com/883973/120588069-5d997100-c3eb-11eb-97a3-acbd5e0eb358.png"></img>
+
+You can hover over the film strip to see a magnified image:
+
+<img width="617" alt="Magnify" src="https://user-images.githubusercontent.com/883973/120588147-8f123c80-c3eb-11eb-864b-19d800619234.png"></img>
+
+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 typ 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.|
+
+<br/>
+
+Here is what the typical Action snapshot looks like:
+
+<img width="682" alt="Snapshots" src="https://user-images.githubusercontent.com/883973/120588728-879f6300-c3ec-11eb-85d6-e67b0e92e4e3.png">
+</img>
+
+Notice how it highlights both, the DOM Node as well as the exact click position.