From ef35bfa0da2f04a2dcd0f701af6faa091997de9e Mon Sep 17 00:00:00 2001 From: Pavel Feldman Date: Mon, 23 Aug 2021 20:10:12 -0700 Subject: [PATCH] docs: update cli & pom docs (#8380) --- docs/src/ci.md | 2 +- docs/src/cli.md | 5 +- docs/src/intro-csharp.md | 6 +-- docs/src/intro-java.md | 6 +-- docs/src/intro-js.md | 46 ++++++++++------- docs/src/intro-python.md | 6 +-- docs/src/library-js.md | 4 +- docs/src/test-cli-js.md | 84 +++++++++++++++++++++++++++--- docs/src/test-pom-js.md | 94 +++++++++++++++------------------- docs/src/troubleshooting-js.md | 2 +- docs/src/why-playwright.md | 6 --- 11 files changed, 161 insertions(+), 100 deletions(-) diff --git a/docs/src/ci.md b/docs/src/ci.md index 81aeba5660..0a8c950aa5 100644 --- a/docs/src/ci.md +++ b/docs/src/ci.md @@ -39,7 +39,7 @@ configurations for common CI providers. ## CI configurations -The [Command Line Interface](./cli.md#install-system-dependencies) can be used to install all operating system dependencies on GitHub Actions. +The [Command line tools](./cli.md#install-system-dependencies) can be used to install all operating system dependencies on GitHub Actions. ### GitHub Actions diff --git a/docs/src/cli.md b/docs/src/cli.md index 4f41d12f37..f5ec29faec 100644 --- a/docs/src/cli.md +++ b/docs/src/cli.md @@ -1,6 +1,6 @@ --- id: cli -title: "Command Line Interface" +title: "Command line tools" --- Playwright comes with the command line tools. @@ -571,6 +571,3 @@ 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/intro-csharp.md b/docs/src/intro-csharp.md index 18fd83addf..56071a31ac 100644 --- a/docs/src/intro-csharp.md +++ b/docs/src/intro-csharp.md @@ -1,6 +1,6 @@ --- id: intro -title: "Getting Started" +title: "Getting started" --- @@ -116,7 +116,7 @@ dotnet test -- NUnit.NumberOfTestWorkers=5 ## Record scripts -[Command Line Interface](./cli.md) can be used to record user interactions and generate C# code. +[Command line tools](./cli.md) can be used to record user interactions and generate C# code. ```bash playwright codegen @@ -143,6 +143,6 @@ dependencies to run the browsers. Only Ubuntu 18.04 and Ubuntu 20.04 are officially supported. ::: -See also in the [Command Line Interface](./cli.md#install-system-dependencies) +See also in the [Command line tools](./cli.md#install-system-dependencies) which has a command to install all necessary dependencies automatically for Ubuntu LTS releases. diff --git a/docs/src/intro-java.md b/docs/src/intro-java.md index 8329b7c856..35e7dc6761 100644 --- a/docs/src/intro-java.md +++ b/docs/src/intro-java.md @@ -1,6 +1,6 @@ --- id: intro -title: "Getting Started" +title: "Getting started" --- @@ -117,7 +117,7 @@ playwright.firefox().launch(new BrowserType.LaunchOptions().setHeadless(false).s ## Record scripts -Command Line Interface [CLI](./cli.md) can be used to record user interactions and generate Java code. +[Command line tools](./cli.md) can be used to record user interactions and generate Java code. ```bash mvn exec:java -e -Dexec.mainClass=com.microsoft.playwright.CLI -Dexec.args="codegen wikipedia.org" @@ -145,6 +145,6 @@ dependencies to run the browsers. Only Ubuntu 18.04 and Ubuntu 20.04 are officially supported. ::: -See also in the [Command Line Interface](./cli.md#install-system-dependencies) +See also in the [Command line tools](./cli.md#install-system-dependencies) which has a command to install all necessary dependencies automatically for Ubuntu LTS releases. diff --git a/docs/src/intro-js.md b/docs/src/intro-js.md index db57da7440..c82f9b64d7 100644 --- a/docs/src/intro-js.md +++ b/docs/src/intro-js.md @@ -1,6 +1,6 @@ --- id: intro -title: "Getting Started" +title: "Getting started" --- Playwright can either be used as a part of the Playwright Test (this guide), or as a [Playwright Library](./library.md). @@ -229,23 +229,13 @@ test.describe('feature foo', () => { ``` -## Learning the command line +## Command line -Here are the most common options available in the [command line](./test-cli.md). +Following are the usual command line patterns. Learn more about the [command line](./test-cli.md). -- Run tests in headed browsers +- Run all the tests ```bash - npx playwright test --headed - ``` - -- Run tests in a particular browser - ```bash - npx playwright test --browser=webkit - ``` - -- Run tests in all browsers - ```bash - npx playwright test --browser=all + npx playwright test ``` - Run a single test file @@ -258,14 +248,29 @@ Here are the most common options available in the [command line](./test-cli.md). npx playwright test tests/todo-page/ tests/landing-page/ ``` -- Run a test with specific title +- Run files that have `my-spec` or `my-spec-2` in the file name + ```bash + npx playwright test my-spec my-spec-2 + ``` + +- Run the test with the title ```bash npx playwright test -g "add a todo item" ``` -- Run tests [in parallel](./test-parallel.md) - that's the default +- Run tests in headed browsers ```bash - npx playwright test + npx playwright test --headed + ``` + +- Run tests in a particular browser (config-less mode) + ```bash + npx playwright test --browser=webkit + ``` + +- Run tests in all browsers (config-less mode) + ```bash + npx playwright test --browser=all ``` - Disable [parallelization](./test-parallel.md) @@ -292,6 +297,11 @@ Here are the most common options available in the [command line](./test-cli.md). npx playwright test ``` +- Ask for help + ```bash + npx playwright test --help + ``` + ## Creating a configuration file So far, we've looked at the zero-config operation of Playwright Test. For a real world application, it is likely that you would want to use a config. diff --git a/docs/src/intro-python.md b/docs/src/intro-python.md index 5bdfa4b41e..eaa930b3c7 100644 --- a/docs/src/intro-python.md +++ b/docs/src/intro-python.md @@ -1,6 +1,6 @@ --- id: intro -title: "Getting Started" +title: "Getting started" --- @@ -89,7 +89,7 @@ firefox.launch(headless=False, slow_mo=50) ## Record scripts -Command Line Interface [CLI](./cli.md) can be used to record user interactions and generate Python code. +[Command line tools](./cli.md) can be used to record user interactions and generate Python code. ```bash playwright codegen wikipedia.org @@ -204,6 +204,6 @@ dependencies to run the browsers. Only Ubuntu 18.04 and Ubuntu 20.04 are officially supported. ::: -See also in the [Command Line Interface](./cli.md#install-system-dependencies) +See also in the [Command line tools](./cli.md#install-system-dependencies) which has a command to install all necessary dependencies automatically for Ubuntu LTS releases. diff --git a/docs/src/library-js.md b/docs/src/library-js.md index 1ba65da83b..2cafd8522a 100644 --- a/docs/src/library-js.md +++ b/docs/src/library-js.md @@ -63,7 +63,7 @@ firefox.launch({ headless: false, slowMo: 50 }); ## Record scripts -Command Line Interface [CLI](./cli.md) can be used to record user interactions and generate JavaScript code. +[Command line tools](./cli.md) can be used to record user interactions and generate JavaScript code. ```bash npx playwright codegen wikipedia.org @@ -117,6 +117,6 @@ dependencies to run the browsers. Only Ubuntu 18.04 and Ubuntu 20.04 are officially supported. ::: -See also in the [Command Line Interface](./cli.md#install-system-dependencies) +See also in the [Command line tools](./cli.md#install-system-dependencies) which has a command to install all necessary dependencies automatically for Ubuntu LTS releases. diff --git a/docs/src/test-cli-js.md b/docs/src/test-cli-js.md index 5313dd9cf2..35152ec217 100644 --- a/docs/src/test-cli-js.md +++ b/docs/src/test-cli-js.md @@ -1,16 +1,86 @@ --- id: test-cli -title: "Advanced: command line" +title: "Command line" --- -```bash -# Ask for help! -npx playwright test --help -``` + -Arguments passed to `npx playwright test` are treated as a filter for test files. For example, `npx playwright test my-spec` will only run tests from files with `my-spec` in the name. +## Examples -All the options are available in the [configuration file](./test-advanced.md). However, selected options can be passed to a command line and take a priority over the configuration file. +Here are the most common options available in the command line. + +- Run all the tests + ```bash + npx playwright test + ``` + +- Run a single test file + ```bash + npx playwright test tests/todo-page.spec.ts + ``` + +- Run a set of test files + ```bash + npx playwright test tests/todo-page/ tests/landing-page/ + ``` + +- Run files that have `my-spec` or `my-spec-2` in the file name + ```bash + npx playwright test my-spec my-spec-2 + ``` + +- Run the test with the title + ```bash + npx playwright test -g "add a todo item" + ``` + +- Run tests in headed browsers + ```bash + npx playwright test --headed + ``` + +- Run tests in a particular browser (config-less mode) + ```bash + npx playwright test --browser=webkit + ``` + +- Run tests in all browsers (config-less mode) + ```bash + npx playwright test --browser=all + ``` + +- Disable [parallelization](./test-parallel.md) + ```bash + npx playwright test --workers=1 + ``` + +- Choose a [reporter](./test-reporters.md) + ```bash + npx playwright test --reporter=dot + ``` + +- Run in debug mode with [Playwright Inspector](./inspector.md) + ```bash + # Linux/macOS + PWDEBUG=1 npx playwright test + + # Windows with cmd.exe + set PWDEBUG=1 + npx playwright test + + # Windows with PowerShell + $env:PWDEBUG=1 + npx playwright test + ``` + +- Ask for help + ```bash + npx playwright test --help + ``` + +## Reference + +Complete set of Playwright Test options is available in the [configuration file](./test-advanced.md). Following options can be passed to a command line and take a priority over the configuration file: - `--headed`: Run tests in headed browsers. Useful for debugging. diff --git a/docs/src/test-pom-js.md b/docs/src/test-pom-js.md index 2130947372..2325d8567c 100644 --- a/docs/src/test-pom-js.md +++ b/docs/src/test-pom-js.md @@ -9,65 +9,69 @@ We will create a `PlaywrightDevPage` helper class to encapsulate common operatio ```js js-flavor=js // playwright-dev-page.js +const { expect } = require('@playwright/test'); + exports.PlaywrightDevPage = class PlaywrightDevPage { + /** - * @param {import('playwright').Page} page + * @param {import('@playwright/test').Page} page */ constructor(page) { this.page = page; + this.getStartedLink = page.locator('text=Get started'); + this.coreConceptsLink = page.locator('text=Core concepts'); + this.tocList = page.locator('article ul > li > a'); } async goto() { await this.page.goto('https://playwright.dev'); } - async toc() { - const text = await this.page.innerText('article ul'); - return text.split('\n').filter(line => !!line); - } - async getStarted() { - await this.page.click('text=Get started'); - await this.page.waitForSelector(`text=Core concepts`); + await this.getStartedLink.first().click(); + await expect(this.coreConceptsLink).toBeVisible(); } async coreConcepts() { await this.getStarted(); - await this.page.click('text=Core concepts'); - await this.page.waitForSelector(`h1:has-text("Core concepts")`); + await this.page.click('text=Guides'); + await this.coreConceptsLink.click(); + await expect(this.page.locator('h1').locator("text=Core concepts")).toBeVisible(); } } ``` ```js js-flavor=ts // playwright-dev-page.ts -import type { Page } from 'playwright'; +import { expect, Locator, Page } from '@playwright/test'; export class PlaywrightDevPage { readonly page: Page; + readonly getStartedLink: Locator; + readonly coreConceptsLink: Locator; + readonly tocList: Locator; constructor(page: Page) { this.page = page; + this.getStartedLink = page.locator('text=Get started'); + this.coreConceptsLink = page.locator('text=Core concepts'); + this.tocList = page.locator('article ul > li > a'); } async goto() { await this.page.goto('https://playwright.dev'); } - async toc() { - const text = await this.page.innerText('article ul'); - return text.split('\n').filter(line => !!line); - } - async getStarted() { - await this.page.click('text=Get started'); - await this.page.waitForSelector(`text=Core concepts`); + await this.getStartedLink.first().click(); + await expect(this.coreConceptsLink).toBeVisible(); } async coreConcepts() { await this.getStarted(); - await this.page.click('text=Core concepts'); - await this.page.waitForSelector(`h1:has-text("Core concepts")`); + await this.page.click('text=Guides'); + await this.coreConceptsLink.click(); + await expect(this.page.locator('h1').locator("text=Core concepts")).toBeVisible(); } } ``` @@ -83,14 +87,15 @@ test('Get Started table of contents', async ({ page }) => { const playwrightDev = new PlaywrightDevPage(page); await playwrightDev.goto(); await playwrightDev.getStarted(); - expect(await playwrightDev.toc()).toEqual([ + await expect(playwrightDev.tocList).toHaveText([ 'Installation', - 'Usage', - 'First script', - 'Record scripts', - 'TypeScript support', - 'System requirements', - 'Release notes' + 'First test', + 'Writing assertions', + 'Using test fixtures', + 'Using test hooks', + 'Learning the command line', + 'Creating a configuration file', + 'Release notes', ]); }); @@ -98,15 +103,7 @@ test('Core Concepts table of contents', async ({ page }) => { const playwrightDev = new PlaywrightDevPage(page); await playwrightDev.goto(); await playwrightDev.coreConcepts(); - expect(await playwrightDev.toc()).toEqual([ - 'Browser', - 'Browser contexts', - 'Pages and frames', - 'Selectors', - 'Auto-waiting', - 'Execution contexts: Playwright and Browser', - 'Evaluation Argument' - ]); + await expect(playwrightDev.tocList.first()).toHaveText('Browser'); }); ``` @@ -119,14 +116,15 @@ test('Get Started table of contents', async ({ page }) => { const playwrightDev = new PlaywrightDevPage(page); await playwrightDev.goto(); await playwrightDev.getStarted(); - expect(await playwrightDev.toc()).toEqual([ + await expect(playwrightDev.tocList).toHaveText([ 'Installation', - 'Usage', - 'First script', - 'Record scripts', - 'TypeScript support', - 'System requirements', - 'Release notes' + 'First test', + 'Writing assertions', + 'Using test fixtures', + 'Using test hooks', + 'Learning the command line', + 'Creating a configuration file', + 'Release notes', ]); }); @@ -134,14 +132,6 @@ test('Core Concepts table of contents', async ({ page }) => { const playwrightDev = new PlaywrightDevPage(page); await playwrightDev.goto(); await playwrightDev.coreConcepts(); - expect(await playwrightDev.toc()).toEqual([ - 'Browser', - 'Browser contexts', - 'Pages and frames', - 'Selectors', - 'Auto-waiting', - 'Execution contexts: Playwright and Browser', - 'Evaluation Argument' - ]); + await expect(playwrightDev.tocList.first()).toHaveText('Browser'); }); ``` diff --git a/docs/src/troubleshooting-js.md b/docs/src/troubleshooting-js.md index 457b097f6d..7665637939 100644 --- a/docs/src/troubleshooting-js.md +++ b/docs/src/troubleshooting-js.md @@ -10,7 +10,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 Interface](./cli.md#install-system-dependencies) +See also in the [Command line tools](./cli.md#install-system-dependencies) which has a command to install all necessary dependencies automatically for Ubuntu LTS releases. diff --git a/docs/src/why-playwright.md b/docs/src/why-playwright.md index 141f65f387..6f9e733bb5 100644 --- a/docs/src/why-playwright.md +++ b/docs/src/why-playwright.md @@ -34,9 +34,3 @@ Playwright enables fast, reliable and capable testing and automation across all * **Modern web features**. Playwright supports web components through [shadow-piercing selectors](./selectors.md), [geolocation, permissions](./emulation.md), web workers and other modern web APIs. * **Capabilities to cover all scenarios**. Support for [file downloads](./downloads.md) and [uploads](./input.md), out-of-process iframes, native [input events](./input.md), and even [dark mode](./emulation.md). - -## Limitations - -* **Legacy Edge and IE11 support**. Playwright does not support legacy Microsoft Edge or IE11 ([deprecation notice](https://techcommunity.microsoft.com/t5/microsoft-365-blog/microsoft-365-apps-say-farewell-to-internet-explorer-11-and/ba-p/1591666)). The new Microsoft Edge (on Chromium) is supported. - -* **Test on real mobile devices**: Playwright uses desktop browsers to emulate mobile devices. There is experimental [Android] support available. If you are interested in iOS, please [upvote this issue](https://github.com/microsoft/playwright/issues/1122).