docs(test runner): more basic docs (#6803)

docs/src/test-cli.md

@@ -1,6 +1,6 @@
 ---
 id: test-cli
-title: "Command Line"
+title: "Advanced Command Line"
 ---
 
 ```sh

docs/src/test-configuration.md

@@ -5,9 +5,7 @@ title: "Configuration"
 
 <!-- TOC -->
 
-<br/>
-
-## Configure [Browser], [BrowserContext], videos and screenshots
+## Configure browser, context, videos and screenshots
 
 Playwright Tests supports browser and context options that you typically pass to [`method: BrowserType.launch`] and [`method: Browser.newContext`] methods, for example `headless`, `viewport` or `ignoreHTTPSErrors`. It also provides options to record video for the test or capture screenshot at the end.
 
@@ -16,19 +14,19 @@ You can specify any options either locally in a test file, or globally in the co
 - Browser options match [`method: BrowserType.launch`] method.
 - Context options match [`method: Browser.newContext`] method.
 - `screenshot` option - whether to capture a screenshot after each test, off by default. Screenshot will appear in the test output directory, typically `test-results`.
-  - `off` - Do not capture screenshots.
-  - `on` - Capture screenshot after each test.
-  - `only-on-failure` - Capture screenshot after each test failure.
-- `video` options - whether to record video for each test, off by default. Video will appear in the test output directory, typically `test-results`.
-  - `off` - Do not record video.
-  - `on` - Record video for each test.
-  - `retain-on-failure`  - Record video for each test, but remove all videos from successful test runs.
-  - `retry-with-video` - Record video only when retrying a test.
+  - `'off'` - Do not capture screenshots.
+  - `'on'` - Capture screenshot after each test.
+  - `'only-on-failure'` - Capture screenshot after each test failure.
+- `video` option - whether to record video for each test, off by default. Video will appear in the test output directory, typically `test-results`.
+  - `'off'` - Do not record video.
+  - `'on'` - Record video for each test.
+  - `'retain-on-failure'` - Record video for each test, but remove all videos from successful test runs.
+  - `'retry-with-video'` - Record video only when retrying a test.
 
 
 ### Global configuration
 
-Create `playwright.config.js` (or `playwright.config.ts`) to configure your tests, and specify options in the `use` section. Playwright Test will automatically pick it up.
+Create `playwright.config.js` (or `playwright.config.ts`) and specify options in the `use` section.
 
 ```js
 module.exports = {
@@ -40,6 +38,10 @@ module.exports = {
     // Context options
     viewport: { width: 1280, height: 720 },
     ignoreHTTPSErrors: true,
+
+    // Artifacts
+    screenshot: 'only-on-failure',
+    video: 'retry-with-video',
   },
 };
 ```
@@ -55,11 +57,21 @@ const config: PlaywrightTestConfig = {
     // Context options
     viewport: { width: 1280, height: 720 },
     ignoreHTTPSErrors: true,
+
+    // Artifacts
+    screenshot: 'only-on-failure',
+    video: 'retry-with-video',
   },
 };
 export default config;
 ```
 
+Now run tests as usual, Playwright Test will pick up the configuration file automatically.
+
+```sh
+npx playwright test --browser=firefox
+```
+
 If you put your configuration file in a different place, pass it with `--config` option.
 
 ```sh
@@ -68,7 +80,7 @@ npx playwright test --config=tests/my.config.js
 
 ### Local configuration
 
-With `test.use()` you can override some options for a file or a `describe` block.
+With `test.use()` you can override some options for a file or a `test.describe` block.
 
 ```js
 // example.spec.js
@@ -80,16 +92,6 @@ test.use({ viewport: { width: 600, height: 900 } });
 test('my portrait test', async ({ page }) => {
   // ...
 });
-
-
-test.describe('headed block', () => {
-  // Run tests in this describe block in headed mode.
-  test.use({ headless: false });
-
-  test('my headed portrait test', async ({ page }) => {
-    // ...
-  });
-});
 ```
 
 ```ts
@@ -102,13 +104,31 @@ test.use({ viewport: { width: 600, height: 900 } });
 test('my portrait test', async ({ page }) => {
   // ...
 });
+```
 
+```js
+// example.spec.js
+const { test, expect } = require('playwright/test');
 
 test.describe('headed block', () => {
   // Run tests in this describe block in headed mode.
   test.use({ headless: false });
 
-  test('my headed portrait test', async ({ page }) => {
+  test('my headed test', async ({ page }) => {
+    // ...
+  });
+});
+```
+
+```ts
+// example.spec.ts
+import { test, expect } from 'playwright/test';
+
+test.describe('headed block', () => {
+  // Run tests in this describe block in headed mode.
+  test.use({ headless: false });
+
+  test('my headed test', async ({ page }) => {
     // ...
   });
 });
@@ -116,7 +136,7 @@ test.describe('headed block', () => {
 
 ## Testing options
 
-In addition to configuring [Browser] or [BrowserContext], videos or screenshots, Playwright Test has many options configuring how your tests are run. Below are the most common ones, see [advanced configuration](./test-advanced.md) for the full list.
+In addition to configuring [Browser] or [BrowserContext], videos or screenshots, Playwright Test has many options to configure how your tests are run. Below are the most common ones, see [advanced configuration](./test-advanced.md) for the full list.
 
 - `forbidOnly`: Whether to exit with an error if any tests are marked as `test.only`. Useful on CI.
 - `globalSetup`: Path to the global setup file. This file will be required and run before all the tests. It must export a single function.
@@ -254,7 +274,7 @@ const config: PlaywrightTestConfig = {
 export default config;
 ```
 
-Playwright Test will run all projects by default, but you can use `--project` command line option to run a single one.
+Playwright Test will run all projects by default.
 
 ```sh
 $ npx playwright test
@@ -266,6 +286,8 @@ Running 3 tests using 3 workers
   ✓ example.spec.ts:3:1 › [WebKit] should work (2s)
 ```
 
+Use `--project` command line option to run a single project.
+
 ```sh
 $ npx playwright test --project=webkit
 
@@ -276,9 +298,9 @@ Running 1 test using 1 worker
 
 There are many more things you can do with projects:
 - Run a subset of test by specifying different `testDir` for each project.
-- Run the same test in multiple configurations, for example with desktop Chromium and emulating Chrome for Android.
-- Running "core" tests without retries to ensure stability of the core functionality, and use `retries` for other tests.
-- And much more!
+- Run tests in multiple configurations, for example with desktop Chromium and emulating Chrome for Android.
+- Run "core" tests without retries to ensure stability of the core functionality, and use `retries` for other tests.
+- And much more! See [advanced configuration](./test-advanced.md) for more details.
 
 :::note
 `--browser` command line option is not compatible with projects. Specify `browserName` in each project instead.

docs/src/test-examples.md

@@ -5,8 +5,6 @@ title: "Examples"
 
 <!-- TOC -->
 
-<br/>
-
 ## Multiple pages
 
 The default `context` argument is a [BrowserContext]. Browser contexts are isolated execution environments that can host multiple pages. See [multi-page scenarios](./multi-pages.md) for more examples.

docs/src/test-fixtures.md

@@ -1,12 +1,10 @@
 ---
 id: test-fixtures
-title: "Fixtures"
+title: "Advanced Fixtures"
 ---
 
 <!-- TOC -->
 
-<br/>
-
 ## Introduction to fixtures
 
 Playwright Test is based on the concept of the test fixtures. Test fixtures are used to establish environment for each test, giving the test everything it needs and nothing else. Test fixtures are isolated between tests, which gives Playwright Test following benefits:

docs/src/test-intro.md

@@ -32,7 +32,7 @@ Create `tests/foo.spec.js` (or `tests/foo.spec.ts` for TypeScript) to define you
 ```js
 const { test, expect } = require('playwright/test');
 
-test('is a basic test with the page', async ({ page }) => {
+test('basic test', async ({ page }) => {
   await page.goto('https://playwright.dev/');
   const name = await page.innerText('.navbar__title');
   expect(name).toBe('Playwright');
@@ -42,38 +42,34 @@ test('is a basic test with the page', async ({ page }) => {
 ```ts
 import { test, expect } from 'playwright/test';
 
-test('is a basic test with the page', async ({ page }) => {
+test('basic test', async ({ page }) => {
   await page.goto('https://playwright.dev/');
   const name = await page.innerText('.navbar__title');
   expect(name).toBe('Playwright');
 });
 ```
 
-Now run your tests:
+Now run your tests, assuming that test files are in the `tests` directory.
 
 ```sh
-# Assuming that test files are in the tests directory.
 npx playwright test -c tests
 ```
 
 Playwright Test just ran a test using Chromium browser, in a headless manner. Let's tell it to use headed browser:
 
 ```sh
-# Assuming that test files are in the tests directory.
 npx playwright test -c tests --headed
 ```
 
 What about other browsers? Let's run the same test using Firefox:
 
 ```sh
-# Assuming that test files are in the tests directory.
 npx playwright test -c tests --browser=firefox
 ```
 
 And finally, on all three browsers:
 
 ```sh
-# Assuming that test files are in the tests directory.
 npx playwright test -c tests --browser=all
 ```
 
@@ -177,6 +173,7 @@ You can use `test.beforeAll` and `test.afterAll` hooks to set up and tear down r
 And you can use `test.beforeEach` and `test.afterEach` hooks to set up and tear down resources for each test individually.
 
 ```js
+// example.spec.js
 const { test, expect } = require('playwright/test');
 
 test.describe('feature foo', () => {
@@ -193,6 +190,7 @@ test.describe('feature foo', () => {
 ```
 
 ```ts
+// example.spec.ts
 import { test, expect } from 'playwright/test';
 
 test.describe('feature foo', () => {
@@ -208,7 +206,111 @@ test.describe('feature foo', () => {
 });
 ```
 
-## Write a configuration file
+### Write assertions
+
+Playwright Test uses [expect](https://jestjs.io/docs/expect) library for test assertions. It provides a lot of matchers like `toEqual`, `toContain`, `toMatch` and many more.
+
+Combine `expect` with various Playwright methods to create expectations for your test:
+- [`method: Page.isVisible`]
+- [`method: Page.waitForSelector`]
+- [`method: Page.textContent`]
+- [`method: Page.getAttribute`]
+- Find out more in the [assertions](./assertions.md) guide
+
+```js
+// example.spec.js
+const { test, expect } = require('playwright/test');
+
+test('my test', async ({ page }) => {
+  await page.goto('https://playwright.dev/');
+
+  // Expect a title "to contain" a substring.
+  expect(await page.title()).toContain('Playwright');
+
+  // Expect an attribute "to be strictly equal" to the value.
+  expect(await page.getAttribute('text=Get Started', 'href')).toBe('/docs/intro');
+
+  // Expect an element "to be visible".
+  expect(await page.isVisible('[aria-label="GitHub repository"]')).toBe(true);
+
+  await page.click('text=Get Started');
+  // Expect some text to be visible on the page.
+  expect(await page.waitForSelector('text=Getting Started')).toBeTruthy();
+});
+```
+
+```ts
+// example.spec.ts
+import { test, expect } from 'playwright/test';
+
+test('my test', async ({ page }) => {
+  await page.goto('https://playwright.dev/');
+
+  // Expect a title "to contain" a substring.
+  expect(await page.title()).toContain('Playwright');
+
+  // Expect an attribute "to be strictly equal" to the value.
+  expect(await page.getAttribute('text=Get Started', 'href')).toBe('/docs/intro');
+
+  // Expect an element "to be visible".
+  expect(await page.isVisible('[aria-label="GitHub repository"]')).toBe(true);
+
+  await page.click('text=Get Started');
+  // Expect some text to be visible on the page.
+  expect(await page.waitForSelector('text=Getting Started')).toBeTruthy();
+});
+```
+
+## Learn the command line
+
+Here are the most common options available in the [command line](./test-cli.md).
+
+- Run tests in headed browsers
+  ```sh
+  npx playwright test --headed
+  ```
+
+- Run tests in a particular browser
+  ```sh
+  npx playwright test --browser=webkit
+  ```
+
+- Run tests in all browsers
+  ```sh
+  npx playwright test --browser=all
+  ```
+
+- Run a single test file
+  ```sh
+  npx playwright test tests/todo-page.spec.ts
+  ```
+
+- Run a set of test files
+  ```sh
+  npx playwright test tests/todo-page/ tests/landing-page/
+  ```
+
+- Run a test with specific title
+  ```sh
+  npx playwright test -g "add a todo item"
+  ```
+
+- Run tests [in parallel](./test-parallel.md) - that's the default
+  ```sh
+  npx playwright test
+  ```
+
+- Disable [parallelization](./test-parallel.md)
+  ```sh
+  npx playwright test --workers=1
+  ```
+
+- Choose a [reporter](./test-reporters.md)
+  ```sh
+  npx playwright test --reporter=dot
+  ```
+
+## Create 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/test-parallel.md

@@ -7,15 +7,50 @@ Playwright Test runs tests in parallel by default, using multiple worker process
 
 <!-- TOC -->
 
-<br/>
-
 ## Workers
 
-Each worker process creates a new environment to run tests. Different projects always run in different workers. By default, runner reuses the worker as much as it can to make testing faster, but it will create a new worker when retrying tests, after any test failure, to initialize a new environment, or just to speed up test execution if the worker limit is not reached.
+Each worker process creates a new environment to run tests. By default, Playwright Test reuses the worker as much as it can to make testing faster.
 
-The maximum number of worker processes is controlled via [command line](#command-line) or [configuration object](#configuration-object).
+However, test runner will create a new worker when retrying tests, after any test failure, to initialize a new environment, or just to speed up test execution if the worker limit is not reached.
 
-Each worker process is assigned a unique sequential index that is accessible through [`workerInfo`](#workerinfo) object.
+You can control the maximum number of worker processes via [command line](./test-cli.md) or in the [configuration file](./test-configuration.md).
+
+- Run in parallel by default
+  ```sh
+  npx playwright test
+  ```
+
+- Disable parallelization
+  ```sh
+  npx playwright test --worker 1
+  ```
+
+- Control the number of workers
+  ```sh
+  npx playwright test --worker 4
+  ```
+
+- In the configuration file
+  ```js
+  // playwright.config.js
+  module.exports = {
+    // Limit the number of workers on CI, use default locally
+    workers: process.env.CI ? 2 : undefined,
+  };
+  ```
+
+  ```ts
+  // playwright.config.ts
+  import { PlaywrightTestConfig } from 'playwright/test';
+
+  const config: PlaywrightTestConfig = {
+    // Limit the number of workers on CI, use default locally
+    workers: process.env.CI ? 2 : undefined,
+  };
+  export default config;
+  ```
+
+Each worker process is assigned a unique sequential index that is accessible through the [`workerInfo`](./test-advanced.md#workerinfo) object.
 
 ## Shards
 

docs/src/test-reporters.md

@@ -5,8 +5,6 @@ title: "Reporters"
 
 <!-- TOC -->
 
-<br/>
-
 ## Using reporters
 
 Playwright Test comes with a few built-in reporters for different needs and ability to provide custom reporters. The easiest way to try out built-in reporters is to pass `--reporter` [command line option](./cli.md).

docs/src/test-retries.md

@@ -9,7 +9,24 @@ Playwright Test will retry tests if they failed. Pass the maximum number of retr
 npx playwright test --retries=3
 ```
 
-Failing tests will be retried multiple times until they pass, or until the maximum number of retries is reached. Playwright Test will report all tests that failed at least once:
+```js
+// playwright.config.js
+module.exports = {
+  retries: 3,
+};
+```
+
+```ts
+// playwright.config.ts
+import { PlaywrightTestConfig } from 'playwright/test';
+
+const config: PlaywrightTestConfig = {
+  retries: 3,
+};
+export default config;
+```
+
+Failing tests will be retried multiple times until they pass, or until the maximum number of retries is reached. Playwright Test will report all tests that failed at least once.
 
 ```sh
 Running 1 test using 1 worker