diff --git a/docs/src/intro-js.md b/docs/src/intro-js.md
index 7b20ac7cce..b3402fde49 100644
--- a/docs/src/intro-js.md
+++ b/docs/src/intro-js.md
@@ -3,120 +3,480 @@ id: intro
title: "Getting Started"
---
+Playwright can either be used as a part of the [Playwright Test](./intro.md), or as a [Playwright Library](./library.md).
+
+Playwright Test was created specifically to accommodate the needs of the end-to-end testing. It does everything you would expect from the regular test runner, and more. Playwright test allows to:
+
+- Run tests across all browsers.
+- Execute tests in parallel.
+- Enjoy context isolation out of the box.
+- Capture videos, screenshots and other artifacts on failure.
+- Integrate your POMs as extensible fixtures.
+
+
+
- [Release notes](./release-notes.md)
+
+
## Installation
-Use npm or Yarn to install Playwright in your Node.js project. See [system requirements](#system-requirements).
+Playwright has its own test runner for end-to-end tests, we call it Playwright Test.
```bash
-npm i -D playwright
+npm i -D @playwright/test
```
-This single command downloads the Playwright NPM package and browser binaries for Chromium, Firefox and WebKit. To modify this behavior see [installation parameters](./installation.md).
-
-## Usage
-
-Once installed, you can `require` Playwright in a Node.js script, and launch any of the 3 browsers (`chromium`, `firefox` and `webkit`).
-
-```js
-const { chromium } = require('playwright');
-
-(async () => {
- const browser = await chromium.launch();
- // Create pages, interact with UI elements, assert values
- await browser.close();
-})();
-```
-
-Playwright APIs are asynchronous and return Promise objects. Our code examples use [the async/await pattern](https://developer.mozilla.org/en-US/docs/Learn/JavaScript/Asynchronous/Async_await) to ease readability. The code is wrapped in an unnamed async arrow function which is invoking itself.
-
-```js
-(async () => { // Start of async arrow function
- // Function code
- // ...
-})(); // End of the function and () to invoke itself
-```
-
-## First script
-
-In our first script, we will navigate to `whatsmyuseragent.org` and take a screenshot in WebKit.
-
-```js
-const { webkit } = require('playwright');
-
-(async () => {
- const browser = await webkit.launch();
- const page = await browser.newPage();
- await page.goto('http://whatsmyuseragent.org/');
- await page.screenshot({ path: `example.png` });
- await browser.close();
-})();
-```
-
-By default, Playwright runs the browsers in headless mode. To see the browser UI, pass the `headless: false` flag while launching the browser. You can also use `slowMo` to slow down execution. Learn more in the debugging tools [section](./debug.md).
-
-```js
-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.
-
-```bash
-npx playwright codegen wikipedia.org
-```
-
-## TypeScript support
-
-Playwright includes built-in support for TypeScript. Type definitions will be imported automatically. It is recommended to use type-checking to improve the IDE experience.
-
-### In JavaScript
-Add the following to the top of your JavaScript file to get type-checking in VS Code or WebStorm.
-
-```js
-//@ts-check
-// ...
-```
-
-Alternatively, you can use JSDoc to set types for variables.
-
-```js
-/** @type {import('playwright').Page} */
-let page;
-```
-
-### In TypeScript
-TypeScript support will work out-of-the-box. Types can also be imported explicitly.
-
-```js
-let page: import('playwright').Page;
-```
-
-## System requirements
-
-Playwright requires Node.js version 12 or above. The browser binaries for Chromium,
-Firefox and WebKit work across the 3 platforms (Windows, macOS, Linux):
-
-### Windows
-
-Works with Windows and Windows Subsystem for Linux (WSL).
-
-### macOS
-
-Requires 10.14 (Mojave) or above.
-
-### Linux
-
-Depending on your Linux distribution, you might need to install additional
-dependencies to run the browsers.
-
:::note
-Only Ubuntu 18.04 and Ubuntu 20.04 are officially supported.
+Playwright Test is self-contained, it does not need Playwright to be installed.
+If you are an existing Playwright user, make sure that you either uninstall
+Playwright or update Playwright before installing Playwright Test:
+
+```
+npm i -D playwright @playwright/test
+```
:::
-See also in the [Command Line Interface](./cli.md#install-system-dependencies)
-which has a command to install all necessary dependencies automatically for Ubuntu
-LTS releases.
+
+Unlike Playwright, Playwright Test does not bundle browsers by default, so you need to install them explicitly:
+
+```bash
+npx playwright install
+```
+
+You can optionally install only selected browsers, see [Playwright CLI](./cli.md) for more details. Or you can install no browsers at all and use existing [browser channels](./browsers.md).
+
+## First test
+
+Create `tests/foo.spec.js` (or `tests/foo.spec.ts` for TypeScript) to define your test.
+
+```js js-flavor=js
+const { test, expect } = require('@playwright/test');
+
+test('basic test', async ({ page }) => {
+ await page.goto('https://playwright.dev/');
+ const name = await page.innerText('.navbar__title');
+ expect(name).toBe('Playwright');
+});
+```
+
+```js js-flavor=ts
+import { test, expect } from '@playwright/test';
+
+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, assuming that test files are in the `tests` directory.
+
+```bash
+npx playwright test
+```
+
+Playwright Test just ran a test using Chromium browser, in a headless manner. Let's tell it to use headed browser:
+
+```bash
+npx playwright test --headed
+```
+
+What about other browsers? Let's run the same test using Firefox:
+
+```bash
+npx playwright test --browser=firefox
+```
+
+And finally, on all three browsers:
+
+```bash
+npx playwright test --browser=all
+```
+
+Refer to [configuration](./test-configuration.md) section for configuring test runs in different modes with different browsers.
+
+## Test fixtures
+
+You noticed an argument `{ page }` that the test above has access to:
+
+```js js-flavor=js
+test('basic test', async ({ page }) => {
+ ...
+```
+
+```js js-flavor=ts
+test('basic test', async ({ page }) => {
+ ...
+```
+
+We call these arguments `fixtures`. Fixtures are objects that are created for each test run. Playwright Test comes loaded with those fixtures, and you can add your own fixtures as well. When running tests, Playwright Test looks at each test declaration, analyses the set of fixtures the test needs and prepares those fixtures specifically for the test.
+
+Here is a list of the pre-defined fixtures that you are likely to use most of the time:
+
+|Fixture |Type |Description |
+|:----------|:----------------|:--------------------------------|
+|page |[Page] |Isolated page for this test run. |
+|context |[BrowserContext] |Isolated context for this test run. The `page` fixture belongs to this context as well. Learn how to [configure context](./test-configuration.md). |
+|browser |[Browser] |Browsers are shared across tests to optimize resources. Learn how to [configure browser](./test-configuration.md). |
+|browserName|[string] |The name of the browser currently running the test. Either `chromium`, `firefox` or `webkit`.|
+
+## Test and assertion features
+
+If you are familiar with test runners like Jest, Mocha and Ava, you will find the Playwright Test syntax familiar. These are the basic things you can do with the test:
+
+### Focus a test
+
+You can focus some tests. When there are focused tests, only they run.
+
+```js js-flavor=js
+test.only('focus this test', async ({ page }) => {
+ // Run only focused tests in the entire project.
+});
+```
+
+```js js-flavor=ts
+test.only('focus this test', async ({ page }) => {
+ // Run only focused tests in the entire project.
+});
+```
+
+### Skip a test
+
+You can skip certain test based on the condition.
+
+```js js-flavor=js
+test('skip this test', async ({ page, browserName }) => {
+ test.skip(browserName === 'firefox', 'Still working on it');
+});
+```
+
+```js js-flavor=ts
+test('skip this test', async ({ page, browserName }) => {
+ test.skip(browserName === 'firefox', 'Still working on it');
+});
+```
+
+### Group tests
+
+You can group tests to give them a logical name or to scope before/after hooks to the group.
+```js js-flavor=js
+const { test, expect } = require('@playwright/test');
+
+test.describe('two tests', () => {
+ test('one', async ({ page }) => {
+ // ...
+ });
+
+ test('two', async ({ page }) => {
+ // ...
+ });
+});
+```
+
+```js js-flavor=ts
+import { test, expect } from '@playwright/test';
+
+test.describe('two tests', () => {
+ test('one', async ({ page }) => {
+ // ...
+ });
+
+ test('two', async ({ page }) => {
+ // ...
+ });
+});
+```
+
+### Use test hooks
+
+You can use `test.beforeAll` and `test.afterAll` hooks to set up and tear down resources shared between tests.
+And you can use `test.beforeEach` and `test.afterEach` hooks to set up and tear down resources for each test individually.
+
+```js js-flavor=js
+// example.spec.js
+const { test, expect } = require('@playwright/test');
+
+test.describe('feature foo', () => {
+ test.beforeEach(async ({ page }) => {
+ // Go to the starting url before each test.
+ await page.goto('https://my.start.url/');
+ });
+
+ test('my test', async ({ page }) => {
+ // Assertions use the expect API.
+ expect(page.url()).toBe('https://my.start.url/');
+ });
+});
+```
+
+```js js-flavor=ts
+// example.spec.ts
+import { test, expect } from '@playwright/test';
+
+test.describe('feature foo', () => {
+ test.beforeEach(async ({ page }) => {
+ // Go to the starting url before each test.
+ await page.goto('https://my.start.url/');
+ });
+
+ test('my test', async ({ page }) => {
+ // Assertions use the expect API.
+ expect(page.url()).toBe('https://my.start.url/');
+ });
+});
+```
+
+### 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`, `toMatchSnapshot` 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`]
+- [`method: Page.screenshot`]
+- Find out more in the [assertions](./assertions.md) guide
+
+```js js-flavor=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('text=Learn more')).toBeTruthy();
+
+ await page.click('text=Get Started');
+ // Expect some text to be visible on the page.
+ expect(await page.waitForSelector('text=System requirements')).toBeTruthy();
+
+ // Compare screenshot with a stored reference.
+ expect(await page.screenshot()).toMatchSnapshot('get-started.png');
+});
+```
+
+```js js-flavor=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');
+
+ await page.click('text=Get Started');
+ // Expect some text to be visible on the page.
+ expect(await page.waitForSelector('text=System requirements')).toBeTruthy();
+
+ // Compare screenshot with a stored reference.
+ expect(await page.screenshot()).toMatchSnapshot('get-started.png');
+});
+```
+
+Notice how running this test is saying:
+
+```
+Error: example.spec.ts-snapshots/get-started-chromium-darwin.png is missing in snapshots, writing actual.
+```
+
+That's because there was no golden file for your `get-started.png` snapshot. It is now created and is ready to be added to the repository. The name of the folder with the golden expectations starts with the name of your test file:
+
+```bash
+drwxr-xr-x 5 user group 160 Jun 4 11:46 .
+drwxr-xr-x 6 user group 192 Jun 4 11:45 ..
+-rw-r--r-- 1 user group 231 Jun 4 11:16 example.spec.ts
+drwxr-xr-x 3 user group 96 Jun 4 11:46 example.spec.ts-snapshots
+```
+
+To update your golden files, you can use the `--update-snapshots` parameter.
+
+```bash
+npx playwright test --update-snapshots
+```
+
+
+## Learn the command line
+
+Here are the most common options available in the [command line](./test-cli.md).
+
+- Run tests in headed browsers
+ ```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
+ ```
+
+- 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 a test with specific title
+ ```bash
+ npx playwright test -g "add a todo item"
+ ```
+
+- Run tests [in parallel](./test-parallel.md) - that's the default
+ ```bash
+ npx playwright test
+ ```
+
+- 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
+ ```
+
+## 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.
+
+Create `playwright.config.ts` (or `playwright.config.js`) to configure your tests. You can specify browser launch options, run tests in multiple browsers and much more with the config. Here is an example configuration that runs every test in Chromium, Firefox and WebKit, both Desktop and Mobile versions. Look for more options in the [configuration section](./test-configuration.md).
+
+```js js-flavor=js
+// playwright.config.js
+const { devices } = require('@playwright/test');
+
+module.exports = {
+ projects: [
+ {
+ name: 'Desktop Chromium',
+ use: {
+ browserName: 'chromium',
+ // Test against Chrome Beta channel.
+ channel: 'chrome-beta',
+ },
+ },
+ {
+ name: 'Desktop Safari',
+ use: {
+ browserName: 'webkit',
+ viewport: { width: 1200, height: 750 },
+ }
+ },
+ // Test against mobile viewports.
+ {
+ name: 'Mobile Chrome',
+ use: devices['Pixel 5'],
+ },
+ {
+ name: 'Mobile Safari',
+ use: devices['iPhone 12'],
+ },
+ {
+ name: 'Desktop Firefox',
+ use: {
+ browserName: 'firefox',
+ viewport: { width: 800, height: 600 },
+ }
+ },
+ ],
+};
+```
+
+```js js-flavor=ts
+// playwright.config.ts
+import { PlaywrightTestConfig, devices } from '@playwright/test';
+
+const config: PlaywrightTestConfig = {
+ projects: [
+ {
+ name: 'Chrome Stable',
+ use: {
+ browserName: 'chromium',
+ // Test against Chrome Stable channel.
+ channel: 'chrome',
+ },
+ },
+ {
+ name: 'Desktop Safari',
+ use: {
+ browserName: 'webkit',
+ viewport: { width: 1200, height: 750 },
+ }
+ },
+ // Test against mobile viewports.
+ {
+ name: 'Mobile Chrome',
+ use: devices['Pixel 5'],
+ },
+ {
+ name: 'Mobile Safari',
+ use: devices['iPhone 12'],
+ },
+ {
+ name: 'Desktop Firefox',
+ use: {
+ browserName: 'firefox',
+ viewport: { width: 800, height: 600 },
+ }
+ },
+ ],
+};
+export default config;
+```
+
+Configure NPM script to run tests. Test runner will automatically pick up `playwright.config.js` or `playwright.config.ts`.
+
+```json
+{
+ "scripts": {
+ "test": "npx playwright test"
+ }
+}
+```
+
+If you put your configuration file in a different place, pass it with `--config` option.
+
+```json
+{
+ "scripts": {
+ "test": "npx playwright test --config=tests/example.config.js"
+ }
+}
+```
diff --git a/docs/src/library.md b/docs/src/library.md
new file mode 100644
index 0000000000..1e90e0692d
--- /dev/null
+++ b/docs/src/library.md
@@ -0,0 +1,124 @@
+---
+id: library
+title: "Playwright Library"
+---
+
+Playwright can either be used as a part of the [Playwright Test](./intro.md), or as a standalone library. If you are working on an application that utilizes Playwright capabilities or you are using Playwright with another test runner, read on.
+
+
+- [Release notes](./release-notes.md)
+
+## Installation
+
+Use npm or Yarn to install Playwright library in your Node.js project. See [system requirements](#system-requirements).
+
+```bash
+npm i -D playwright
+```
+
+This single command downloads the Playwright NPM package and browser binaries for Chromium, Firefox and WebKit. To modify this behavior see [installation parameters](./installation.md).
+
+## Usage
+
+Once installed, you can `require` Playwright in a Node.js script, and launch any of the 3 browsers (`chromium`, `firefox` and `webkit`).
+
+```js
+const { chromium } = require('playwright');
+
+(async () => {
+ const browser = await chromium.launch();
+ // Create pages, interact with UI elements, assert values
+ await browser.close();
+})();
+```
+
+Playwright APIs are asynchronous and return Promise objects. Our code examples use [the async/await pattern](https://developer.mozilla.org/en-US/docs/Learn/JavaScript/Asynchronous/Async_await) to ease readability. The code is wrapped in an unnamed async arrow function which is invoking itself.
+
+```js
+(async () => { // Start of async arrow function
+ // Function code
+ // ...
+})(); // End of the function and () to invoke itself
+```
+
+## First script
+
+In our first script, we will navigate to `whatsmyuseragent.org` and take a screenshot in WebKit.
+
+```js
+const { webkit } = require('playwright');
+
+(async () => {
+ const browser = await webkit.launch();
+ const page = await browser.newPage();
+ await page.goto('http://whatsmyuseragent.org/');
+ await page.screenshot({ path: `example.png` });
+ await browser.close();
+})();
+```
+
+By default, Playwright runs the browsers in headless mode. To see the browser UI, pass the `headless: false` flag while launching the browser. You can also use `slowMo` to slow down execution. Learn more in the debugging tools [section](./debug.md).
+
+```js
+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.
+
+```bash
+npx playwright codegen wikipedia.org
+```
+
+## TypeScript support
+
+Playwright includes built-in support for TypeScript. Type definitions will be imported automatically. It is recommended to use type-checking to improve the IDE experience.
+
+### In JavaScript
+Add the following to the top of your JavaScript file to get type-checking in VS Code or WebStorm.
+
+```js
+//@ts-check
+// ...
+```
+
+Alternatively, you can use JSDoc to set types for variables.
+
+```js
+/** @type {import('playwright').Page} */
+let page;
+```
+
+### In TypeScript
+TypeScript support will work out-of-the-box. Types can also be imported explicitly.
+
+```js
+let page: import('playwright').Page;
+```
+
+## System requirements
+
+Playwright requires Node.js version 12 or above. The browser binaries for Chromium,
+Firefox and WebKit work across the 3 platforms (Windows, macOS, Linux):
+
+### Windows
+
+Works with Windows and Windows Subsystem for Linux (WSL).
+
+### macOS
+
+Requires 10.14 (Mojave) or above.
+
+### Linux
+
+Depending on your Linux distribution, you might need to install additional
+dependencies to run the browsers.
+
+:::note
+Only Ubuntu 18.04 and Ubuntu 20.04 are officially supported.
+:::
+
+See also in the [Command Line Interface](./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-intro.md b/docs/src/test-intro.md
index 98cf7d1590..158a886929 100644
--- a/docs/src/test-intro.md
+++ b/docs/src/test-intro.md
@@ -1,9 +1,9 @@
---
id: test-intro
-title: "Introduction"
+title: "Getting Started"
---
-Playwright Test Runner was created specifically to accommodate the needs of the end-to-end testing. It does everything you would expect from the regular test runner, and more. Playwright test allows to:
+Playwright Test was created specifically to accommodate the needs of the end-to-end testing. It does everything you would expect from the regular test runner, and more. Playwright test allows to:
- Run tests across all browsers.
- Execute tests in parallel.
@@ -13,30 +13,20 @@ Playwright Test Runner was created specifically to accommodate the needs of the
+### Contents
## Installation
-Playwright has its own test runner for end-to-end tests, we call it Playwright Test.
-
```bash
npm i -D @playwright/test
```
-:::note
-Playwright Test is self-contained, it does not need Playwright to be installed.
-If you are an existing Playwright user, make sure that you either uninstall
-Playwright or update Playwright before installing Playwright Test:
+Playwright Test is self-contained solution, it does not need Playwright [library](./library.md) to be installed. If you are an existing Playwright library user, make sure that you either uninstall it or update it prior to installing Playwright Test.
-```
-npm i -D playwright @playwright/test
-```
-:::
-
-
-Unlike Playwright, Playwright Test does not bundle browsers by default, so you need to install them explicitly:
+Unlike Playwright [library](./library.md), Playwright Test does not download browsers by default, so you need to install them explicitly:
```bash
npx playwright install
diff --git a/packages/build_package.js b/packages/build_package.js
index e22057e700..2f765d8935 100755
--- a/packages/build_package.js
+++ b/packages/build_package.js
@@ -43,7 +43,7 @@ const PACKAGES = {
files: PLAYWRIGHT_CORE_FILES,
},
'playwright-test': {
- description: 'Playwright Test Runner',
+ description: 'Playwright Test',
browsers: ['chromium', 'firefox', 'webkit', 'ffmpeg'],
files: PLAYWRIGHT_CORE_FILES,
name: '@playwright/test',
diff --git a/packages/playwright-test/README.md b/packages/playwright-test/README.md
index c9f2d8d314..71d411e0ba 100644
--- a/packages/playwright-test/README.md
+++ b/packages/playwright-test/README.md
@@ -1,3 +1,3 @@
# @playwright/test
-This package contains [Playwright Test Runner](https://playwright.dev/docs/test-intro).
+This package contains [Playwright Test](https://playwright.dev/docs/test-intro).