docs: new getting started stucture (#15624)
Co-authored-by: Max Schmitt <max@schmitt.mx>
This commit is contained in:
Debbie O'Brien
GitHub
parent
f87d2d7c5b
commit
2b8198f1e3
|
|
@ -3,11 +3,7 @@ id: codegen
|
|||
title: "Test Generator"
|
||||
---
|
||||
|
||||
Playwright comes with the ability to generate tests out of the box.
|
||||
|
||||
<!-- TOC -->
|
||||
|
||||
## Generate tests
|
||||
Playwright comes with the ability to generate tests out of the box and is a great way to quickly get started with testing. It will open two windows, a browser window where you interact with the website you wish to test and the Playwright Inspector window where you can record your tests, copy the tests, clear your tests as well as change the language of your tests.
|
||||
|
||||
```bash js
|
||||
npx playwright codegen wikipedia.org
|
||||
|
|
@ -27,7 +23,7 @@ pwsh bin\Debug\netX\playwright.ps1 codegen wikipedia.org
|
|||
|
||||
Run `codegen` and perform actions in the browser. Playwright will generate the code for the user interactions. `codegen` will attempt to generate resilient text-based selectors.
|
||||
|
||||
<img src="https://user-images.githubusercontent.com/284612/92536033-7e7ebe00-f1ed-11ea-9e1a-7cbd912e3391.gif"></img>
|
||||
<img width="1916" alt="image" src="https://user-images.githubusercontent.com/13063165/177550119-4e202a56-7d8e-43ac-ad91-bf2f7b2579bd.png"/>
|
||||
|
||||
## Preserve authenticated state
|
||||
|
||||
|
|
|
|||
|
|
@ -1,108 +1,102 @@
|
|||
---
|
||||
id: debug
|
||||
title: "Debugging tools"
|
||||
title: "Debugging Tests"
|
||||
---
|
||||
|
||||
Playwright scripts work with existing debugging tools, like Node.js debuggers
|
||||
and browser developer tools. Playwright also introduces new debugging features
|
||||
for browser automation.
|
||||
The Playwright inspector is a great tool to help with debugging. It opens up a browser window highlighting the selectors as you step through each line of the test. You can also use the explore button to find other available [selectors](./selectors.md) which you can then copy into your test file and rerun your tests to see if it passes.
|
||||
|
||||
<!-- TOC -->
|
||||
|
||||
## Playwright Inspector
|
||||
|
||||
[Playwright Inspector](./inspector.md) is a GUI tool that helps authoring and debugging Playwright scripts. That's our default recommended tool for scripts troubleshooting.
|
||||
Playwright Inspector is a GUI tool that helps authoring and debugging Playwright scripts. That's our default recommended tool for scripts troubleshooting.
|
||||
|
||||
<img width="712" alt="Playwright Inspector" src="https://user-images.githubusercontent.com/883973/108614092-8c478a80-73ac-11eb-9597-67dfce110e00.png"></img>
|
||||
|
||||
There are several ways of opening Playwright Inspector:
|
||||
|
||||
## Playwright Trace Viewer
|
||||
### Using --debug
|
||||
* langs: js
|
||||
|
||||
[Playwright Trace Viewer](./trace-viewer.md) is a GUI tool that helps troubleshooting test runs in a post-mortem manner.
|
||||
- Debugging all Tests
|
||||
|
||||
<img width="1212" alt="Playwright Trace Viewer" src="https://user-images.githubusercontent.com/883973/120585896-6a1bca80-c3e7-11eb-951a-bd84002480f5.png"></img>
|
||||
```bash
|
||||
npx playwright test --debug
|
||||
```
|
||||
- Debugging one test
|
||||
|
||||
## Run in headed mode
|
||||
```bash
|
||||
npx playwright test example --debug
|
||||
```
|
||||
|
||||
Playwright runs browsers in headless mode by default. To change this behavior,
|
||||
use `headless: false` as a launch option. You can also use the [`option: slowMo`] option
|
||||
to slow down execution and follow along while debugging.
|
||||
### Using PWDEBUG
|
||||
|
||||
```js
|
||||
await chromium.launch({ headless: false, slowMo: 100 }); // or firefox, webkit
|
||||
```
|
||||
Set the `PWDEBUG` environment variable to run your scripts in debug mode. This
|
||||
configures Playwright for debugging and opens the inspector.
|
||||
|
||||
```java
|
||||
chromium.launch(new BrowserType.LaunchOptions() // or firefox, webkit
|
||||
.setHeadless(false)
|
||||
.setSlowMo(100));
|
||||
```
|
||||
```bash tab=bash-bash lang=js
|
||||
PWDEBUG=1 npm run test
|
||||
```
|
||||
|
||||
```python async
|
||||
await chromium.launch(headless=False, slow_mo=100) # or firefox, webkit
|
||||
```batch tab=bash-batch lang=js
|
||||
set PWDEBUG=1
|
||||
npm run test
|
||||
```
|
||||
|
||||
```
|
||||
```powershell tab=bash-powershell lang=js
|
||||
$env:PWDEBUG=1
|
||||
npm run test
|
||||
```
|
||||
|
||||
```python sync
|
||||
chromium.launch(headless=False, slow_mo=100) # or firefox, webkit
|
||||
```bash tab=bash-bash lang=java
|
||||
# Source directories in the list are separated by : on macos and linux and by ; on win.
|
||||
PWDEBUG=1 PLAYWRIGHT_JAVA_SRC=<java source dirs> mvn test
|
||||
```
|
||||
|
||||
```
|
||||
```batch tab=bash-batch lang=java
|
||||
# Source directories in the list are separated by : on macos and linux and by ; on win.
|
||||
set PLAYWRIGHT_JAVA_SRC=<java source dirs>
|
||||
set PWDEBUG=1
|
||||
mvn test
|
||||
```
|
||||
|
||||
```csharp
|
||||
// Chromium, Firefox, or Webkit
|
||||
await using var browser = await playwright.Chromium.LaunchAsync(new()
|
||||
{
|
||||
Headless = false,
|
||||
SlowMo = 100
|
||||
});
|
||||
```
|
||||
```powershell tab=bash-powershell lang=java
|
||||
# Source directories in the list are separated by : on macos and linux and by ; on win.
|
||||
$env:PLAYWRIGHT_JAVA_SRC="<java source dirs>"
|
||||
$env:PWDEBUG=1
|
||||
mvn test
|
||||
```
|
||||
|
||||
## Browser Developer Tools
|
||||
```bash tab=bash-bash lang=python
|
||||
PWDEBUG=1 pytest -s
|
||||
```
|
||||
|
||||
You can use browser developer tools in Chromium, Firefox and WebKit while running
|
||||
a Playwright script in headed mode. Developer tools help to:
|
||||
```batch tab=bash-batch lang=python
|
||||
set PWDEBUG=1
|
||||
pytest -s
|
||||
```
|
||||
|
||||
* Inspect the DOM tree and **find element selectors**
|
||||
* **See console logs** during execution (or learn how to [read logs via API](./api/class-page.md#page-event-console))
|
||||
* Check **network activity** and other developer tools features
|
||||
```powershell tab=bash-powershell lang=python
|
||||
$env:PWDEBUG=1
|
||||
pytest -s
|
||||
```
|
||||
|
||||
<a href="https://user-images.githubusercontent.com/284612/77234134-5f21a500-6b69-11ea-92ec-1c146e1333ec.png"><img src="https://user-images.githubusercontent.com/284612/77234134-5f21a500-6b69-11ea-92ec-1c146e1333ec.png" width="500" alt="Chromium Developer Tools"></img></a>
|
||||
```bash tab=bash-bash lang=csharp
|
||||
PWDEBUG=1 dotnet test
|
||||
```
|
||||
|
||||
Using a [`method: Page.pause`] method is an easy way to pause the Playwright script execution
|
||||
and inspect the page in Developer tools. It will also open [Playwright Inspector](./inspector.md) to help with debugging.
|
||||
```batch tab=bash-batch lang=csharp
|
||||
set PWDEBUG=1
|
||||
dotnet test
|
||||
```
|
||||
|
||||
**For Chromium**: you can also open developer tools through a launch option.
|
||||
```js
|
||||
await chromium.launch({ devtools: true });
|
||||
```
|
||||
```powershell tab=bash-powershell lang=csharp
|
||||
$env:PWDEBUG=1
|
||||
dotnet test
|
||||
```
|
||||
|
||||
```java
|
||||
chromium.launch(new BrowserType.LaunchOptions().setDevtools(true));
|
||||
```
|
||||
|
||||
```python async
|
||||
await chromium.launch(devtools=True)
|
||||
```
|
||||
|
||||
```python sync
|
||||
chromium.launch(devtools=True)
|
||||
```
|
||||
|
||||
```csharp
|
||||
await using var browser = await playwright.Chromium.LaunchAsync(new()
|
||||
{
|
||||
Devtools: true
|
||||
});
|
||||
```
|
||||
|
||||
:::note
|
||||
**For WebKit**: launching WebKit Inspector during the execution will
|
||||
prevent the Playwright script from executing any further.
|
||||
:::
|
||||
|
||||
## Run in Debug Mode
|
||||
|
||||
Set the `PWDEBUG` environment variable to run your scripts in debug mode. Using `PWDEBUG=1` will open [Playwright Inspector](./inspector.md).
|
||||
Additional useful defaults are configured when `PWDEBUG=1` is set:
|
||||
- Browsers launch in the headed mode
|
||||
- Default timeout is set to 0 (= no timeout)
|
||||
|
||||
Using `PWDEBUG=console` will configure the browser for debugging in Developer tools console:
|
||||
* **Runs headed**: Browsers always launch in headed mode
|
||||
|
|
@ -153,7 +147,7 @@ $env:PWDEBUG="console"
|
|||
pytest -s
|
||||
```
|
||||
|
||||
## Selectors in Developer Tools Console
|
||||
#### Selectors in Developer Tools Console
|
||||
|
||||
When running in Debug Mode with `PWDEBUG=console`, a `playwright` object is available in Developer tools console.
|
||||
|
||||
|
|
@ -172,23 +166,228 @@ When running in Debug Mode with `PWDEBUG=console`, a `playwright` object is avai
|
|||
|
||||
<a href="https://user-images.githubusercontent.com/284612/86857345-299abc00-c073-11ea-9e31-02923a9f0d4b.png"><img src="https://user-images.githubusercontent.com/284612/86857345-299abc00-c073-11ea-9e31-02923a9f0d4b.png" width="500" alt="Highlight selectors"></img></a>
|
||||
|
||||
## Visual Studio Code debugger (Node.js)
|
||||
|
||||
The VS Code debugger can be used to pause and resume execution of Playwright
|
||||
scripts with breakpoints. The debugger can be configured in two ways.
|
||||
### Using page.pause
|
||||
|
||||
### Use launch config
|
||||
Call [`method: Page.pause`] method from your script when running in headed browser.
|
||||
|
||||
Setup [`launch.json` configuration](https://code.visualstudio.com/docs/nodejs/nodejs-debugging)
|
||||
for your Node.js project. Once configured launch the scripts with F5 and use
|
||||
breakpoints.
|
||||
```js
|
||||
// Pause on the following line.
|
||||
await page.pause();
|
||||
```
|
||||
|
||||
### Use the JavaScript Debug Terminal
|
||||
```java
|
||||
// Pause on the following line.
|
||||
page.pause();
|
||||
```
|
||||
|
||||
1. Open [JavaScript Debug Terminal](https://code.visualstudio.com/docs/nodejs/nodejs-debugging#_javascript-debug-terminal)
|
||||
1. Set a breakpoint in VS Code
|
||||
* Use the `debugger` keyword or set a breakpoint in the VS Code UI
|
||||
1. Run your Node.js script from the terminal
|
||||
```python async
|
||||
# Pause on the following line.
|
||||
await page.pause()
|
||||
```
|
||||
|
||||
```python sync
|
||||
# Pause on the following line.
|
||||
page.pause()
|
||||
```
|
||||
|
||||
```csharp
|
||||
// Pause on the following line.
|
||||
await page.PauseAsync();
|
||||
```
|
||||
|
||||
|
||||
- Use `open` or `codegen` commands in the Playwright [CLI](./cli.md):
|
||||
```bash js
|
||||
npx playwright codegen wikipedia.org
|
||||
```
|
||||
|
||||
```bash java
|
||||
mvn exec:java -e -Dexec.mainClass=com.microsoft.playwright.CLI -Dexec.args="codegen wikipedia.org"
|
||||
```
|
||||
|
||||
```bash python
|
||||
playwright codegen wikipedia.org
|
||||
```
|
||||
|
||||
```bash csharp
|
||||
pwsh bin\Debug\netX\playwright.ps1 codegen wikipedia.org
|
||||
```
|
||||
|
||||
## Stepping through the Playwright script
|
||||
|
||||
When `PWDEBUG=1` is set, Playwright Inspector window will be opened and the script will be
|
||||
paused on the first Playwright statement:
|
||||
|
||||
<img width="557" alt="Paused on line" src="https://user-images.githubusercontent.com/883973/108614337-71761580-73ae-11eb-9f61-3d29c52c9520.png"></img>
|
||||
|
||||
Now we know what action is about to be performed and we can look into the details on that
|
||||
action. For example, when stopped on an input action such as `click`, the exact point Playwright is about to click is highlighted with the large red dot on the inspected page:
|
||||
|
||||
<img width="344" alt="Red dot on inspected page" src="https://user-images.githubusercontent.com/883973/108614363-b69a4780-73ae-11eb-8f5e-51f9c91ec9b4.png"></img>
|
||||
|
||||
By the time Playwright has paused on that click action, it has already performed actionability checks that can be found in the log:
|
||||
|
||||
<img width="712" alt="Action log" src="https://user-images.githubusercontent.com/883973/108614564-72a84200-73b0-11eb-9de2-828b28d78b36.png"></img>
|
||||
|
||||
If actionability can't be reached, it'll show action as pending:
|
||||
|
||||
<img width="712" alt="Pending action" src="https://user-images.githubusercontent.com/883973/108614840-e6e3e500-73b2-11eb-998f-0cf31b2aa9a2.png"></img>
|
||||
|
||||
You can step over each action using the "Step over" action (keyboard shortcut: `F10`) or resume script without further pauses (`F8`):
|
||||
|
||||
<center><img width="98" alt="Stepping toolbar" src="https://user-images.githubusercontent.com/883973/108614389-f9f4b600-73ae-11eb-8df2-8d9ce9da5d5c.png"></img></center>
|
||||
|
||||
|
||||
## Browser Developer Tools
|
||||
|
||||
You can use browser developer tools in Chromium, Firefox and WebKit while running
|
||||
a Playwright script in headed mode. Developer tools help to:
|
||||
|
||||
* Inspect the DOM tree and **find element selectors**
|
||||
* **See console logs** during execution (or learn how to [read logs via API](./api/class-page.md#page-event-console))
|
||||
* Check **network activity** and other developer tools features
|
||||
|
||||
<a href="https://user-images.githubusercontent.com/284612/77234134-5f21a500-6b69-11ea-92ec-1c146e1333ec.png"><img src="https://user-images.githubusercontent.com/284612/77234134-5f21a500-6b69-11ea-92ec-1c146e1333ec.png" width="500" alt="Chromium Developer Tools"></img></a>
|
||||
|
||||
Using a [`method: Page.pause`] method is an easy way to pause the Playwright script execution
|
||||
and inspect the page in Developer tools. It will also open [Playwright Inspector](./inspector.md) to help with debugging.
|
||||
|
||||
**For Chromium**: you can also open developer tools through a launch option.
|
||||
```js
|
||||
await chromium.launch({ devtools: true });
|
||||
```
|
||||
|
||||
```java
|
||||
chromium.launch(new BrowserType.LaunchOptions().setDevtools(true));
|
||||
```
|
||||
|
||||
```python async
|
||||
await chromium.launch(devtools=True)
|
||||
```
|
||||
|
||||
```python sync
|
||||
chromium.launch(devtools=True)
|
||||
```
|
||||
|
||||
```csharp
|
||||
await using var browser = await playwright.Chromium.LaunchAsync(new()
|
||||
{
|
||||
Devtools: true
|
||||
});
|
||||
```
|
||||
|
||||
:::note
|
||||
**For WebKit**: launching WebKit Inspector during the execution will
|
||||
prevent the Playwright script from executing any further.
|
||||
:::
|
||||
|
||||
## Debugging Selectors
|
||||
|
||||
- Click the Explore button to hover over elements in the screen and click them to
|
||||
automatically generate selectors for those elements.
|
||||
- To verify where selector points, paste it into the inspector input field:
|
||||
|
||||
<img width="602" alt="Selectors toolbar" src="https://user-images.githubusercontent.com/883973/108614696-ad5eaa00-73b1-11eb-81f5-9eebe62543a2.png"></img>
|
||||
|
||||
You can also use the following API inside the Developer Tools Console of any browser.
|
||||
|
||||
<img src="https://user-images.githubusercontent.com/284612/92536317-37dd9380-f1ee-11ea-875d-daf1b206dd56.png"></img>
|
||||
|
||||
#### playwright.$(selector)
|
||||
|
||||
Query Playwright selector, using the actual Playwright query engine, for example:
|
||||
|
||||
```js
|
||||
> playwright.$('.auth-form >> text=Log in');
|
||||
|
||||
<button>Log in</button>
|
||||
```
|
||||
|
||||
#### playwright.$$(selector)
|
||||
|
||||
Same as `playwright.$`, but returns all matching elements.
|
||||
|
||||
```js
|
||||
> playwright.$$('li >> text=John')
|
||||
|
||||
> [<li>, <li>, <li>, <li>]
|
||||
```
|
||||
|
||||
#### 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.*/"
|
||||
```
|
||||
|
||||
<!-- ## Recording scripts
|
||||
|
||||
At any moment, clicking Record action enables [codegen mode](./codegen.md).
|
||||
Every action on the target page is turned into the generated script:
|
||||
|
||||
<img width="712" alt="Recorded script" src="https://user-images.githubusercontent.com/883973/108614897-85704600-73b3-11eb-8bcd-f2e129786c49.png"></img>
|
||||
|
||||
You can copy entire generated script or clear it using toolbar actions. -->
|
||||
|
||||
|
||||
## Run Tests in headed mode
|
||||
|
||||
Playwright runs browsers in headless mode by default. To change this behavior,
|
||||
use `headless: false` as a launch option. You can also use the [`option: slowMo`] option
|
||||
to slow down execution and follow along while debugging.
|
||||
|
||||
```js
|
||||
await chromium.launch({ headless: false, slowMo: 100 }); // or firefox, webkit
|
||||
```
|
||||
|
||||
```java
|
||||
chromium.launch(new BrowserType.LaunchOptions() // or firefox, webkit
|
||||
.setHeadless(false)
|
||||
.setSlowMo(100));
|
||||
```
|
||||
|
||||
```python async
|
||||
await chromium.launch(headless=False, slow_mo=100) # or firefox, webkit
|
||||
|
||||
```
|
||||
|
||||
```python sync
|
||||
chromium.launch(headless=False, slow_mo=100) # or firefox, webkit
|
||||
|
||||
```
|
||||
|
||||
```csharp
|
||||
// Chromium, Firefox, or Webkit
|
||||
await using var browser = await playwright.Chromium.LaunchAsync(new()
|
||||
{
|
||||
Headless = false,
|
||||
SlowMo = 100
|
||||
});
|
||||
```
|
||||
|
||||
## Verbose API logs
|
||||
|
||||
|
|
@ -249,3 +448,8 @@ dotnet run
|
|||
$env:DEBUG="pw:api"
|
||||
dotnet run
|
||||
```
|
||||
|
||||
## What's Next
|
||||
|
||||
- [Generate tests with Codegen](./codegen.md)
|
||||
- [See a trace of your tests](./trace-viewer.md)
|
||||
|
|
@ -1,257 +0,0 @@
|
|||
---
|
||||
id: getting-started-cli
|
||||
title: "Getting started (CLI)"
|
||||
---
|
||||
|
||||
Playwright Test was created specifically to accommodate the needs of end-to-end testing. It does everything you would expect from a regular test runner, and more. Here you will learn how to:
|
||||
|
||||
- [Install Playwright using the CLI](#installation)
|
||||
- [Generate tests though user actions with Codegen](#generating-tests-with-codegen)
|
||||
- [Write assertions, use fixtures and test hooks](#writing-assertions)
|
||||
- [Run tests](#running-tests)
|
||||
- [Debug tests using the Playwright Explorer](#debugging-tests)
|
||||
- [See a detailed HTML report of your tests](#test-reports)
|
||||
- [Run tests on CI](#running-tests-on-ci)
|
||||
- [See a trace view of your test with DOM snapshots](#viewing-test-traces)
|
||||
## Installation
|
||||
|
||||
Install Playwright and follow the instructions to get started choosing either TypeScript or JavaScript, what name you would like your tests folder to be called and if you would like GitHub Actions to be set up.
|
||||
|
||||
- Install Playwright in project's root directory
|
||||
|
||||
```bash
|
||||
npm init playwright@latest
|
||||
```
|
||||
|
||||
|
||||
- Install Playwright in a new project
|
||||
|
||||
```bash
|
||||
npm init playwright@latest new-project
|
||||
```
|
||||
|
||||
For installing using the CLI see the [Getting Started (VS Code)](./getting-started-vscode.md) guide.
|
||||
## Generating Tests with Codegen
|
||||
|
||||
[CodeGen](./codegen.md) will auto generate your tests for you and is a great way to quickly get started. It will open two windows, a browser window where you interact with the website you wish to test and the Playwright Inspector window where you can record your tests, copy the tests, clear your tests as well as change the language of your tests. The Playwright inspector is also used for debugging your tests.
|
||||
|
||||
- Open Codegen
|
||||
|
||||
```bash
|
||||
npx playwright codegen
|
||||
```
|
||||
|
||||
- Open Codegen on a specific URL
|
||||
|
||||
```bash
|
||||
npx playwright codegen playwright.dev
|
||||
```
|
||||
|
||||
<img width="1916" alt="image" src="https://user-images.githubusercontent.com/13063165/177550119-4e202a56-7d8e-43ac-ad91-bf2f7b2579bd.png"/>
|
||||
|
||||
To learn more about codegen please see the [Playwright Inspector](./codegen.md) docs.
|
||||
|
||||
## Writing Assertions
|
||||
|
||||
Playwright Test uses the [expect](https://jestjs.io/docs/expect) library for test assertions. It extends it with the Playwright-specific matchers to achieve greater testing ergonomics.
|
||||
|
||||
Learn more about [test assertions](./test-assertions.md).
|
||||
|
||||
Here is a quick example of using them:
|
||||
|
||||
```js tab=js-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.
|
||||
await expect(page).toHaveTitle(/Playwright/);
|
||||
|
||||
// Expect an attribute "to be strictly equal" to the value.
|
||||
await expect(page.locator("text=Get Started").first()).toHaveAttribute(
|
||||
"href",
|
||||
"/docs/intro"
|
||||
);
|
||||
|
||||
await page.locator("text=Get Started").click();
|
||||
// Expect some text to be visible on the page.
|
||||
await expect(page.locator("text=Introduction").first()).toBeVisible();
|
||||
});
|
||||
```
|
||||
|
||||
```js tab=js-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.
|
||||
await expect(page).toHaveTitle(/Playwright/);
|
||||
|
||||
// Expect an attribute "to be strictly equal" to the value.
|
||||
await expect(page.locator("text=Get Started").first()).toHaveAttribute(
|
||||
"href",
|
||||
"/docs/intro"
|
||||
);
|
||||
|
||||
await page.locator("text=Get Started").click();
|
||||
// Expect some text to be visible on the page.
|
||||
await expect(page.locator("text=Introduction").first()).toBeVisible();
|
||||
});
|
||||
```
|
||||
|
||||
## Using test fixtures
|
||||
|
||||
You noticed an argument `{ page }` that the test above has access to:
|
||||
|
||||
```js tab=js-js
|
||||
test('basic test', async ({ page }) => {
|
||||
...
|
||||
```
|
||||
|
||||
```js tab=js-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`. |
|
||||
|
||||
## Using 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 tab=js-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://playwright.dev/");
|
||||
});
|
||||
|
||||
test("my test", async ({ page }) => {
|
||||
// Assertions use the expect API.
|
||||
await expect(page).toHaveURL("https://playwright.dev/");
|
||||
});
|
||||
});
|
||||
```
|
||||
|
||||
```js tab=js-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://playwright.dev/");
|
||||
});
|
||||
|
||||
test("my test", async ({ page }) => {
|
||||
// Assertions use the expect API.
|
||||
await expect(page).toHaveURL("https://playwright.dev/");
|
||||
});
|
||||
});
|
||||
```
|
||||
|
||||
## Running Tests
|
||||
|
||||
You can run a single test, a set of tests or all tests. Tests can be run on one browser or multiple browsers. By default tests are run in a headless manner meaning no browser window will be opened while running the tests and results will be seen in the terminal. If you prefer you can run your tests in headed mode by using the `--headed` flag.
|
||||
|
||||
- Running all tests
|
||||
|
||||
```bash
|
||||
npx playwright test
|
||||
```
|
||||
|
||||
- Running a single test file
|
||||
|
||||
```bash
|
||||
npx playwright test test-1
|
||||
```
|
||||
|
||||
- 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"
|
||||
```
|
||||
|
||||
- Running tests in headed mode
|
||||
|
||||
```bash
|
||||
npx playwright test test-1 --headed
|
||||
```
|
||||
|
||||
- Running Tests on specific browsers
|
||||
|
||||
```bash
|
||||
npx playwright test test-1.spec.ts --project=chromium
|
||||
```
|
||||
|
||||
## Debugging Tests
|
||||
|
||||
The Playwright inspector is a great tool to help with debugging. It opens up a browser window highlighting the selectors as you step through each line of the test. You can also use the explore button to find other available [selectors](./selectors.md) which you can then copy into your test file and rerun your tests to see if it passes.
|
||||
|
||||
- Debugging all Tests
|
||||
|
||||
```bash
|
||||
npx playwright test --debug
|
||||
```
|
||||
- Debugging one test
|
||||
|
||||
```bash
|
||||
npx playwright test test-1 --debug
|
||||
```
|
||||
|
||||
<img width="1904" alt="image" src="https://user-images.githubusercontent.com/13063165/177560786-c561f428-3a81-415f-a3d4-9ba889ead99e.png"></img>
|
||||
|
||||
To learn more about the Playwright Inspector please see the [Playwright Inspector](./inspector.md) docs.
|
||||
|
||||
|
||||
## Test Reports
|
||||
|
||||
The [HTML Reporter](./html-reporter.md) shows you a full report of your tests allowing you to filter the report by browsers, passed tests, failed tests, skipped tests and flaky tests. You can click on each test and explore the tests errors as well as each step of the test. By default, the HTML report is opened automatically if some of the tests failed.
|
||||
|
||||
```bash
|
||||
npx playwright show-report
|
||||
```
|
||||
|
||||
<img width="739" alt="image" src="https://user-images.githubusercontent.com/13063165/178003817-3bd2f088-4173-406c-a9e9-74c89181f381.png" />
|
||||
|
||||
To learn more about the HTML Reporter please see the [HTML Reporter](./html-reporter.md) docs.
|
||||
|
||||
## Running Tests on CI
|
||||
|
||||
Run your tests locally or on CI on each pull request with GitHub actions. Tests can be run on a local dev environment or on a staging URL. Checkout our guide for more options on [CI Configurations](./ci.md).
|
||||
|
||||
## Viewing Test Traces
|
||||
|
||||
Playwright Trace Viewer is a GUI tool where you can explore recorded Playwright traces after the script has ran. See your test's DOM snapshot before and after the action item. View the test's timeline, log, source, network and console. Open traces locally or in your browser on [`trace.playwright.dev`](https://trace.playwright.dev).
|
||||
|
||||
<img width="1212" alt="Playwright Trace Viewer" src="https://user-images.githubusercontent.com/883973/120585896-6a1bca80-c3e7-11eb-951a-bd84002480f5.png"></img>
|
||||
|
||||
To learn more about the Trace Viewer please see the [Trace Viewer](./trace-viewer.md) docs.
|
||||
|
|
@ -1,30 +1,23 @@
|
|||
---
|
||||
id: getting-started-vscode
|
||||
title: "Getting started (VS Code)"
|
||||
title: "Getting started - VS Code"
|
||||
---
|
||||
|
||||
Playwright Test was created specifically to accommodate the needs of end-to-end testing. It does everything you would expect from a regular test runner, and more. Here you will learn how to:
|
||||
Playwright Test was created specifically to accommodate the needs of end-to-end testing. Playwright supports all modern rendering engines including Chromium, WebKit, and Firefox. Test on Windows, Linux, and macOS, locally or on CI, headless or headed with native mobile emulation of Google Chrome for Android and Mobile Safari.
|
||||
|
||||
- [Install Playwright using the VS Code Extension](#installation)
|
||||
- [Generate tests with Codegen right from VS Code](#generating-tests-with-codegen)
|
||||
- [Write assertions, use test fixtures and test hooks](#writing-assertions)
|
||||
- [Run tests in VS Code](#running-tests)
|
||||
- [Create breakpoints and debug tests right in VS Code](#debugging-tests)
|
||||
- [See a detailed HTML report of your tests](#test-reports)
|
||||
- [Run tests on CI](#running-tests-on-ci)
|
||||
- [See a trace view of your test with DOM snapshots](#viewing-test-traces)
|
||||
Get started by installing Playwright and generating a test to see it in action.
|
||||
|
||||
## Installation
|
||||
|
||||
Install the [VS Code extension from the marketplace](https://marketplace.visualstudio.com/items?itemName=ms-playwright.playwright). Once installed, open the command panel and type "Install Playwright" and select "Test: Install Playwright". Choose the browsers you would like to run your tests on. These can be later configured in the `playwright.config.ts` file.
|
||||
Install the [VS Code extension from the marketplace](https://marketplace.visualstudio.com/items?itemName=ms-playwright.playwright).
|
||||
|
||||
<img width="535" alt="image" src="https://user-images.githubusercontent.com/13063165/177198887-de49ec12-a7a9-48c2-8d02-ad53ea312c91.png"></img>
|
||||
|
||||
<!-- <img width="535" alt="image" src="https://user-images.githubusercontent.com/13063165/177198887-de49ec12-a7a9-48c2-8d02-ad53ea312c91.png"></img> -->
|
||||
Once installed, open the command panel and type "Install Playwright" and select "Test: Install Playwright". Choose the browsers you would like to run your tests on. These can be later configured in the [playwright.config file](./test-configuration.md) file.
|
||||
|
||||
|
||||
<img width="538" alt="image" src="https://user-images.githubusercontent.com/13063165/177199115-ce90eb84-f12a-4b95-bd3a-17ff870fcec2.png"></img>
|
||||
|
||||
For installing using the CLI see the [Getting Started (CLI)](./getting-started-cli.md) guide.
|
||||
|
||||
## Generating Tests with Codegen
|
||||
|
||||
|
|
@ -35,122 +28,6 @@ For installing using the CLI see the [Getting Started (CLI)](./getting-started-c
|
|||
As you hover over an element Playwright will highlight the element with the [selector](./selectors.md) shown underneath it. If you click the element [CodeGen](./codegen.md) will generate the test for you in the test file that was created.
|
||||
<img width="958" alt="image" src="https://user-images.githubusercontent.com/13063165/177199982-42dc316f-3438-48b1-a6a6-417be77be658.png"></img>
|
||||
|
||||
To learn more about codegen please see the [Test Generator](./codegen.md) docs.
|
||||
|
||||
## Writing Assertions
|
||||
|
||||
Playwright Test uses the [expect](https://jestjs.io/docs/expect) library for test assertions. It extends it with the Playwright-specific matchers to achieve greater testing ergonomics.
|
||||
|
||||
Learn more about [test assertions](./test-assertions.md).
|
||||
|
||||
Here is a quick example of using them:
|
||||
|
||||
```js tab=js-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.
|
||||
await expect(page).toHaveTitle(/Playwright/);
|
||||
|
||||
// Expect an attribute "to be strictly equal" to the value.
|
||||
await expect(page.locator("text=Get Started").first()).toHaveAttribute(
|
||||
"href",
|
||||
"/docs/intro"
|
||||
);
|
||||
|
||||
await page.locator("text=Get Started").click();
|
||||
// Expect some text to be visible on the page.
|
||||
await expect(page.locator("text=Introduction").first()).toBeVisible();
|
||||
});
|
||||
```
|
||||
|
||||
```js tab=js-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.
|
||||
await expect(page).toHaveTitle(/Playwright/);
|
||||
|
||||
// Expect an attribute "to be strictly equal" to the value.
|
||||
await expect(page.locator("text=Get Started").first()).toHaveAttribute(
|
||||
"href",
|
||||
"/docs/intro"
|
||||
);
|
||||
|
||||
await page.locator("text=Get Started").click();
|
||||
// Expect some text to be visible on the page.
|
||||
await expect(page.locator("text=Introduction").first()).toBeVisible();
|
||||
});
|
||||
```
|
||||
|
||||
## Using test fixtures
|
||||
|
||||
You noticed an argument `{ page }` that the test above has access to:
|
||||
|
||||
```js tab=js-js
|
||||
test('basic test', async ({ page }) => {
|
||||
...
|
||||
```
|
||||
|
||||
```js tab=js-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`. |
|
||||
|
||||
## Using 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 tab=js-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://playwright.dev/");
|
||||
});
|
||||
|
||||
test("my test", async ({ page }) => {
|
||||
// Assertions use the expect API.
|
||||
await expect(page).toHaveURL("https://playwright.dev/");
|
||||
});
|
||||
});
|
||||
```
|
||||
|
||||
```js tab=js-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://playwright.dev/");
|
||||
});
|
||||
|
||||
test("my test", async ({ page }) => {
|
||||
// Assertions use the expect API.
|
||||
await expect(page).toHaveURL("https://playwright.dev/");
|
||||
});
|
||||
});
|
||||
```
|
||||
|
||||
## Running Tests
|
||||
|
||||
|
|
@ -176,38 +53,7 @@ With the VS Code extension you can debug your tests right in VS Code see error m
|
|||
|
||||
<img width="1025" alt="image" src="https://user-images.githubusercontent.com/13063165/178027941-0d9d5f88-2426-43fb-b204-62a2add27415.png" />
|
||||
|
||||
Modify your test right in VS Code while debugging and Playwright will highlight the selector you are modifying in the browser. You can step through the tests, pause the test and rerun the tests from the menu in VS Code.
|
||||
Modify your test right in VS Code while debugging and Playwright will highlight the selector you are modifying in the browser. You can step through the tests, pause the test and rerun the tests from the menu in VS Code.
|
||||
|
||||
<img width="1044" alt="image" src="https://user-images.githubusercontent.com/13063165/178029249-e0a85f53-b8d4-451f-b3e5-df62b0c57929.png" />
|
||||
|
||||
## Test Reports
|
||||
|
||||
The [HTML Reporter](./html-reporter.md) shows you a full report of your tests allowing you to filter the report by browsers, passed tests, failed tests, skipped tests and flaky tests. You can click on each test and explore the tests errors as well as each step of the test. By default, the HTML report is opened automatically if some of the tests failed.
|
||||
|
||||
- Run your tests using the CLI
|
||||
|
||||
```bash
|
||||
npx playwright test
|
||||
```
|
||||
|
||||
- Show the HTML Report
|
||||
|
||||
```bash
|
||||
npx playwright show-report
|
||||
```
|
||||
|
||||
<img width="739" alt="image" src="https://user-images.githubusercontent.com/13063165/178003817-3bd2f088-4173-406c-a9e9-74c89181f381.png" />
|
||||
|
||||
To learn more about the HTML Reporter please see the [HTML Reporter](./html-reporter.md) docs.
|
||||
|
||||
## Running Tests on CI
|
||||
|
||||
Run your tests locally or on CI on each pull request with GitHub actions. Tests can be run on a local dev environment or on a staging URL. Checkout our guide for more options on [CI Configurations](./ci.md).
|
||||
|
||||
## Viewing Test Traces
|
||||
|
||||
Playwright Trace Viewer is a GUI tool where you can explore recorded Playwright traces after the script has ran. See your test's DOM snapshot before and after the action item. View the test's timeline, log, source, network and console. Open traces locally or in your browser on [`trace.playwright.dev`](https://trace.playwright.dev).
|
||||
|
||||
<img width="1212" alt="Playwright Trace Viewer" src="https://user-images.githubusercontent.com/883973/120585896-6a1bca80-c3e7-11eb-951a-bd84002480f5.png"></img>
|
||||
|
||||
To learn more about the Trace Viewer please see the [Trace Viewer](./trace-viewer.md) docs.
|
||||
|
|
@ -1,419 +1,89 @@
|
|||
---
|
||||
id: intro
|
||||
title: "Getting started"
|
||||
title: "Installation"
|
||||
---
|
||||
|
||||
Playwright can either be used as a part of the Playwright Test test runner (this guide), or as a [Playwright Library](./library.md).
|
||||
Playwright Test was created specifically to accommodate the needs of end-to-end testing. Playwright supports all modern rendering engines including Chromium, WebKit, and Firefox. Test on Windows, Linux, and macOS, locally or on CI, headless or headed with native mobile emulation of Google Chrome for Android and Mobile Safari.
|
||||
|
||||
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:
|
||||
Get started by installing Playwright and running the example test to see it in action.
|
||||
|
||||
- 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.
|
||||
|
||||
<br/>
|
||||
|
||||
<!-- TOC -->
|
||||
- [Release notes](./release-notes.md)
|
||||
|
||||
<br/>
|
||||
|
||||
## Installation
|
||||
|
||||
Playwright has its own test runner for end-to-end tests, we call it Playwright Test.
|
||||
|
||||
### Using the VS Code extension
|
||||
|
||||
Install the VS Code extension from the [marketplace](https://marketplace.visualstudio.com/items?itemName=ms-playwright.playwright).
|
||||
|
||||
If you don't have the Playwright Test npm package installed in your project, or if you are starting with a new testing project, "Install Playwright" action will help you get started.
|
||||
|
||||
<img width="446" alt="Install Playwright" src="https://user-images.githubusercontent.com/883973/153693073-a83fc6e6-a17a-4011-b11e-2423f75ce584.png"></img>
|
||||
|
||||
Pick the browsers you'd like to use by default, don't worry, you'll be able to change them later to add or configure the browsers used.
|
||||
|
||||
<img width="579" alt="Choose browsers" src="https://user-images.githubusercontent.com/883973/153693126-258646eb-0d4c-41eb-8c4a-7ac248384078.png"></img>
|
||||
|
||||
The extension automatically detects if you have [Playwright Test] installed and loads the [Playwright Test] projects into Visual Studio Code. By default it will select the first project as a run profile and inside the test explorer you can change this behavior to run a single test in multiple or different browsers.
|
||||
|
||||
### Using init command
|
||||
|
||||
Alternatively, you can scaffold your project using the init command.
|
||||
<Tabs
|
||||
defaultValue="npm"
|
||||
values={[
|
||||
{label: 'npm', value: 'npm'},
|
||||
{label: 'yarn', value: 'yarn'}
|
||||
]
|
||||
}>
|
||||
<TabItem value="npm">
|
||||
|
||||
```bash
|
||||
# Run from your project's root directory
|
||||
npm init playwright@latest
|
||||
# Or create a new project
|
||||
npm init playwright@latest new-project
|
||||
```
|
||||
|
||||
This will create a configuration file, optionally add examples, a GitHub Action workflow and a first test `example.spec.ts`. You can now jump directly to [writing assertions](#writing-assertions) section.
|
||||
</TabItem>
|
||||
|
||||
### Manually
|
||||
|
||||
Add dependency and install browsers.
|
||||
<TabItem value="yarn">
|
||||
|
||||
```bash
|
||||
npm i -D @playwright/test
|
||||
# install supported browsers
|
||||
npx playwright install
|
||||
yarn create playwright@latest
|
||||
```
|
||||
|
||||
You can optionally install only selected browsers, see [install browsers](./cli.md#install-browsers) for more details. Or you can install no browsers at all and use existing [browser channels](./browsers.md).
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
## First test
|
||||
|
||||
Create `tests/example.spec.js` (or `tests/example.spec.ts` for TypeScript) to define your test.
|
||||
Run the install command and select the following to get started:
|
||||
- Choose between TypeScript or JavaScript(default is TypeScript)
|
||||
- Name of your Tests folder (default is tests or e2e if you already have a tests folder in your project)
|
||||
- Add a GitHub Actions workflow to easily run tests on CI
|
||||
|
||||
```js tab=js-js
|
||||
const { test, expect } = require('@playwright/test');
|
||||
<!-- For installing using the CLI see the [Getting Started (VS Code)](./getting-started-vscode.mdx) guide. -->
|
||||
|
||||
test('basic test', async ({ page }) => {
|
||||
await page.goto('https://playwright.dev/');
|
||||
const title = page.locator('.navbar__inner .navbar__title');
|
||||
await expect(title).toHaveText('Playwright');
|
||||
});
|
||||
## What's Installed
|
||||
|
||||
Playwright will download the browsers needed as well as create the following files.
|
||||
|
||||
```bash
|
||||
playwright.config.ts
|
||||
package.json
|
||||
package-lock.json
|
||||
tests/
|
||||
example.spec.ts
|
||||
tests-demos/
|
||||
demo-todo-app.spec.ts
|
||||
```
|
||||
|
||||
```js tab=js-ts
|
||||
import { test, expect } from '@playwright/test';
|
||||
The playwright [playwright.config file](./test-configuration.md) is where you can add configuration for Playwright including modifying which browsers you would like to run Playwright on.
|
||||
|
||||
If you are running tests inside an already existing project then a package.json and package-lock.json file will not be created. Instead the dependencies will be added to your already existing package.json file.
|
||||
|
||||
The tests folder contains a basic example test to help you get started with testing as well as a more detailed example with tests written to test a todo app.
|
||||
|
||||
test('basic test', async ({ page }) => {
|
||||
await page.goto('https://playwright.dev/');
|
||||
const title = page.locator('.navbar__inner .navbar__title');
|
||||
await expect(title).toHaveText('Playwright');
|
||||
});
|
||||
```
|
||||
## Running the Example Test
|
||||
|
||||
Now run your tests, assuming that test files are in the `tests` directory.
|
||||
By default tests will be run on all 3 browsers, chromium, firefox and webkit using 3 workers. This can be configured in the [playwright.config file](./test-configuration.md). Tests are run in headless mode meaning no browser will open up when running the tests. Results of the tests and test logs will be shown in the terminal.
|
||||
|
||||
```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:
|
||||
See our doc on [Running Tests](./running-tests.md) to learn more about running tests in headed mode, running multiple tests, running specific tests etc.
|
||||
|
||||
## HTML Test Reports
|
||||
|
||||
Once your test has finished running a [HTML Reporter](./html-reporter.md) will have been created which shows you a full report of your tests allowing you to filter the report by browsers, passed tests, failed tests, skipped tests and flaky tests. You can click on each test and explore the test's errors as well as each step of the test. By default, the HTML report is opened automatically if some of the tests failed.
|
||||
|
||||
```bash
|
||||
npx playwright test --headed
|
||||
npx playwright show-report
|
||||
```
|
||||
|
||||
## Configuration file
|
||||
<img width="739" alt="image" src="https://user-images.githubusercontent.com/13063165/178003817-3bd2f088-4173-406c-a9e9-74c89181f381.png" />
|
||||
|
||||
To enjoy all the features that Playwright Test has to offer, you would want to create a configuration file `playwright.config.ts` (or `playwright.config.js`). It allows you to run tests in multiple browsers configured as you'd like.
|
||||
|
||||
Here is an example configuration that runs every test in Chromium, Firefox and WebKit, by creating a "project" for each browser configuration. It also specifies [two retries](./test-retries.md) and [tracing](./trace-viewer.md) options.
|
||||
## What's next
|
||||
|
||||
```js tab=js-js
|
||||
// playwright.config.js
|
||||
// @ts-check
|
||||
const { devices } = require('@playwright/test');
|
||||
|
||||
/** @type {import('@playwright/test').PlaywrightTestConfig} */
|
||||
const config = {
|
||||
forbidOnly: !!process.env.CI,
|
||||
retries: process.env.CI ? 2 : 0,
|
||||
use: {
|
||||
trace: 'on-first-retry',
|
||||
},
|
||||
projects: [
|
||||
{
|
||||
name: 'chromium',
|
||||
use: { ...devices['Desktop Chrome'] },
|
||||
},
|
||||
{
|
||||
name: 'firefox',
|
||||
use: { ...devices['Desktop Firefox'] },
|
||||
},
|
||||
{
|
||||
name: 'webkit',
|
||||
use: { ...devices['Desktop Safari'] },
|
||||
},
|
||||
],
|
||||
};
|
||||
|
||||
module.exports = config;
|
||||
```
|
||||
|
||||
```js tab=js-ts
|
||||
// playwright.config.ts
|
||||
import { type PlaywrightTestConfig, devices } from '@playwright/test';
|
||||
|
||||
const config: PlaywrightTestConfig = {
|
||||
forbidOnly: !!process.env.CI,
|
||||
retries: process.env.CI ? 2 : 0,
|
||||
use: {
|
||||
trace: 'on-first-retry',
|
||||
},
|
||||
projects: [
|
||||
{
|
||||
name: 'chromium',
|
||||
use: { ...devices['Desktop Chrome'] },
|
||||
},
|
||||
{
|
||||
name: 'firefox',
|
||||
use: { ...devices['Desktop Firefox'] },
|
||||
},
|
||||
{
|
||||
name: 'webkit',
|
||||
use: { ...devices['Desktop Safari'] },
|
||||
},
|
||||
],
|
||||
};
|
||||
export default config;
|
||||
```
|
||||
|
||||
Look for more options in the [configuration section](./test-configuration.md).
|
||||
|
||||
Now you can run tests in multiple browsers by default.
|
||||
|
||||
```bash
|
||||
npx playwright test
|
||||
|
||||
Running 5 tests using 5 workers
|
||||
|
||||
✓ [chromium] › example.spec.ts:3:1 › basic test (2s)
|
||||
✓ [firefox] › example.spec.ts:3:1 › basic test (2s)
|
||||
✓ [webkit] › example.spec.ts:3:1 › basic test (2s)
|
||||
```
|
||||
|
||||
Use `--project` command line option to run a single project.
|
||||
|
||||
```bash
|
||||
npx playwright test --project=firefox
|
||||
|
||||
Running 1 test using 1 worker
|
||||
|
||||
✓ [firefox] › example.spec.ts:3:1 › basic test (2s)
|
||||
```
|
||||
|
||||
## Writing assertions
|
||||
|
||||
Playwright Test uses [expect](https://jestjs.io/docs/expect) library for test assertions. It extends it with the Playwright-specific matchers to achieve greater testing ergonomics.
|
||||
|
||||
Learn more about [test assertions here](./test-assertions.md).
|
||||
|
||||
Here is a quick example of using them:
|
||||
|
||||
|
||||
```js tab=js-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.
|
||||
await expect(page).toHaveTitle(/Playwright/);
|
||||
|
||||
// Expect an attribute "to be strictly equal" to the value.
|
||||
await expect(page.locator('text=Get Started')).toHaveAttribute('href', '/docs/intro');
|
||||
|
||||
await page.locator('text=Get Started').click();
|
||||
// Expect some text to be visible on the page.
|
||||
await expect(page.locator('text=Introduction').first()).toBeVisible();
|
||||
});
|
||||
```
|
||||
|
||||
```js tab=js-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.
|
||||
await expect(page).toHaveTitle(/Playwright/);
|
||||
|
||||
// Expect an attribute "to be strictly equal" to the value.
|
||||
await expect(page.locator('text=Get Started')).toHaveAttribute('href', '/docs/intro');
|
||||
|
||||
await page.locator('text=Get Started').click();
|
||||
// Expect some text to be visible on the page.
|
||||
await expect(page.locator('text=Introduction').first()).toBeVisible();
|
||||
});
|
||||
```
|
||||
|
||||
## Using test fixtures
|
||||
|
||||
You noticed an argument `{ page }` that the test above has access to:
|
||||
|
||||
```js tab=js-js
|
||||
test('basic test', async ({ page }) => {
|
||||
...
|
||||
```
|
||||
|
||||
```js tab=js-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`.|
|
||||
|
||||
## Using 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 tab=js-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://playwright.dev/');
|
||||
});
|
||||
|
||||
test('my test', async ({ page }) => {
|
||||
// Assertions use the expect API.
|
||||
await expect(page).toHaveURL('https://playwright.dev/');
|
||||
});
|
||||
});
|
||||
```
|
||||
|
||||
```js tab=js-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://playwright.dev/');
|
||||
});
|
||||
|
||||
test('my test', async ({ page }) => {
|
||||
// Assertions use the expect API.
|
||||
await expect(page).toHaveURL('https://playwright.dev/');
|
||||
});
|
||||
});
|
||||
```
|
||||
|
||||
## VS Code extension
|
||||
|
||||
Install the VS Code extension from the [marketplace](https://marketplace.visualstudio.com/items?itemName=ms-playwright.playwright).
|
||||
|
||||
### Run tests with a single click
|
||||
|
||||
You can use Tests sidebar to run a test or a group of tests with a single click.
|
||||
|
||||
|
||||
|
||||
### Follow the execution line
|
||||
|
||||
While tests are running, execution line is highlighted, once the line has completed, step time is rendered as an editor decoration.
|
||||
|
||||
|
||||
|
||||
### Debug step-by-step, explore selectors
|
||||
|
||||
Right click and start breakpoint debugging. Set a breakpoint, hover over a value. When your cursor is on some Playwright action or a locator, corresponding element (or elements) are highlighted in the browser.
|
||||
|
||||
|
||||
|
||||
### Record new tests
|
||||
|
||||
Record new tests via performing the test actions in the browser.
|
||||
|
||||
|
||||
|
||||
### Tune selectors
|
||||
|
||||
You can edit test source code to fine-tune selectors while on a breakpoint. A selector playground on every line of your test script!
|
||||
|
||||
|
||||
|
||||
## Command line
|
||||
|
||||
Following are the usual command line patterns. Learn more about the [command line](./test-cli.md).
|
||||
|
||||
- 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 configuration (project)
|
||||
```bash
|
||||
npx playwright test --project=firefox
|
||||
```
|
||||
|
||||
- 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
|
||||
npx playwright test --debug
|
||||
```
|
||||
|
||||
- Ask for help
|
||||
```bash
|
||||
npx playwright test --help
|
||||
```
|
||||
|
||||
## Configure NPM scripts
|
||||
|
||||
Playwright Test will automatically pick up `playwright.config.js` or `playwright.config.ts`.
|
||||
|
||||
```json
|
||||
{
|
||||
"scripts": {
|
||||
"test": "playwright test"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
If you put your configuration file in a different place, pass it with `--config` option.
|
||||
|
||||
```json
|
||||
{
|
||||
"scripts": {
|
||||
"test": "playwright test --config=tests/example.config.js"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
:::note
|
||||
To pass options through npm script, use double dashes: ```npm run test -- --headed```.
|
||||
:::
|
||||
- [Write tests using web first assertions, page fixtures and locators](./writing-tests.md)
|
||||
- [Run single tests, multiple tests, headed mode](./running-tests.md)
|
||||
- [Debug tests with the Playwright Debugger](./debug.md)
|
||||
- [Generate tests with Codegen](./codegen.md)
|
||||
- [See a trace of your tests](./trace-viewer.md)
|
||||
65
docs/src/running-tests-js.md
Normal file
65
docs/src/running-tests-js.md
Normal file
|
|
@ -0,0 +1,65 @@
|
|||
---
|
||||
id: running-tests
|
||||
title: "Running Tests"
|
||||
---
|
||||
|
||||
You can run a single test, a set of tests or all tests. Tests can be run on one browser or multiple browsers. By default tests are run in a headless manner meaning no browser window will be opened while running the tests and results will be seen in the terminal. If you prefer you can run your tests in headed mode by using the `--headed` flag.
|
||||
|
||||
- Running all tests
|
||||
|
||||
```bash
|
||||
npx playwright test
|
||||
```
|
||||
|
||||
- Running a single test file
|
||||
|
||||
```bash
|
||||
npx playwright test test-1
|
||||
```
|
||||
|
||||
- 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"
|
||||
```
|
||||
|
||||
- Running tests in headed mode
|
||||
|
||||
```bash
|
||||
npx playwright test test-1 --headed
|
||||
```
|
||||
|
||||
- Running Tests on specific browsers
|
||||
|
||||
```bash
|
||||
npx playwright test test-1.spec.ts --project=chromium
|
||||
```
|
||||
|
||||
## Test Reports
|
||||
|
||||
The [HTML Reporter](./html-reporter.md) shows you a full report of your tests allowing you to filter the report by browsers, passed tests, failed tests, skipped tests and flaky tests. You can click on each test and explore the tests errors as well as each step of the test. By default, the HTML report is opened automatically if some of the tests failed.
|
||||
|
||||
```bash
|
||||
npx playwright show-report
|
||||
```
|
||||
|
||||
<img width="739" alt="image" src="https://user-images.githubusercontent.com/13063165/178003817-3bd2f088-4173-406c-a9e9-74c89181f381.png" />
|
||||
|
||||
|
||||
## What's Next
|
||||
|
||||
- [Debug tests with the Playwright Debugger](./debug.md)
|
||||
- [Generate tests with Codegen](./codegen.md)
|
||||
- [See a trace of your tests](./trace-viewer.md)
|
||||
|
|
@ -7,7 +7,6 @@ Playwright Trace Viewer is a GUI tool that helps exploring recorded Playwright t
|
|||
|
||||
<img width="1212" alt="Playwright Trace Viewer" src="https://user-images.githubusercontent.com/883973/120585896-6a1bca80-c3e7-11eb-951a-bd84002480f5.png"></img>
|
||||
|
||||
<!-- TOC -->
|
||||
|
||||
## Recording a trace
|
||||
* langs: js
|
||||
|
|
@ -238,3 +237,5 @@ You can also pass the URL of your uploaded trace (e.g. inside your CI) from some
|
|||
```txt
|
||||
https://trace.playwright.dev/?trace=https://demo.playwright.dev/reports/todomvc/data/cb0fa77ebd9487a5c899f3ae65a7ffdbac681182.zip
|
||||
```
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -1,36 +0,0 @@
|
|||
---
|
||||
id: vs-code-extension
|
||||
title: "VS Code Extension"
|
||||
---
|
||||
|
||||
Install the VS Code extension from the [marketplace](https://marketplace.visualstudio.com/items?itemName=ms-playwright.playwright).
|
||||
|
||||
### Run tests with a single click
|
||||
|
||||
You can use Tests sidebar to run a test or a group of tests with a single click.
|
||||
|
||||
|
||||
|
||||
### Follow the execution line
|
||||
|
||||
While tests are running, execution line is highlighted, once the line has completed, step time is rendered as an editor decoration.
|
||||
|
||||
|
||||
|
||||
### Debug step-by-step, explore selectors
|
||||
|
||||
Right click and start breakpoint debugging. Set a breakpoint, hover over a value. When your cursor is on some Playwright action or a locator, corresponding element (or elements) are highlighted in the browser.
|
||||
|
||||
|
||||
|
||||
### Record new tests
|
||||
|
||||
Record new tests via performing the test actions in the browser.
|
||||
|
||||
|
||||
|
||||
### Tune selectors
|
||||
|
||||
You can edit test source code to fine-tune selectors while on a breakpoint. A selector playground on every line of your test script!
|
||||
|
||||
|
||||
139
docs/src/writing-tests-js.md
Normal file
139
docs/src/writing-tests-js.md
Normal file
|
|
@ -0,0 +1,139 @@
|
|||
---
|
||||
id: writing-tests
|
||||
title: "Writing Tests"
|
||||
---
|
||||
|
||||
Playwright assertions are created specifically for the dynamic web. Checks are automatically retried until the necessary conditions are met. Playwright comes with auto-wait built in meaning it waits for elements to be actionable prior to performing actions. Playwright provides a [test](./api/class-test.md) function to declare tests and the [expect](https://jestjs.io/docs/expect) function to write assertions.
|
||||
|
||||
Take a look at the example test included when installing Playwright to see how to write a test using web first assertions, locators and selectors.
|
||||
|
||||
```js tab=js-js
|
||||
// @ts-check
|
||||
const { test, expect } = require('@playwright/test');
|
||||
|
||||
test('homepage has Playwright in title and get started link linking to the intro page', async ({ page }) => {
|
||||
await page.goto('https://playwright.dev/');
|
||||
|
||||
// Expect a title "to contain" a substring.
|
||||
await expect(page).toHaveTitle(/Playwright/);
|
||||
|
||||
// create a locator
|
||||
const getStarted = page.locator('text=Get Started');
|
||||
|
||||
// Expect an attribute "to be strictly equal" to the value.
|
||||
await expect(getStarted).toHaveAttribute('href', '/docs/intro');
|
||||
|
||||
// Click the get started link.
|
||||
await getStarted.click();
|
||||
|
||||
// Expects the URL to contain intro.
|
||||
await expect(page).toHaveURL(/.*intro/);
|
||||
});
|
||||
```
|
||||
|
||||
```js tab=js-ts
|
||||
import { test, expect } from '@playwright/test';
|
||||
|
||||
test('homepage has Playwright in title and get started link linking to the intro page', async ({ page }) => {
|
||||
await page.goto('https://playwright.dev/');
|
||||
|
||||
// Expect a title "to contain" a substring.
|
||||
await expect(page).toHaveTitle(/Playwright/);
|
||||
|
||||
// create a locator
|
||||
const getStarted = page.locator('text=Get Started');
|
||||
|
||||
// Expect an attribute "to be strictly equal" to the value.
|
||||
await expect(getStarted).toHaveAttribute('href', '/docs/intro');
|
||||
|
||||
// Click the get started link.
|
||||
await getStarted.click();
|
||||
|
||||
// Expects the URL to contain intro.
|
||||
await expect(page).toHaveURL(/.*intro/);
|
||||
});
|
||||
```
|
||||
|
||||
:::note
|
||||
Add `// @ts-check` at the start of each test file when using JavaScript in VS Code to get automatic type checking.
|
||||
:::
|
||||
|
||||
### Assertions
|
||||
|
||||
Playwright Test uses the [expect](https://jestjs.io/docs/expect) library for [test assertions](./test-assertions.md) which provides matchers like `toEqual`, `toContain`, `toMatch`, `toBe` and many more. Playwright also extends this library with convenience async matchers that will wait until the expected condition is met.
|
||||
|
||||
```js
|
||||
await expect(page).toHaveTitle(/Playwright/);
|
||||
```
|
||||
|
||||
|
||||
### Locators
|
||||
|
||||
[Locators](./locators.md) are the central piece of Playwright's auto-waiting and retry-ability. Locators represent a way to find element(s) on the page at any moment and are used to perform actions on elements such as .click. fill etc. Custom locators can be created with the [`method: Page.locator`] method.
|
||||
|
||||
```js
|
||||
const getStarted = page.locator('text=Get Started');
|
||||
|
||||
await expect(getStarted).toHaveAttribute('href', '/docs/installation');
|
||||
await getStarted.click();
|
||||
```
|
||||
|
||||
[Selectors](./selectors.md) are strings that are used to create Locators. Playwright supports many different selectors like [Text](./selectors.md#text-selector), [CSS](./selectors.md#css-selector), [XPath](./selectors.md#xpath-selectors) and many more.
|
||||
|
||||
```js
|
||||
await expect(page.locator('text=Installation')).toBeVisible();
|
||||
```
|
||||
|
||||
|
||||
### Test Isolation
|
||||
|
||||
Playwright Test is based on the concept of [test fixtures](./test-fixtures.md) such as the [built in page fixture](./test-fixtures#built-in-fixtures), which is passed into your test. Pages are isolated between tests due to the Browser Context, which is equivalent to a brand new browser profile, where every test gets a fresh environment, even when multiple tests run in a single Browser.
|
||||
|
||||
```js
|
||||
test('basic test', async ({ page }) => {
|
||||
...
|
||||
```
|
||||
|
||||
### Using Test Hooks
|
||||
|
||||
You can use various [test hooks](./api/class-test.md) such as `test.describe` to declare a group of tests and `test.beforeEach` and `test.afterEach` which are executed before/after each test. Other hooks include the `test.beforeAll` and `test.afterAll` which are executed once per worker before/after all tests.
|
||||
|
||||
```js tab=js-js
|
||||
// @ts-check
|
||||
const { test, expect } = require("@playwright/test");
|
||||
|
||||
test.describe("navigation", () => {
|
||||
test.beforeEach(async ({ page }) => {
|
||||
// Go to the starting url before each test.
|
||||
await page.goto("https://playwright.dev/");
|
||||
});
|
||||
|
||||
test("main navigation", async ({ page }) => {
|
||||
// Assertions use the expect API.
|
||||
await expect(page).toHaveURL("https://playwright.dev/");
|
||||
});
|
||||
});
|
||||
```
|
||||
|
||||
```js tab=js-ts
|
||||
import { test, expect } from "@playwright/test";
|
||||
|
||||
test.describe("navigation", () => {
|
||||
test.beforeEach(async ({ page }) => {
|
||||
// Go to the starting url before each test.
|
||||
await page.goto("https://playwright.dev/");
|
||||
});
|
||||
|
||||
test("main navigation", async ({ page }) => {
|
||||
// Assertions use the expect API.
|
||||
await expect(page).toHaveURL("https://playwright.dev/");
|
||||
});
|
||||
});
|
||||
```
|
||||
|
||||
## What's Next
|
||||
|
||||
- [Run single tests, multiple tests, headed mode](./running-tests.md)
|
||||
- [Debug tests with the Playwright Debugger](./debug.md)
|
||||
- [Generate tests with Codegen](./codegen.md)
|
||||
- [See a trace of your tests](./trace-viewer.md)
|
||||
Loading…
Reference in a new issue