diff --git a/docs/src/ci.md b/docs/src/ci.md index b0edb4a68f..96c10020bc 100644 --- a/docs/src/ci.md +++ b/docs/src/ci.md @@ -13,7 +13,7 @@ configurations for common CI providers. 3 steps to get your tests running on CI: 1. **Ensure CI agent can run browsers**: Use [our Docker image](./docker.md) - in Linux agents or install your dependencies using the [CLI](./cli.md#install-system-dependencies). + in Linux agents or install your dependencies using the [CLI](./browsers#install-system-dependencies). 1. **Install Playwright**: ```bash js # Install NPM packages @@ -51,7 +51,7 @@ configurations for common CI providers. ## CI configurations -The [Command line tools](./cli.md#install-system-dependencies) can be used to install all operating system dependencies on GitHub Actions. +The [Command line tools](./browsers#install-system-dependencies) can be used to install all operating system dependencies on GitHub Actions. ### GitHub Actions @@ -291,7 +291,7 @@ For Windows or macOS agents, no additional configuration required, just install For Linux agents, you can use [our Docker container](./docker.md) with Azure Pipelines support [running containerized jobs](https://docs.microsoft.com/en-us/azure/devops/pipelines/process/container-phases?view=azure-devops). -Alternatively, you can use [Command line tools](./cli.md#install-system-dependencies) to install all necessary dependencies. +Alternatively, you can use [Command line tools](./browsers#install-system-dependencies) to install all necessary dependencies. For running the Playwright tests use this pipeline task: ```yml diff --git a/docs/src/cli.md b/docs/src/cli.md deleted file mode 100644 index fdec9af6c6..0000000000 --- a/docs/src/cli.md +++ /dev/null @@ -1,592 +0,0 @@ ---- -id: cli -title: "Command line tools" ---- - -Playwright comes with the command line tools. - -## Usage - -```bash js -npx playwright --help -``` - -```bash java -mvn exec:java -e -D exec.mainClass=com.microsoft.playwright.CLI -``` - -```bash python -playwright -``` - -```bash csharp -# Use the tools. -pwsh bin/Debug/netX/playwright.ps1 --help -``` - -```json js -# Running from `package.json` script -{ - "scripts": { - "help": "playwright --help" - } -} -``` - -## Install browsers - -Playwright can install supported browsers. - -```bash js -# Running without arguments will install default browsers -npx playwright install -``` - -```bash java -# Running without arguments will install default browsers -mvn exec:java -e -D exec.mainClass=com.microsoft.playwright.CLI -D exec.args="install" -``` - -```bash python -# Running without arguments will install default browsers -playwright install -``` - -```bash csharp -# Running without arguments will install default browsers -pwsh bin/Debug/netX/playwright.ps1 install -``` - -You can also install specific browsers by providing an argument: - -```bash js -# Install WebKit -npx playwright install webkit -``` - -```bash java -# Install WebKit -mvn exec:java -e -D exec.mainClass=com.microsoft.playwright.CLI -D exec.args="install webkit" -``` - -```bash python -# Install WebKit -playwright install webkit -``` - -```bash csharp -# Install WebKit -pwsh bin/Debug/netX/playwright.ps1 install webkit -``` - -See all supported browsers: - -```bash js -npx playwright install --help -``` - -```bash java -mvn exec:java -e -D exec.mainClass=com.microsoft.playwright.CLI -D exec.args="install --help" -``` - -```bash python -playwright install --help -``` - -```bash csharp -pwsh bin/Debug/netX/playwright.ps1 install --help -``` - -## Install system dependencies - -System dependencies can get installed automatically. This is useful for CI environments. - -```bash js -# See command help -npx playwright install-deps -``` - -```bash java -# See command help -mvn exec:java -e -D exec.mainClass=com.microsoft.playwright.CLI -D exec.args="install-deps" -``` - -```bash python -# See command help -playwright install-deps -``` - -```bash csharp -# See command help -pwsh bin/Debug/netX/playwright.ps1 install-deps -``` - -You can also install the dependencies for a single browser only by passing it as an argument: - -```bash js -npx playwright install-deps chromium -``` - -```bash java -mvn exec:java -e -D exec.mainClass=com.microsoft.playwright.CLI -D exec.args="install-deps chromium" -``` - -```bash python -playwright install-deps chromium -``` - -```bash csharp -pwsh bin/Debug/netX/playwright.ps1 install-deps chromium -``` - -It's also possible to combine `install-deps` with `install` and install by that the browsers and OS dependencies with a single command. This would do both for Chromium, but you can also leave it out. - -```bash js -npx playwright install --with-deps chromium -``` - -```bash java -mvn exec:java -e -D exec.mainClass=com.microsoft.playwright.CLI -D exec.args="install --with-deps chromium" -``` - -```bash python -playwright install --with-deps chromium -``` - -```bash csharp -pwsh bin/Debug/netX/playwright.ps1 install --with-deps chromium -``` - -## Generate code - -```bash js -npx playwright codegen wikipedia.org -``` - -```bash java -mvn exec:java -e -D exec.mainClass=com.microsoft.playwright.CLI -D exec.args="codegen wikipedia.org" -``` - -```bash python -playwright codegen wikipedia.org -``` - -```bash csharp -pwsh bin/Debug/netX/playwright.ps1 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. - - - -### Preserve authenticated state - -Run `codegen` with `--save-storage` to save [cookies](https://developer.mozilla.org/en-US/docs/Web/HTTP/Cookies) and [localStorage](https://developer.mozilla.org/en-US/docs/Web/API/Window/localStorage) at the end. This is useful to separately record authentication step and reuse it later. - -```bash js -npx playwright codegen --save-storage=auth.json -# Perform authentication and exit. -# auth.json will contain the storage state. -``` - -```bash java -mvn exec:java -e -D exec.mainClass=com.microsoft.playwright.CLI -D exec.args="codegen --save-storage=auth.json" -# Perform authentication and exit. -# auth.json will contain the storage state. -``` - -```bash python -playwright codegen --save-storage=auth.json -# Perform authentication and exit. -# auth.json will contain the storage state. -``` - -```bash csharp -pwsh bin/Debug/netX/playwright.ps1 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 -npx playwright open --load-storage=auth.json my.web.app -npx playwright codegen --load-storage=auth.json my.web.app -# Perform actions in authenticated state. -``` - -```bash java -mvn exec:java -e -D exec.mainClass=com.microsoft.playwright.CLI -D exec.args="open --load-storage=auth.json my.web.app" -mvn exec:java -e -D exec.mainClass=com.microsoft.playwright.CLI -D exec.args="codegen --load-storage=auth.json my.web.app" -# Perform authentication and exit. -# auth.json will contain the storage state. -``` - -```bash python -playwright open --load-storage=auth.json my.web.app -playwright codegen --load-storage=auth.json my.web.app -# Perform actions in authenticated state. -``` - -```bash csharp -pwsh bin/Debug/netX/playwright.ps1 open --load-storage=auth.json my.web.app -pwsh bin/Debug/netX/playwright.ps1 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. - -```js -const { chromium } = require('playwright'); - -(async () => { - // Make sure to run headed. - const browser = await chromium.launch({ headless: false }); - - // Setup context however you like. - const context = await browser.newContext({ /* pass any options */ }); - await context.route('**/*', route => route.continue()); - - // Pause the page, and start recording manually. - const page = await context.newPage(); - await page.pause(); -})(); -``` - -```java -import com.microsoft.playwright.*; - -public class Example { - public static void main(String[] args) { - try (Playwright playwright = Playwright.create()) { - BrowserType chromium = playwright.chromium(); - // Make sure to run headed. - Browser browser = chromium.launch(new BrowserType.LaunchOptions().setHeadless(false)); - // Setup context however you like. - BrowserContext context = browser.newContext(/* pass any options */); - context.route("**/*", route -> route.resume()); - // Pause the page, and start recording manually. - Page page = context.newPage(); - page.pause(); - } - } -} -``` - -```python async -import asyncio -from playwright.async_api import async_playwright - -async def main(): - async with async_playwright() as p: - # Make sure to run headed. - browser = await p.chromium.launch(headless=False) - - # Setup context however you like. - context = await browser.new_context() # Pass any options - await context.route('**/*', lambda route: route.continue_()) - - # Pause the page, and start recording manually. - page = await context.new_page() - await page.pause() - -asyncio.run(main()) -``` - -```python sync -from playwright.sync_api import sync_playwright - -with sync_playwright() as p: - # Make sure to run headed. - browser = p.chromium.launch(headless=False) - - # Setup context however you like. - context = browser.new_context() # Pass any options - context.route('**/*', lambda route: route.continue_()) - - # Pause the page, and start recording manually. - page = context.new_page() - page.pause() -``` - -```csharp -using Microsoft.Playwright; - -using var playwright = await Playwright.CreateAsync(); -var chromium = playwright.Chromium; -// Make sure to run headed. -var browser = await chromium.LaunchAsync(new() { Headless = false }); - -// Setup context however you like. -var context = await browser.NewContextAsync(); // Pass any options -await context.RouteAsync("**/*", route => route.ContinueAsync()); - -// Pause the page, and start recording manually. -var page = await context.NewPageAsync(); -await page.PauseAsync(); -``` - -## Open pages - -With `open`, you can use Playwright bundled browsers to browse web pages. Playwright provides cross-platform WebKit builds that can be used to reproduce Safari rendering across Windows, Linux and macOS. - -```bash js -# Open page in Chromium -npx playwright open example.com -``` - -```bash java -# Open page in Chromium -mvn exec:java -e -D exec.mainClass=com.microsoft.playwright.CLI -D exec.args="open example.com" -``` - -```bash python -# Open page in Chromium -playwright open example.com -``` - -```bash csharp -# Open page in Chromium -pwsh bin/Debug/netX/playwright.ps1 open example.com -``` - -```bash js -# Open page in WebKit -npx playwright wk example.com -``` - -```bash java -# Open page in WebKit -mvn exec:java -e -D exec.mainClass=com.microsoft.playwright.CLI -D exec.args="wk example.com" -``` - -```bash python -# Open page in WebKit -playwright wk example.com -``` - -```bash csharp -# Open page in WebKit -pwsh bin/Debug/netX/playwright.ps1 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. - -```bash js -# Emulate iPhone 11. -npx playwright open --device="iPhone 11" wikipedia.org -``` - -```bash java -# Emulate iPhone 11. -mvn exec:java -e -D exec.mainClass=com.microsoft.playwright.CLI -D exec.args='open --device="iPhone 11" wikipedia.org' -``` - -```bash python -# Emulate iPhone 11. -playwright open --device="iPhone 11" wikipedia.org -``` - -```bash csharp -# Emulate iPhone 11. -pwsh bin/Debug/netX/playwright.ps1 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 -D exec.mainClass=com.microsoft.playwright.CLI -D exec.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. -pwsh bin/Debug/netX/playwright.ps1 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 -D exec.mainClass=com.microsoft.playwright.CLI -D exec.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 -pwsh bin/Debug/netX/playwright.ps1 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. - - - -#### playwright.$(selector) - -Query Playwright selector, using the actual Playwright query engine, for example: - -```js -> playwright.$('.auth-form >> text=Log in'); - - -``` - -#### playwright.$$(selector) - -Same as `playwright.$`, but returns all matching elements. - -```js -> playwright.$$('li >> text=John') - -> [
  • ,
  • ,
  • ,
  • ] -``` - -#### playwright.inspect(selector) - -Reveal element in the Elements panel (if DevTools of the respective browser supports it). - -```js -> playwright.inspect('text=Log in') -``` - -#### playwright.locator(selector) - -Query Playwright element using the actual Playwright query engine, for example: - -```js -> playwright.locator('.auth-form', { hasText: 'Log in' }); - -> Locator () -> - element: button -> - elements: [button] -``` - -#### playwright.selector(element) - -Generates selector for the given element. - -```js -> playwright.selector($0) - -"div[id="glow-ingress-block"] >> text=/.*Hello.*/" -``` - -## Take screenshot - -```bash js -# See command help -npx playwright screenshot --help -``` - -```bash java -# See command help -mvn exec:java -e -D exec.mainClass=com.microsoft.playwright.CLI -D exec.args="screenshot --help" -``` - -```bash python -# See command help -playwright screenshot --help -``` - -```bash js -# Wait 3 seconds before capturing a screenshot after page loads ('load' event fires) -npx playwright screenshot \ - --device="iPhone 11" \ - --color-scheme=dark \ - --wait-for-timeout=3000 \ - twitter.com twitter-iphone.png -``` - -```bash java -# Wait 3 seconds before capturing a screenshot after page loads ('load' event fires) -mvn exec:java -e -D exec.mainClass=com.microsoft.playwright.CLI -D exec.args='screenshot --device="iPhone 11" --color-scheme=dark --wait-for-timeout=3000 twitter.com twitter-iphone.png' -``` - -```bash python -# 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 csharp -# Wait 3 seconds before capturing a screenshot after page loads ('load' event fires) -pwsh bin/Debug/netX/playwright.ps1 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 -``` - -```bash java -# Capture a full page screenshot -mvn exec:java -e -D exec.mainClass=com.microsoft.playwright.CLI -D exec.args='screenshot --full-page en.wikipedia.org wiki-full.png' -``` - -```bash python -# Capture a full page screenshot -playwright screenshot --full-page en.wikipedia.org wiki-full.png -``` - -```bash csharp -# Capture a full page screenshot -pwsh bin/Debug/netX/playwright.ps1 screenshot --full-page en.wikipedia.org wiki-full.png -``` - -## Generate PDF - -PDF generation only works in Headless Chromium. - -```bash js -# See command help -npx playwright pdf https://en.wikipedia.org/wiki/PDF wiki.pdf -``` - -```bash java -# See command help -mvn exec:java -e -D exec.mainClass=com.microsoft.playwright.CLI -D exec.args="pdf https://en.wikipedia.org/wiki/PDF wiki.pdf" -``` - -```bash python -# See command help -playwright pdf https://en.wikipedia.org/wiki/PDF wiki.pdf -``` - -```bash csharp -# See command help -pwsh bin/Debug/netX/playwright.ps1 pdf https://en.wikipedia.org/wiki/PDF wiki.pdf -``` diff --git a/docs/src/library-js.md b/docs/src/library-js.md index 3eb44371c0..9ed21dce7e 100644 --- a/docs/src/library-js.md +++ b/docs/src/library-js.md @@ -171,7 +171,7 @@ firefox.launch({ headless: false, slowMo: 50 }); ## Record scripts -[Command line tools](./cli.md) can be used to record user interactions and generate JavaScript code. +[Command line tools](./test-cli.md) can be used to record user interactions and generate JavaScript code. ```bash npx playwright codegen wikipedia.org diff --git a/docs/src/network.md b/docs/src/network.md index b8d0fe5ef4..6da91a78bf 100644 --- a/docs/src/network.md +++ b/docs/src/network.md @@ -715,7 +715,7 @@ You can record network activity as an HTTP Archive file (HAR). Later on, this ar ### Recording HAR with CLI -Open the browser with [Playwright CLI](./cli.md) and pass `--save-har` option to produce a HAR file. Optionally, use `--save-har-glob` to only save requests you are interested in, for example API endpoints. If the har file name ends with `.zip`, artifacts are written as separate files and are all compressed into a single `zip`. +Open the browser with Playwright CLI and pass `--save-har` option to produce a HAR file. Optionally, use `--save-har-glob` to only save requests you are interested in, for example API endpoints. If the har file name ends with `.zip`, artifacts are written as separate files and are all compressed into a single `zip`. ```bash js # Save API requests from example.com as "example.har" archive. diff --git a/docs/src/release-notes-csharp.md b/docs/src/release-notes-csharp.md index 2466ccce25..4be9356d8e 100644 --- a/docs/src/release-notes-csharp.md +++ b/docs/src/release-notes-csharp.md @@ -831,7 +831,7 @@ await button.ClickAsync("button >> visible=true"); #### Highlights - Playwright for .NET v1.12 is now stable! -- Ships with the [codegen](./cli.md#generate-code) and [trace viewer](./trace-viewer.md) tools out-of-the-box +- Ships with the [codegen](./codegen.md) and [trace viewer](./trace-viewer.md) tools out-of-the-box #### Browser Versions diff --git a/docs/src/release-notes-java.md b/docs/src/release-notes-java.md index 5b5b3b1cf0..025128c5c6 100644 --- a/docs/src/release-notes-java.md +++ b/docs/src/release-notes-java.md @@ -922,7 +922,7 @@ This version of Playwright was also tested against the following stable channels ## Version 1.8 - [Selecting elements based on layout](./other-locators.md#css-matching-elements-based-on-layout) with `:left-of()`, `:right-of()`, `:above()` and `:below()`. -- Playwright now includes [command line interface](./cli.md), former playwright-cli. +- Playwright now includes command line interface, former playwright-cli. ```bash java mvn exec:java -e -D exec.mainClass=com.microsoft.playwright.CLI -D exec.args="--help" ``` diff --git a/docs/src/release-notes-js.md b/docs/src/release-notes-js.md index 86c1a47f96..bc82f4a572 100644 --- a/docs/src/release-notes-js.md +++ b/docs/src/release-notes-js.md @@ -1765,7 +1765,7 @@ This version of Playwright was also tested against the following stable channels ## Version 1.8 - [Selecting elements based on layout](./other-locators.md#css-matching-elements-based-on-layout) with `:left-of()`, `:right-of()`, `:above()` and `:below()`. -- Playwright now includes [command line interface](./cli.md), former playwright-cli. +- Playwright now includes [command line interface](./test-cli.md), former playwright-cli. ```bash js npx playwright --help ``` diff --git a/docs/src/release-notes-python.md b/docs/src/release-notes-python.md index 03452f61a9..259347cee0 100644 --- a/docs/src/release-notes-python.md +++ b/docs/src/release-notes-python.md @@ -1003,7 +1003,7 @@ This version of Playwright was also tested against the following stable channels ## Version 1.8 - [Selecting elements based on layout](./other-locators.md#css-matching-elements-based-on-layout) with `:left-of()`, `:right-of()`, `:above()` and `:below()`. -- Playwright now includes [command line interface](./cli.md), former playwright-cli. +- Playwright now includes command line interface, former playwright-cli. ```bash python playwright --help ``` diff --git a/docs/src/troubleshooting.md b/docs/src/troubleshooting.md index 19e8f2fb3d..09cd2edf92 100644 --- a/docs/src/troubleshooting.md +++ b/docs/src/troubleshooting.md @@ -8,7 +8,7 @@ title: "Troubleshooting" Playwright does self-inspection every time it runs to make sure the browsers can be launched successfully. If there are missing dependencies, playwright will print instructions to acquire them. -See also in the [Command line tools](./cli.md#install-system-dependencies) +See also in the [browsers](./browsers.md#install-system-dependencies) doc which has a command to install all necessary dependencies automatically for Ubuntu LTS releases. @@ -89,7 +89,7 @@ dependencies to run the browsers. Only Debian 11, Ubuntu 20.04 and 22.04 are officially supported. ::: -See also in the [Command line tools](./cli.md#install-system-dependencies) +See also in the [browsers](./browsers.md#install-system-dependencies) doc which has a command to install all necessary dependencies automatically for Ubuntu LTS releases.