docs: update cli & pom docs (#8380)

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
 

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.

docs/src/intro-csharp.md

@@ -1,6 +1,6 @@
 ---
 id: intro
-title: "Getting Started"
+title: "Getting started"
 ---
 
 <!-- TOC -->
@@ -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.

docs/src/intro-java.md

@@ -1,6 +1,6 @@
 ---
 id: intro
-title: "Getting Started"
+title: "Getting started"
 ---
 
 <!-- TOC -->
@@ -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.

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.

docs/src/intro-python.md

@@ -1,6 +1,6 @@
 ---
 id: intro
-title: "Getting Started"
+title: "Getting started"
 ---
 
 <!-- TOC -->
@@ -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.

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.

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
-```
+<!-- TOC -->
 
-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.
 

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');
 });
 ```

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.
 

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).