diff --git a/docs/src/api/class-browsercontext.md b/docs/src/api/class-browsercontext.md index 851f0b9e4d..34c897af02 100644 --- a/docs/src/api/class-browsercontext.md +++ b/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 diff --git a/docs/src/api/class-download.md b/docs/src/api/class-download.md index e00b6c4727..7464ebbb88 100644 --- a/docs/src/api/class-download.md +++ b/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. diff --git a/docs/src/api/class-page.md b/docs/src/api/class-page.md index 623d73962f..ce93713476 100644 --- a/docs/src/api/class-page.md +++ b/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 diff --git a/docs/src/api/class-tracing.md b/docs/src/api/class-tracing.md index 48be69c56b..e171c21b93 100644 --- a/docs/src/api/class-tracing.md +++ b/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]> diff --git a/docs/src/api/params.md b/docs/src/api/params.md index 9f2b4896a2..3b88a716d1 100644 --- a/docs/src/api/params.md +++ b/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. diff --git a/docs/src/cli.md b/docs/src/cli.md index 45528ae455..3e0191341f 100644 --- a/docs/src/cli.md +++ b/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. @@ -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. @@ -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. diff --git a/docs/src/core-concepts.md b/docs/src/core-concepts.md index cab03431f1..c9893cc30c 100644 --- a/docs/src/core-concepts.md +++ b/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(); ``` diff --git a/docs/src/debug.md b/docs/src/debug.md index 149a73176f..e6d37f17d0 100644 --- a/docs/src/debug.md +++ b/docs/src/debug.md @@ -16,6 +16,12 @@ for browser automation. Playwright Inspector +## Playwright Trace Viewer + +[Playwright Trace Viewer](./trace-viewer.md) is a GUI tool that helps troubleshooting test runs in a post-mortem manner. + +Playwright Trace Viewer + ## Run in headed mode Playwright runs browsers in headless mode by default. To change this behavior, diff --git a/docs/src/trace-viewer.md b/docs/src/trace-viewer.md new file mode 100644 index 0000000000..f7fdef05fc --- /dev/null +++ b/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. + +Playwright Trace Viewer + + + +## 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: + +Actions + +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: + +Film strip + +You can hover over the film strip to see a magnified image: + +Magnify + +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.| + +
+ +Here is what the typical Action snapshot looks like: + +Snapshots + + +Notice how it highlights both, the DOM Node as well as the exact click position.