docs: update docs with ToT docs (#16262)
This commit is contained in:
Max Schmitt
GitHub
parent
0eb8a70089
commit
0e0a54e6e2
238
docs/src/accessibility-testing-java.md
Normal file
238
docs/src/accessibility-testing-java.md
Normal file
|
|
@ -0,0 +1,238 @@
|
||||||
|
---
|
||||||
|
id: accessibility-testing
|
||||||
|
title: "Accessibility testing"
|
||||||
|
---
|
||||||
|
|
||||||
|
Playwright can be used to test your application for many types of accessibility issues.
|
||||||
|
|
||||||
|
A few examples of problems this can catch include:
|
||||||
|
- Text that would be hard to read for users with vision impairments due to poor color contrast with the background behind it
|
||||||
|
- UI controls and form elements without labels that a screen reader could identify
|
||||||
|
- Interactive elements with duplicate IDs which can confuse assistive technologies
|
||||||
|
|
||||||
|
The following examples rely on the [`com.deque.html.axe-core/playwright`](https://mvnrepository.com/artifact/com.deque.html.axe-core/playwright) Maven package which adds support for running the [axe accessibility testing engine](https://www.deque.com/axe/) as part of your Playwright tests.
|
||||||
|
|
||||||
|
<!-- TOC -->
|
||||||
|
|
||||||
|
## Disclaimer
|
||||||
|
|
||||||
|
Automated accessibility tests can detect some common accessibility problems such as missing or invalid properties. But many accessibility problems can only be discovered through manual testing. We recommend using a combination of automated testing, manual accessibility assessments, and inclusive user testing.
|
||||||
|
|
||||||
|
For manual assessments, we recommend [Accessibility Insights for Web](https://accessibilityinsights.io/docs/web/overview/?referrer=playwright-accessibility-testing-java), a free and open source dev tool that walks you through assessing a website for [WCAG 2.1 AA](https://www.w3.org/WAI/WCAG21/quickref/?currentsidebar=%23col_customize&levels=aaa) coverage.
|
||||||
|
|
||||||
|
## Example accessibility tests
|
||||||
|
|
||||||
|
Accessibility tests work just like any other Playwright test. You can either create separate test cases for them, or integrate accessibility scans and assertions into your existing test cases.
|
||||||
|
|
||||||
|
The following examples demonstrate a few basic accessibility testing scenarios.
|
||||||
|
|
||||||
|
### Example 1: Scanning an entire page
|
||||||
|
|
||||||
|
This example demonstrates how to test an entire page for automatically detectable accessibility violations. The test:
|
||||||
|
1. Imports the [`com.deque.html.axe-core/playwright`](https://mvnrepository.com/artifact/com.deque.html.axe-core/playwright) package
|
||||||
|
1. Uses normal JUnit 5 `@Test` syntax to define a test case
|
||||||
|
1. Uses normal Playwright syntax to open a browser and navigate to the page under test
|
||||||
|
1. Invokes `AxeBuilder.analyze()` to run the accessibility scan against the page
|
||||||
|
1. Uses normal JUnit 5 test assertions to verify that there are no violations in the returned scan results
|
||||||
|
|
||||||
|
```java
|
||||||
|
import com.deque.html.axecore.playwright.*; // 1
|
||||||
|
import com.deque.html.axecore.utilities.axeresults.*;
|
||||||
|
|
||||||
|
import org.junit.jupiter.api.*;
|
||||||
|
import com.microsoft.playwright.*;
|
||||||
|
|
||||||
|
import static org.junit.jupiter.api.Assertions.*;
|
||||||
|
|
||||||
|
public class HomepageTests {
|
||||||
|
@Test // 2
|
||||||
|
void shouldNotHaveAutomaticallyDetectableAccessibilityIssues() throws Exception {
|
||||||
|
Playwright playwright = Playwright.create();
|
||||||
|
Browser browser = playwright.chromium().launch();
|
||||||
|
BrowserContext context = browser.newContext();
|
||||||
|
Page page = context.newPage();
|
||||||
|
|
||||||
|
page.navigate("https://your-site.com/"); // 3
|
||||||
|
|
||||||
|
AxeResults accessibilityScanResults = new AxeBuilder(page).analyze(); // 4
|
||||||
|
|
||||||
|
assertEquals(Collections.emptyList(), accessibilityScanResults.getViolations()); // 5
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Example 2: Configuring axe to scan a specific part of a page
|
||||||
|
|
||||||
|
`com.deque.html.axe-core/playwright` supports many configuration options for axe. You can specify these options by using a Builder pattern with the `AxeBuilder` class.
|
||||||
|
|
||||||
|
For example, you can use [`AxeBuilder.include()`](https://github.com/dequelabs/axe-core-maven-html/blob/develop/playwright/README.md#axebuilderincludeliststring-selector) to constrain an accessibility scan to only run against one specific part of a page.
|
||||||
|
|
||||||
|
`AxeBuilder.analyze()` will scan the page *in its current state* when you call it. To scan parts of a page that are revealed based on UI interactions, use [Locators](./locators.md) to interact with the page before invoking `analyze()`:
|
||||||
|
|
||||||
|
```java
|
||||||
|
@Test
|
||||||
|
void navigationMenuFlyoutShouldNotHaveAutomaticallyDetectableAccessibilityViolations() throws Exception {
|
||||||
|
page.navigate("https://your-site.com/");
|
||||||
|
|
||||||
|
page.locator("button[aria-label=\"Navigation Menu\"]").click();
|
||||||
|
|
||||||
|
// It is important to waitFor() the page to be in the desired
|
||||||
|
// state *before* running analyze(). Otherwise, axe might not
|
||||||
|
// find all the elements your test expects it to scan.
|
||||||
|
page.locator("#navigation-menu-flyout").waitFor();
|
||||||
|
|
||||||
|
AxeResults accessibilityScanResults = new AxeBuilder(page)
|
||||||
|
.include(Arrays.asList("#navigation-menu-flyout"))
|
||||||
|
.analyze();
|
||||||
|
|
||||||
|
assertEquals(Collections.emptyList(), accessibilityScanResults.getViolations());
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Example 3: Scanning for WCAG violations
|
||||||
|
|
||||||
|
By default, axe checks against a wide variety of accessibility rules. Some of these rules correspond to specific success criteria from the [Web Content Accessibility Guidelines (WCAG)](https://www.w3.org/TR/WCAG21/), and others are "best practice" rules that are not specifically required by any WCAG criteron.
|
||||||
|
|
||||||
|
You can constrain an accessibility scan to only run those rules which are "tagged" as corresponding to specific WCAG success criteria by using [`AxeBuilder.withTags()`](https://github.com/dequelabs/axe-core-maven-html/blob/develop/playwright/README.md#axebuilderwithtagsliststring-rules). For example, [Accessibility Insights for Web's Automated Checks](https://accessibilityinsights.io/docs/web/getstarted/fastpass/?referrer=playwright-accessibility-testing-java) only include axe rules that test for violations of WCAG A and AA success criteria; to match that behavior, you would use the tags `wcag2a`, `wcag2aa`, `wcag21a`, and `wcag21aa`.
|
||||||
|
|
||||||
|
Note that [automated testing cannot detect all types of WCAG violations](#disclaimer).
|
||||||
|
|
||||||
|
```java
|
||||||
|
AxeResults accessibilityScanResults = new AxeBuilder(page)
|
||||||
|
.withTags(Arrays.asList("wcag2a", "wcag2aa", "wcag21a", "wcag21aa"))
|
||||||
|
.analyze();
|
||||||
|
|
||||||
|
assertEquals(Collections.emptyList(), accessibilityScanResults.getViolations());
|
||||||
|
```
|
||||||
|
|
||||||
|
You can find a complete listing of the rule tags axe-core supports in [the "Axe-core Tags" section of the axe API documentation](https://www.deque.com/axe/core-documentation/api-documentation/#axe-core-tags).
|
||||||
|
|
||||||
|
## Handling known issues
|
||||||
|
|
||||||
|
A common question when adding accessibility tests to an application is "how do I suppress known violations?" The following examples demonstrate a few techniques you can use.
|
||||||
|
|
||||||
|
### Excluding individual elements from a scan
|
||||||
|
|
||||||
|
If your application contains a few specific elements with known issues, you can use [`AxeBuilder.exclude()`](https://github.com/dequelabs/axe-core-maven-html/blob/develop/playwright/README.md#axebuilderexcludeliststring-selector) to exclude them from being scanned until you're able to fix the issues.
|
||||||
|
|
||||||
|
This is usually the simplest option, but it has some important downsides:
|
||||||
|
* `exclude()` will exclude the specified elements *and all of their descendants*. Avoid using it with components that contain many children.
|
||||||
|
* `exclude()` will prevent *all* rules from running against the specified elements, not just the rules corresponding to known issues.
|
||||||
|
|
||||||
|
Here is an example of excluding one element from being scanned in one specific test:
|
||||||
|
|
||||||
|
```java
|
||||||
|
AxeResults accessibilityScanResults = new AxeBuilder(page)
|
||||||
|
.exclude(Arrays.asList("#element-with-known-issue"))
|
||||||
|
.analyze();
|
||||||
|
|
||||||
|
assertEquals(Collections.emptyList(), accessibilityScanResults.getViolations());
|
||||||
|
```
|
||||||
|
|
||||||
|
If the element in question is used repeatedly in many pages, consider [using a test fixture](#using-a-test-fixture-for-common-axe-configuration) to reuse the same `AxeBuilder` configuration across multiple tests.
|
||||||
|
|
||||||
|
### Disabling individual scan rules
|
||||||
|
|
||||||
|
If your application contains many different pre-existing violations of a specific rule, you can use [`AxeBuilder.disableRules()`](https://github.com/dequelabs/axe-core-maven-html/blob/develop/playwright/README.md#axebuilderdisablerulesliststring-rules) to temporarily disable individual rules until you're able to fix the issues.
|
||||||
|
|
||||||
|
You can find the rule IDs to pass to `disableRules()` in the `id` property of the violations you want to suppress. A [complete list of axe's rules](https://github.com/dequelabs/axe-core/blob/master/doc/rule-descriptions.md) can be found in `axe-core`'s documentation.
|
||||||
|
|
||||||
|
```java
|
||||||
|
AxeResults accessibilityScanResults = new AxeBuilder(page)
|
||||||
|
.disableRules(Arrays.asList("duplicate-id"))
|
||||||
|
.analyze();
|
||||||
|
|
||||||
|
assertEquals(Collections.emptyList(), accessibilityScanResults.getViolations());
|
||||||
|
```
|
||||||
|
|
||||||
|
### Using violation fingerprints to specific known issues
|
||||||
|
|
||||||
|
If you would like to allow for a more granular set of known issues, you can use the following pattern:
|
||||||
|
|
||||||
|
1. Perform an accessibility scan which is expected to find some known violations
|
||||||
|
1. Convert the violations into "violation fingerprint" objects
|
||||||
|
1. Assert that the set of fingerprints is equivalent to the expected ones
|
||||||
|
|
||||||
|
This approach avoids the downsides of using `AxeBuilder.exclude()` at the cost of slightly more complexity and fragility.
|
||||||
|
|
||||||
|
Here is an example of using fingerprints based on only rule IDs and "target" selectors pointing to each violation:
|
||||||
|
|
||||||
|
```java
|
||||||
|
@Test
|
||||||
|
shouldOnlyHaveAccessibilityViolationsMatchingKnownFingerprints() throws Exception {
|
||||||
|
page.navigate("https://your-site.com/");
|
||||||
|
|
||||||
|
AxeResults accessibilityScanResults = new AxeBuilder(page).analyze();
|
||||||
|
|
||||||
|
List<ViolationFingerprint> violationFingerprints = fingerprintsFromScanResults(accessibilityScanResults);
|
||||||
|
|
||||||
|
assertEquals(Arrays.asList(
|
||||||
|
new ViolationFingerprint("aria-roles", "[span[role=\"invalid\"]]"),
|
||||||
|
new ViolationFingerprint("color-contrast", "[li:nth-child(2) > span]"),
|
||||||
|
new ViolationFingerprint("label", "[input]")
|
||||||
|
), violationFingerprints);
|
||||||
|
}
|
||||||
|
|
||||||
|
// You can make your "fingerprint" as specific as you like. This one considers a violation to be
|
||||||
|
// "the same" if it corresponds the same Axe rule on the same element.
|
||||||
|
//
|
||||||
|
// Using a record type makes it easy to compare fingerprints with assertEquals
|
||||||
|
public record ViolationFingerprint(String ruleId, String target) { }
|
||||||
|
|
||||||
|
public List<ViolationFingerprint> fingerprintsFromScanResults(AxeResults results) {
|
||||||
|
return results.getViolations().stream()
|
||||||
|
// Each violation refers to one rule and multiple "nodes" which violate it
|
||||||
|
.flatMap(violation -> violation.getNodes().stream()
|
||||||
|
.map(node -> new ViolationFingerprint(
|
||||||
|
violation.getId(),
|
||||||
|
// Each node contains a "target", which is a CSS selector that uniquely identifies it
|
||||||
|
// If the page involves iframes or shadow DOMs, it may be a chain of CSS selectors
|
||||||
|
node.getTarget().toString()
|
||||||
|
)))
|
||||||
|
.collect(Collectors.toList());
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## Using a test fixture for common axe configuration
|
||||||
|
|
||||||
|
A [`TestFixtures` class](./test-runners#running-tests-in-parallel) is a good way to share common `AxeBuilder` configuration across many tests. Some scenarios where this might be useful include:
|
||||||
|
* Using a common set of rules among all of your tests
|
||||||
|
* Suppressing a known violation in a common element which appears in many different pages
|
||||||
|
* Attaching standalone accessibility reports consistently for many scans
|
||||||
|
|
||||||
|
The following example demonstrates extending the `TestFixtures` class from the [Test Runners example](./test-runners#running-tests-in-parallel) with a new fixture that contains some common `AxeBuilder` configuration.
|
||||||
|
|
||||||
|
### Creating a fixture
|
||||||
|
|
||||||
|
This example fixture creates an `AxeBuilder` object which is pre-configured with shared `withTags()` and `exclude()` configuration.
|
||||||
|
|
||||||
|
```java
|
||||||
|
class AxeTestFixtures extends TestFixtures {
|
||||||
|
AxeBuilder makeAxeBuilder() {
|
||||||
|
return new AxeBuilder(page)
|
||||||
|
.withTags(['wcag2a', 'wcag2aa', 'wcag21a', 'wcag21aa'])
|
||||||
|
.exclude('#commonly-reused-element-with-known-issue');
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Using a fixture
|
||||||
|
|
||||||
|
To use the fixture, replace the earlier examples' `new AxeBuilder(page)` with the newly defined `makeAxeBuilder` fixture:
|
||||||
|
|
||||||
|
```java
|
||||||
|
public class HomepageTests extends AxeTestFixtures {
|
||||||
|
@Test
|
||||||
|
void exampleUsingCustomFixture() throws Exception {
|
||||||
|
page.navigate("https://your-site.com/");
|
||||||
|
|
||||||
|
AxeResults accessibilityScanResults = makeAxeBuilder()
|
||||||
|
// Automatically uses the shared AxeBuilder configuration,
|
||||||
|
// but supports additional test-specific configuration too
|
||||||
|
.include('#specific-element-under-test')
|
||||||
|
.analyze();
|
||||||
|
|
||||||
|
assertEquals(Collections.emptyList(), accessibilityScanResults.getViolations());
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
@ -18,7 +18,7 @@ The following examples rely on the [`@axe-core/playwright`](https://npmjs.org/@a
|
||||||
|
|
||||||
Automated accessibility tests can detect some common accessibility problems such as missing or invalid properties. But many accessibility problems can only be discovered through manual testing. We recommend using a combination of automated testing, manual accessibility assessments, and inclusive user testing.
|
Automated accessibility tests can detect some common accessibility problems such as missing or invalid properties. But many accessibility problems can only be discovered through manual testing. We recommend using a combination of automated testing, manual accessibility assessments, and inclusive user testing.
|
||||||
|
|
||||||
For manual assessments, we recommend [Accessibility Insights for Web](https://accessibilityinsights.io/docs/web/overview/?referrer=playwright-accessibility-testing-js), a free and open source dev tool that walks you through assessing a website for [WCAG 2.1 AA](https://www.w3.org/WAI/WCAG21/quickref/?currentsidebar=%23col_customize&levels=aa) coverage.
|
For manual assessments, we recommend [Accessibility Insights for Web](https://accessibilityinsights.io/docs/web/overview/?referrer=playwright-accessibility-testing-js), a free and open source dev tool that walks you through assessing a website for [WCAG 2.1 AA](https://www.w3.org/WAI/WCAG21/quickref/?currentsidebar=%23col_customize&levels=aaa) coverage.
|
||||||
|
|
||||||
## Example accessibility tests
|
## Example accessibility tests
|
||||||
|
|
||||||
|
|
|
||||||
|
|
@ -39,7 +39,7 @@ using Microsoft.Playwright.NUnit;
|
||||||
using Microsoft.Playwright;
|
using Microsoft.Playwright;
|
||||||
using NUnit.Framework;
|
using NUnit.Framework;
|
||||||
|
|
||||||
namespace Playwright.TestingHarnessTest.NUnit
|
namespace PlaywrightTests
|
||||||
{
|
{
|
||||||
|
|
||||||
public class TestGitHubAPI : PlaywrightTest
|
public class TestGitHubAPI : PlaywrightTest
|
||||||
|
|
@ -91,7 +91,7 @@ using Microsoft.Playwright.NUnit;
|
||||||
using Microsoft.Playwright;
|
using Microsoft.Playwright;
|
||||||
using NUnit.Framework;
|
using NUnit.Framework;
|
||||||
|
|
||||||
namespace Playwright.TestingHarnessTest.NUnit
|
namespace PlaywrightTests
|
||||||
{
|
{
|
||||||
|
|
||||||
public class TestGitHubAPI : PlaywrightTest
|
public class TestGitHubAPI : PlaywrightTest
|
||||||
|
|
@ -216,7 +216,7 @@ using Microsoft.Playwright.NUnit;
|
||||||
using Microsoft.Playwright;
|
using Microsoft.Playwright;
|
||||||
using NUnit.Framework;
|
using NUnit.Framework;
|
||||||
|
|
||||||
namespace Playwright.TestingHarnessTest.NUnit
|
namespace PlaywrightTests
|
||||||
{
|
{
|
||||||
|
|
||||||
public class TestGitHubAPI : PlaywrightTest
|
public class TestGitHubAPI : PlaywrightTest
|
||||||
|
|
|
||||||
|
|
@ -89,7 +89,7 @@ class BrowserTypeExamples
|
||||||
* since: v1.8
|
* since: v1.8
|
||||||
- returns: <[Browser]>
|
- returns: <[Browser]>
|
||||||
|
|
||||||
This method attaches Playwright to an existing browser instance.
|
This method attaches Playwright to an existing browser instance. When connecting to another browser launched via `BrowserType.launchServer` in Node.js, the major and minor version needs to match the client version (1.2.3 → is compatible with 1.2.x).
|
||||||
|
|
||||||
### param: BrowserType.connect.wsEndpoint
|
### param: BrowserType.connect.wsEndpoint
|
||||||
* since: v1.10
|
* since: v1.10
|
||||||
|
|
@ -283,7 +283,7 @@ use a temporary directory instead.
|
||||||
* langs: js
|
* langs: js
|
||||||
- returns: <[BrowserServer]>
|
- returns: <[BrowserServer]>
|
||||||
|
|
||||||
Returns the browser app instance.
|
Returns the browser app instance. You can connect to it via [`method: BrowserType.connect`], which requires the major/minor client/server version to match (1.2.3 → is compatible with 1.2.x).
|
||||||
|
|
||||||
Launches browser server that client can connect to. An example of launching a browser executable and connecting to it
|
Launches browser server that client can connect to. An example of launching a browser executable and connecting to it
|
||||||
later:
|
later:
|
||||||
|
|
|
||||||
|
|
@ -53,7 +53,7 @@ using System.Threading.Tasks;
|
||||||
using Microsoft.Playwright.NUnit;
|
using Microsoft.Playwright.NUnit;
|
||||||
using NUnit.Framework;
|
using NUnit.Framework;
|
||||||
|
|
||||||
namespace Playwright.TestingHarnessTest.NUnit;
|
namespace PlaywrightTests;
|
||||||
|
|
||||||
public class ExampleTests : PageTest
|
public class ExampleTests : PageTest
|
||||||
{
|
{
|
||||||
|
|
|
||||||
|
|
@ -41,6 +41,18 @@ upon closing the browser context. This method throws when connected remotely.
|
||||||
Saves the video to a user-specified path. It is safe to call this method while the video
|
Saves the video to a user-specified path. It is safe to call this method while the video
|
||||||
is still in progress, or after the page has closed. This method waits until the page is closed and the video is fully saved.
|
is still in progress, or after the page has closed. This method waits until the page is closed and the video is fully saved.
|
||||||
|
|
||||||
|
## method: Video.saveAs
|
||||||
|
* langs: java
|
||||||
|
* since: v1.11
|
||||||
|
|
||||||
|
Saves the video to a user-specified path. This must be called after [`method: Page.close`] (or [`method: BrowserContext.close`]), otherwise an error will be thrown. This method waits until the video is fully saved.
|
||||||
|
|
||||||
|
## async method: Video.saveAs
|
||||||
|
* langs: python
|
||||||
|
* since: v1.11
|
||||||
|
|
||||||
|
Saves the video to a user-specified path. If using the sync API, this must be called after [`method: Page.close`] (or [`method: BrowserContext.close`]), otherwise an error will be thrown. If using the async API, it is safe to call this method while the video is still in progress, or after the page has closed. This method waits until the page is closed and the video is fully saved.
|
||||||
|
|
||||||
### param: Video.saveAs.path
|
### param: Video.saveAs.path
|
||||||
* since: v1.11
|
* since: v1.11
|
||||||
- `path` <[path]>
|
- `path` <[path]>
|
||||||
|
|
|
||||||
|
|
@ -6,80 +6,180 @@ title: "Test Generator"
|
||||||
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.
|
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
|
```bash js
|
||||||
npx playwright codegen wikipedia.org
|
npx playwright codegen playwright.dev
|
||||||
```
|
```
|
||||||
|
|
||||||
```bash java
|
```bash java
|
||||||
mvn exec:java -e -Dexec.mainClass=com.microsoft.playwright.CLI -Dexec.args="codegen wikipedia.org"
|
mvn exec:java -e -Dexec.mainClass=com.microsoft.playwright.CLI -Dexec.args="codegen playwright.dev"
|
||||||
```
|
```
|
||||||
|
|
||||||
```bash python
|
```bash python
|
||||||
playwright codegen wikipedia.org
|
playwright codegen playwright.dev
|
||||||
```
|
```
|
||||||
|
|
||||||
```bash csharp
|
```bash csharp
|
||||||
pwsh bin\Debug\netX\playwright.ps1 codegen wikipedia.org
|
pwsh bin\Debug\netX\playwright.ps1 codegen playwright.dev
|
||||||
```
|
```
|
||||||
|
|
||||||
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.
|
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 width="1916" alt="image" src="https://user-images.githubusercontent.com/13063165/177550119-4e202a56-7d8e-43ac-ad91-bf2f7b2579bd.png"/>
|
<img width="1183" alt="Codegen generating code for tests for playwright.dev website" src="https://user-images.githubusercontent.com/13063165/181852815-971c10da-0b55-4e54-8a73-77e1e825193c.png" />
|
||||||
|
|
||||||
|
|
||||||
|
## Emulate viewport size
|
||||||
|
|
||||||
|
Playwright opens a browser window with it's viewport set to a specific width and height and is not responsive as tests need to be run under the same conditions. Use the `--viewport` option to generate tests with a different viewport size.
|
||||||
|
|
||||||
|
```bash js
|
||||||
|
npx playwright codegen --viewport-size=800,600 playwright.dev
|
||||||
|
```
|
||||||
|
|
||||||
|
```bash java
|
||||||
|
mvn exec:java -e -Dexec.mainClass=com.microsoft.playwright.CLI -Dexec.args="codegen --viewport-size=800,600 playwright.dev"
|
||||||
|
```
|
||||||
|
|
||||||
|
```bash python
|
||||||
|
playwright codegen --viewport-size=800,600 playwright.dev
|
||||||
|
```
|
||||||
|
|
||||||
|
```bash csharp
|
||||||
|
pwsh bin\Debug\netX\playwright.ps1 codegen --viewport-size=800,600 playwright.dev
|
||||||
|
```
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
<img width="1409" alt="Codegen generating code for tests for playwright.dev website with a specific viewport" src="https://user-images.githubusercontent.com/13063165/182360039-6db79ad6-fe82-4fd6-900a-b5e25f7f720f.png" />
|
||||||
|
|
||||||
|
## Emulate devices
|
||||||
|
|
||||||
|
Record scripts and tests while emulating a mobile device using the `--device` option which sets the viewport size and user agent among others.
|
||||||
|
|
||||||
|
```bash js
|
||||||
|
npx playwright codegen --device="iPhone 11" playwright.dev
|
||||||
|
```
|
||||||
|
|
||||||
|
```bash java
|
||||||
|
mvn exec:java -e -Dexec.mainClass=com.microsoft.playwright.CLI -Dexec.args='codegen --device="iPhone 11" playwright.dev'
|
||||||
|
```
|
||||||
|
|
||||||
|
```bash python
|
||||||
|
playwright codegen --device="iPhone 11" playwright.dev
|
||||||
|
```
|
||||||
|
|
||||||
|
```bash csharp
|
||||||
|
pwsh bin\Debug\netX\playwright.ps1 codegen --device="iPhone 11" playwright.dev
|
||||||
|
```
|
||||||
|
|
||||||
|
<img width="1239" alt="Codegen generating code for tests for playwright.dev website emulated for iPhone 11" src="https://user-images.githubusercontent.com/13063165/182360089-9dc6d33d-480e-4bb2-86a3-fec51c1c228e.png" />
|
||||||
|
|
||||||
|
|
||||||
|
## Emulate color scheme
|
||||||
|
|
||||||
|
Record scripts and tests while emulating the color scheme with the `--color-scheme` option.
|
||||||
|
|
||||||
|
```bash js
|
||||||
|
npx playwright codegen --color-scheme=dark playwright.dev
|
||||||
|
```
|
||||||
|
|
||||||
|
```bash java
|
||||||
|
mvn exec:java -e -Dexec.mainClass=com.microsoft.playwright.CLI -Dexec.args="codegen --color-scheme=dark playwright.dev"
|
||||||
|
```
|
||||||
|
|
||||||
|
```bash python
|
||||||
|
playwright codegen --color-scheme=dark playwright.dev
|
||||||
|
```
|
||||||
|
|
||||||
|
```bash csharp
|
||||||
|
pwsh bin\Debug\netX\playwright.ps1 codegen --color-scheme=dark playwright.dev
|
||||||
|
```
|
||||||
|
|
||||||
|
<img width="1258" alt="Codegen generating code for tests for playwright.dev website in dark mode" src="https://user-images.githubusercontent.com/13063165/182359371-0bb4a7a2-abbb-4f73-8550-d67e0101f0ad.png" />
|
||||||
|
|
||||||
|
## Emulate geolocation, language and timezone
|
||||||
|
|
||||||
|
Record scripts and tests while emulating timezone, language & location using the `--timezone`, `--geolocation` and `--lang` options. Once page opens, click the "show your location" icon at them bottom right corner of the map to see geolocation in action.
|
||||||
|
|
||||||
|
```bash js
|
||||||
|
npx playwright codegen --timezone="Europe/Rome" --geolocation="41.890221,12.492348" --lang="it-IT" maps.google.com
|
||||||
|
```
|
||||||
|
|
||||||
|
```bash java
|
||||||
|
mvn exec:java -e -Dexec.mainClass=com.microsoft.playwright.CLI -Dexec.args='codegen --timezone="Europe/Rome" --geolocation="41.890221,12.492348" --lang="it-IT" maps.google.com'
|
||||||
|
```
|
||||||
|
|
||||||
|
```bash python
|
||||||
|
playwright codegen --timezone="Europe/Rome" --geolocation="41.890221,12.492348" --lang="it-IT" maps.google.com
|
||||||
|
```
|
||||||
|
|
||||||
|
```bash csharp
|
||||||
|
pwsh bin\Debug\netX\playwright.ps1 codegen --timezone="Europe/Rome" --geolocation="41.890221,12.492348" --lang="it-IT" maps.google.com
|
||||||
|
```
|
||||||
|
|
||||||
|
<img width="1276" alt="Codegen generating code for tests for google maps showing timezone, geoloation as Rome, Italy and in Italian language" src="https://user-images.githubusercontent.com/13063165/182394434-73e1c2a8-767e-411a-94e4-0912c1c50ecc.png" />
|
||||||
|
|
||||||
## Preserve authenticated state
|
## Preserve authenticated state
|
||||||
|
|
||||||
Run `codegen` with `--save-storage` to save [cookies](https://developer.mozilla.org/en-US/docs/Web/HTTP/Cookies) and [localStorage](https://developer.mozilla.org/en-US/docs/Web/API/Window/localStorage) at the end of the session. This is useful to separately record authentication step and reuse it later in the tests.
|
Run `codegen` with `--save-storage` to save [cookies](https://developer.mozilla.org/en-US/docs/Web/HTTP/Cookies) and [localStorage](https://developer.mozilla.org/en-US/docs/Web/API/Window/localStorage) at the end of the session. This is useful to separately record an authentication step and reuse it later in the tests.
|
||||||
|
|
||||||
|
After performing authentication and closing the browser, `auth.json` will contain the storage state.
|
||||||
|
|
||||||
```bash js
|
```bash js
|
||||||
npx playwright codegen --save-storage=auth.json
|
npx playwright codegen --save-storage=auth.json
|
||||||
# Perform authentication and exit.
|
|
||||||
# auth.json will contain the storage state.
|
|
||||||
```
|
```
|
||||||
|
|
||||||
```bash java
|
```bash java
|
||||||
mvn exec:java -e -Dexec.mainClass=com.microsoft.playwright.CLI -Dexec.args="codegen --save-storage=auth.json"
|
mvn exec:java -e -Dexec.mainClass=com.microsoft.playwright.CLI -Dexec.args="codegen --save-storage=auth.json"
|
||||||
# Perform authentication and exit.
|
|
||||||
# auth.json will contain the storage state.
|
|
||||||
```
|
```
|
||||||
|
|
||||||
```bash python
|
```bash python
|
||||||
playwright codegen --save-storage=auth.json
|
playwright codegen --save-storage=auth.json
|
||||||
# Perform authentication and exit.
|
|
||||||
# auth.json will contain the storage state.
|
|
||||||
```
|
```
|
||||||
|
|
||||||
```bash csharp
|
```bash csharp
|
||||||
pwsh bin\Debug\netX\playwright.ps1 codegen --save-storage=auth.json
|
pwsh bin\Debug\netX\playwright.ps1 codegen --save-storage=auth.json
|
||||||
# Perform authentication and exit.
|
|
||||||
# auth.json will contain the storage state.
|
|
||||||
```
|
```
|
||||||
|
|
||||||
Run with `--load-storage` to consume previously loaded storage. This way, all [cookies](https://developer.mozilla.org/en-US/docs/Web/HTTP/Cookies) and [localStorage](https://developer.mozilla.org/en-US/docs/Web/API/Window/localStorage) will be restored, bringing most web apps to the authenticated state.
|
<img width="1264" alt="Screenshot 2022-08-03 at 13 28 02" src="https://user-images.githubusercontent.com/13063165/182599605-df2fbd05-622b-4cd7-8a32-0abdfea7d38d.png" />
|
||||||
|
|
||||||
|
Run with `--load-storage` to consume previously loaded storage. This way, all [cookies](https://developer.mozilla.org/en-US/docs/Web/HTTP/Cookies) and [localStorage](https://developer.mozilla.org/en-US/docs/Web/API/Window/localStorage) will be restored, bringing most web apps to the authenticated state without the need to login again.
|
||||||
|
|
||||||
```bash js
|
```bash js
|
||||||
npx playwright open --load-storage=auth.json my.web.app
|
npx playwright codegen --load-storage=auth.json github.com/microsoft/playwright
|
||||||
npx playwright codegen --load-storage=auth.json my.web.app
|
|
||||||
# Perform actions in authenticated state.
|
|
||||||
```
|
```
|
||||||
|
|
||||||
```bash java
|
```bash java
|
||||||
mvn exec:java -e -Dexec.mainClass=com.microsoft.playwright.CLI -Dexec.args="open --load-storage=auth.json my.web.app"
|
mvn exec:java -e -Dexec.mainClass=com.microsoft.playwright.CLI -Dexec.args="codegen --load-storage=auth.json github.com/microsoft/playwright"
|
||||||
mvn exec:java -e -Dexec.mainClass=com.microsoft.playwright.CLI -Dexec.args="codegen --load-storage=auth.json my.web.app"
|
|
||||||
# Perform authentication and exit.
|
|
||||||
# auth.json will contain the storage state.
|
|
||||||
```
|
```
|
||||||
|
|
||||||
```bash python
|
```bash python
|
||||||
playwright open --load-storage=auth.json my.web.app
|
playwright codegen --load-storage=auth.json github.com/microsoft/playwright
|
||||||
playwright codegen --load-storage=auth.json my.web.app
|
|
||||||
# Perform actions in authenticated state.
|
|
||||||
```
|
```
|
||||||
|
|
||||||
```bash csharp
|
```bash csharp
|
||||||
pwsh bin\Debug\netX\playwright.ps1 open --load-storage=auth.json my.web.app
|
pwsh bin\Debug\netX\playwright.ps1 codegen --load-storage=auth.json github.com/microsoft/playwright
|
||||||
pwsh bin\Debug\netX\playwright.ps1 codegen --load-storage=auth.json my.web.app
|
|
||||||
# Perform actions in authenticated state.
|
|
||||||
```
|
```
|
||||||
|
|
||||||
|
<img width="1261" alt="Screenshot 2022-08-03 at 13 33 40" src="https://user-images.githubusercontent.com/13063165/182599680-05297b4e-c258-4416-8daa-b8637c1db120.png" />
|
||||||
|
|
||||||
|
Use the `open` command with `--load-storage` to open the saved `auth.json`.
|
||||||
|
|
||||||
|
```bash js
|
||||||
|
npx playwright open --load-storage=auth.json github.com/microsoft/playwright
|
||||||
|
```
|
||||||
|
|
||||||
|
```bash java
|
||||||
|
mvn exec:java -e -Dexec.mainClass=com.microsoft.playwright.CLI -Dexec.args="open --load-storage=auth.json github.com/microsoft/playwright"
|
||||||
|
```
|
||||||
|
|
||||||
|
```bash python
|
||||||
|
playwright open --load-storage=auth.json github.com/microsoft/playwright
|
||||||
|
```
|
||||||
|
|
||||||
|
```bash csharp
|
||||||
|
pwsh bin\Debug\netX\playwright.ps1 open --load-storage=auth.json github.com/microsoft/playwright
|
||||||
|
```
|
||||||
|
|
||||||
|
|
||||||
## Record using custom setup
|
## Record using custom setup
|
||||||
|
|
||||||
If you would like to use codegen in some non-standard setup (for example, use [`method: BrowserContext.route`]), it is possible to call [`method: Page.pause`] that will open a separate window with codegen controls.
|
If you would like to use codegen in some non-standard setup (for example, use [`method: BrowserContext.route`]), it is possible to call [`method: Page.pause`] that will open a separate window with codegen controls.
|
||||||
|
|
@ -174,76 +274,6 @@ var page = await context.NewPageAsync();
|
||||||
await page.PauseAsync();
|
await page.PauseAsync();
|
||||||
```
|
```
|
||||||
|
|
||||||
## Emulate devices
|
## What's Next
|
||||||
|
|
||||||
You can record scripts and tests while emulating a device.
|
- [See a trace of your tests](./trace-viewer.md)
|
||||||
|
|
||||||
```bash js
|
|
||||||
# Emulate iPhone 11.
|
|
||||||
npx playwright codegen --device="iPhone 11" wikipedia.org
|
|
||||||
```
|
|
||||||
|
|
||||||
```bash java
|
|
||||||
# Emulate iPhone 11.
|
|
||||||
mvn exec:java -e -Dexec.mainClass=com.microsoft.playwright.CLI -Dexec.args='codegen --device="iPhone 11" wikipedia.org'
|
|
||||||
```
|
|
||||||
|
|
||||||
```bash python
|
|
||||||
# Emulate iPhone 11.
|
|
||||||
playwright codegen --device="iPhone 11" wikipedia.org
|
|
||||||
```
|
|
||||||
|
|
||||||
```bash csharp
|
|
||||||
# Emulate iPhone 11.
|
|
||||||
pwsh bin\Debug\netX\playwright.ps1 codegen --device="iPhone 11" wikipedia.org
|
|
||||||
```
|
|
||||||
|
|
||||||
## Emulate color scheme and viewport size
|
|
||||||
|
|
||||||
You can also record scripts and tests while emulating various browser properties.
|
|
||||||
|
|
||||||
```bash js
|
|
||||||
# Emulate screen size and color scheme.
|
|
||||||
npx playwright codegen --viewport-size=800,600 --color-scheme=dark twitter.com
|
|
||||||
```
|
|
||||||
|
|
||||||
```bash java
|
|
||||||
# Emulate screen size and color scheme.
|
|
||||||
mvn exec:java -e -Dexec.mainClass=com.microsoft.playwright.CLI -Dexec.args="codegen --viewport-size=800,600 --color-scheme=dark twitter.com"
|
|
||||||
```
|
|
||||||
|
|
||||||
```bash python
|
|
||||||
# Emulate screen size and color scheme.
|
|
||||||
playwright codegen --viewport-size=800,600 --color-scheme=dark twitter.com
|
|
||||||
```
|
|
||||||
|
|
||||||
```bash csharp
|
|
||||||
# Emulate screen size and color scheme.
|
|
||||||
pwsh bin\Debug\netX\playwright.ps1 codegen --viewport-size=800,600 --color-scheme=dark twitter.com
|
|
||||||
```
|
|
||||||
|
|
||||||
## Emulate geolocation, language and timezone
|
|
||||||
|
|
||||||
```bash js
|
|
||||||
# Emulate timezone, language & location
|
|
||||||
# Once page opens, click the "my location" button to see geolocation in action
|
|
||||||
npx playwright codegen --timezone="Europe/Rome" --geolocation="41.890221,12.492348" --lang="it-IT" maps.google.com
|
|
||||||
```
|
|
||||||
|
|
||||||
```bash java
|
|
||||||
# Emulate timezone, language & location
|
|
||||||
# Once page opens, click the "my location" button to see geolocation in action
|
|
||||||
mvn exec:java -e -Dexec.mainClass=com.microsoft.playwright.CLI -Dexec.args='codegen --timezone="Europe/Rome" --geolocation="41.890221,12.492348" --lang="it-IT" maps.google.com'
|
|
||||||
```
|
|
||||||
|
|
||||||
```bash python
|
|
||||||
# Emulate timezone, language & location
|
|
||||||
# Once page opens, click the "my location" button to see geolocation in action
|
|
||||||
playwright codegen --timezone="Europe/Rome" --geolocation="41.890221,12.492348" --lang="it-IT" maps.google.com
|
|
||||||
```
|
|
||||||
|
|
||||||
```bash csharp
|
|
||||||
# Emulate timezone, language & location
|
|
||||||
# Once page opens, click the "my location" button to see geolocation in action
|
|
||||||
pwsh bin\Debug\netX\playwright.ps1 codegen --timezone="Europe/Rome" --geolocation="41.890221,12.492348" --lang="it-IT" maps.google.com
|
|
||||||
```
|
|
||||||
|
|
|
||||||
156
docs/src/debug-selectors.md
Normal file
156
docs/src/debug-selectors.md
Normal file
|
|
@ -0,0 +1,156 @@
|
||||||
|
---
|
||||||
|
id: debug-selectors
|
||||||
|
title: "Debugging Selectors"
|
||||||
|
---
|
||||||
|
|
||||||
|
Playwright will throw a timeout exception like `locator.click: Timeout 30000ms exceeded` when an element does not exist on the page. There are multiple ways of debugging selectors:
|
||||||
|
|
||||||
|
- [Playwright Inspector](#using-playwright-inspector) to step over each Playwright API call to inspect the page.
|
||||||
|
- [Browser DevTools](#using-devtools) to inspect selectors with the DevTools element panel.
|
||||||
|
- [Trace Viewer](./trace-viewer.md) to see what the page looked like during the test run.
|
||||||
|
- [Verbose API logs](#verbose-api-logs) shows [actionability checks](./actionability.md) when locating the element.
|
||||||
|
|
||||||
|
## Using Playwright Inspector
|
||||||
|
|
||||||
|
Open the [Playwright Inspector](./debug.md) and 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>
|
||||||
|
|
||||||
|
## Using DevTools
|
||||||
|
|
||||||
|
You can also use the following API inside the Developer Tools Console of any browser.
|
||||||
|
|
||||||
|
When running in Debug Mode with `PWDEBUG=console`, a `playwright` object is available in Developer tools console.
|
||||||
|
|
||||||
|
1. Run with `PWDEBUG=console`
|
||||||
|
1. Setup a breakpoint to pause the execution
|
||||||
|
1. Open the console panel in browser developer tools
|
||||||
|
|
||||||
|
<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:
|
||||||
|
|
||||||
|
```txt
|
||||||
|
> playwright.$('.auth-form >> text=Log in');
|
||||||
|
|
||||||
|
<button>Log in</button>
|
||||||
|
```
|
||||||
|
|
||||||
|
### playwright.$$(selector)
|
||||||
|
|
||||||
|
Same as `playwright.$`, but returns all matching elements.
|
||||||
|
|
||||||
|
```txt
|
||||||
|
> 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).
|
||||||
|
|
||||||
|
```txt
|
||||||
|
> playwright.inspect('text=Log in')
|
||||||
|
```
|
||||||
|
|
||||||
|
### playwright.locator(selector)
|
||||||
|
|
||||||
|
Query Playwright element using the actual Playwright query engine, for example:
|
||||||
|
|
||||||
|
```txt
|
||||||
|
> playwright.locator('.auth-form', { hasText: 'Log in' });
|
||||||
|
|
||||||
|
> Locator ()
|
||||||
|
> - element: button
|
||||||
|
> - elements: [button]
|
||||||
|
```
|
||||||
|
|
||||||
|
### playwright.highlight(selector)
|
||||||
|
|
||||||
|
Highlight the first occurrence of the locator:
|
||||||
|
|
||||||
|
```txt
|
||||||
|
> playwright.hightlight('.auth-form');
|
||||||
|
```
|
||||||
|
|
||||||
|
### playwright.clear()
|
||||||
|
|
||||||
|
```txt
|
||||||
|
> playwright.clear()
|
||||||
|
```
|
||||||
|
|
||||||
|
Clear existing highlights.
|
||||||
|
|
||||||
|
### playwright.selector(element)
|
||||||
|
|
||||||
|
Generates selector for the given element.
|
||||||
|
|
||||||
|
```txt
|
||||||
|
> playwright.selector($0)
|
||||||
|
|
||||||
|
"div[id="glow-ingress-block"] >> text=/.*Hello.*/"
|
||||||
|
```
|
||||||
|
|
||||||
|
## Verbose API logs
|
||||||
|
|
||||||
|
Playwright supports verbose logging with the `DEBUG` environment variable.
|
||||||
|
|
||||||
|
```bash tab=bash-bash lang=js
|
||||||
|
DEBUG=pw:api npm run test
|
||||||
|
```
|
||||||
|
|
||||||
|
```batch tab=bash-batch lang=js
|
||||||
|
set DEBUG=pw:api
|
||||||
|
npm run test
|
||||||
|
```
|
||||||
|
|
||||||
|
```powershell tab=bash-powershell lang=js
|
||||||
|
$env:DEBUG="pw:api"
|
||||||
|
npm run test
|
||||||
|
```
|
||||||
|
|
||||||
|
```bash tab=bash-bash lang=java
|
||||||
|
DEBUG=pw:api mvn test
|
||||||
|
```
|
||||||
|
|
||||||
|
```batch tab=bash-batch lang=java
|
||||||
|
set DEBUG=pw:api
|
||||||
|
mvn test
|
||||||
|
```
|
||||||
|
|
||||||
|
```powershell tab=bash-powershell lang=java
|
||||||
|
$env:DEBUG="pw:api"
|
||||||
|
mvn test
|
||||||
|
```
|
||||||
|
|
||||||
|
```bash tab=bash-bash lang=python
|
||||||
|
DEBUG=pw:api pytest -s
|
||||||
|
```
|
||||||
|
|
||||||
|
```batch tab=bash-batch lang=python
|
||||||
|
set DEBUG=pw:api
|
||||||
|
pytest -s
|
||||||
|
```
|
||||||
|
|
||||||
|
```powershell tab=bash-powershell lang=python
|
||||||
|
$env:DEBUG="pw:api"
|
||||||
|
pytest -s
|
||||||
|
```
|
||||||
|
|
||||||
|
```bash tab=bash-bash lang=csharp
|
||||||
|
DEBUG=pw:api dotnet run
|
||||||
|
```
|
||||||
|
|
||||||
|
```batch tab=bash-batch lang=csharp
|
||||||
|
set DEBUG=pw:api
|
||||||
|
dotnet run
|
||||||
|
```
|
||||||
|
|
||||||
|
```powershell tab=bash-powershell lang=csharp
|
||||||
|
$env:DEBUG="pw:api"
|
||||||
|
dotnet run
|
||||||
|
```
|
||||||
|
|
@ -3,8 +3,7 @@ id: debug
|
||||||
title: "Debugging Tests"
|
title: "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.
|
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. For debugging selectors, see [here](./debug-selectors.md).
|
||||||
|
|
||||||
|
|
||||||
## Playwright Inspector
|
## Playwright Inspector
|
||||||
|
|
||||||
|
|
@ -14,21 +13,22 @@ Playwright Inspector is a GUI tool that helps authoring and debugging Playwright
|
||||||
|
|
||||||
There are several ways of opening Playwright Inspector:
|
There are several ways of opening Playwright Inspector:
|
||||||
|
|
||||||
### Using --debug
|
### --debug
|
||||||
* langs: js
|
* langs: js
|
||||||
|
|
||||||
- Debugging all Tests
|
* Debugging all Tests
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
npx playwright test --debug
|
npx playwright test --debug
|
||||||
```
|
```
|
||||||
- Debugging one test
|
|
||||||
|
* Debugging one test
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
npx playwright test example --debug
|
npx playwright test example --debug
|
||||||
```
|
```
|
||||||
|
|
||||||
### Using PWDEBUG
|
### PWDEBUG
|
||||||
|
|
||||||
Set the `PWDEBUG` environment variable to run your scripts in debug mode. This
|
Set the `PWDEBUG` environment variable to run your scripts in debug mode. This
|
||||||
configures Playwright for debugging and opens the inspector.
|
configures Playwright for debugging and opens the inspector.
|
||||||
|
|
@ -95,13 +95,15 @@ configures Playwright for debugging and opens the inspector.
|
||||||
```
|
```
|
||||||
|
|
||||||
Additional useful defaults are configured when `PWDEBUG=1` is set:
|
Additional useful defaults are configured when `PWDEBUG=1` is set:
|
||||||
|
|
||||||
- Browsers launch in the headed mode
|
- Browsers launch in the headed mode
|
||||||
- Default timeout is set to 0 (= no timeout)
|
- Default timeout is set to 0 (= no timeout)
|
||||||
|
|
||||||
Using `PWDEBUG=console` will configure the browser for debugging in Developer tools console:
|
Using `PWDEBUG=console` will configure the browser for debugging in Developer tools console:
|
||||||
* **Runs headed**: Browsers always launch in headed mode
|
|
||||||
* **Disables timeout**: Sets default timeout to 0 (= no timeout)
|
- **Runs headed**: Browsers always launch in headed mode
|
||||||
* **Console helper**: Configures a `playwright` object in the browser to generate and highlight
|
- **Disables timeout**: Sets default timeout to 0 (= no timeout)
|
||||||
|
- **Console helper**: Configures a `playwright` object in the browser to generate and highlight
|
||||||
[Playwright selectors](./selectors.md). This can be used to verify text or
|
[Playwright selectors](./selectors.md). This can be used to verify text or
|
||||||
composite selectors.
|
composite selectors.
|
||||||
|
|
||||||
|
|
@ -147,27 +149,7 @@ $env:PWDEBUG="console"
|
||||||
pytest -s
|
pytest -s
|
||||||
```
|
```
|
||||||
|
|
||||||
#### Selectors in Developer Tools Console
|
### page.pause
|
||||||
|
|
||||||
When running in Debug Mode with `PWDEBUG=console`, a `playwright` object is available in Developer tools console.
|
|
||||||
|
|
||||||
1. Run with `PWDEBUG=console`
|
|
||||||
1. Setup a breakpoint to pause the execution
|
|
||||||
1. Open the console panel in browser developer tools
|
|
||||||
1. Use the `playwright` API
|
|
||||||
* `playwright.$(selector)`: Highlight the first occurrence of the selector. This reflects
|
|
||||||
how `page.$` would see the page.
|
|
||||||
* `playwright.$$(selector)`: Highlight all occurrences of the selector. This reflects
|
|
||||||
how `page.$$` would see the page.
|
|
||||||
* `playwright.inspect(selector)`: Inspect the selector in the Elements panel.
|
|
||||||
* `playwright.locator(selector)`: Highlight the first occurrence of the locator.
|
|
||||||
* `playwright.clear()`: Clear existing highlights.
|
|
||||||
* `playwright.selector(element)`: Generate a selector that points to the element.
|
|
||||||
|
|
||||||
<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>
|
|
||||||
|
|
||||||
|
|
||||||
### Using page.pause
|
|
||||||
|
|
||||||
Call [`method: Page.pause`] method from your script when running in headed browser.
|
Call [`method: Page.pause`] method from your script when running in headed browser.
|
||||||
|
|
||||||
|
|
@ -196,8 +178,8 @@ Call [`method: Page.pause`] method from your script when running in headed brows
|
||||||
await page.PauseAsync();
|
await page.PauseAsync();
|
||||||
```
|
```
|
||||||
|
|
||||||
|
Use `open` or `codegen` commands in the Playwright [CLI](./cli.md):
|
||||||
|
|
||||||
- Use `open` or `codegen` commands in the Playwright [CLI](./cli.md):
|
|
||||||
```bash js
|
```bash js
|
||||||
npx playwright codegen wikipedia.org
|
npx playwright codegen wikipedia.org
|
||||||
```
|
```
|
||||||
|
|
@ -214,19 +196,24 @@ Call [`method: Page.pause`] method from your script when running in headed brows
|
||||||
pwsh bin\Debug\netX\playwright.ps1 codegen wikipedia.org
|
pwsh bin\Debug\netX\playwright.ps1 codegen wikipedia.org
|
||||||
```
|
```
|
||||||
|
|
||||||
## Stepping through the Playwright script
|
### Stepping through the Playwright script
|
||||||
|
|
||||||
When `PWDEBUG=1` is set, Playwright Inspector window will be opened and the script will be
|
The Inspector opens up a browser window highlighting the selectors as you step through each line of the test. 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 they pass.
|
||||||
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>
|
<img width="557" alt="Paused on line" src="https://user-images.githubusercontent.com/883973/108614337-71761580-73ae-11eb-9f61-3d29c52c9520.png"></img>
|
||||||
|
|
||||||
|
Use the toolbar to play the test or 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>
|
||||||
|
|
||||||
Now we know what action is about to be performed and we can look into the details on that
|
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:
|
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>
|
<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:
|
### Actionability Logs
|
||||||
|
|
||||||
|
By the time Playwright has paused on that click action, it has already performed [actionability checks](./actionability.md) 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>
|
<img width="712" alt="Action log" src="https://user-images.githubusercontent.com/883973/108614564-72a84200-73b0-11eb-9de2-828b28d78b36.png"></img>
|
||||||
|
|
||||||
|
|
@ -234,26 +221,26 @@ 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>
|
<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`):
|
### Exploring selectors
|
||||||
|
|
||||||
<center><img width="98" alt="Stepping toolbar" src="https://user-images.githubusercontent.com/883973/108614389-f9f4b600-73ae-11eb-8df2-8d9ce9da5d5c.png"></img></center>
|
|
||||||
|
|
||||||
|
Use the Explore button to hover over an element on the page and explore it's selector by clicking on it. You can then copy this selector into your tests and rerun your tests to see if they now pass with this selector. You can also debug selectors, checkout our [debugging selectors](./debug-selectors.md) guide for more details.
|
||||||
|
|
||||||
## Browser Developer Tools
|
## Browser Developer Tools
|
||||||
|
|
||||||
You can use browser developer tools in Chromium, Firefox and WebKit while running
|
You can use browser developer tools in Chromium, Firefox and WebKit while running
|
||||||
a Playwright script in headed mode. Developer tools help to:
|
a Playwright script in headed mode. Developer tools help to:
|
||||||
|
|
||||||
* Inspect the DOM tree and **find element selectors**
|
- 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))
|
- **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
|
- 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>
|
<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
|
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.
|
and inspect the page in Developer tools. It will also open Playwright Inspector to help with debugging.
|
||||||
|
|
||||||
**For Chromium**: you can also open developer tools through a launch option.
|
**For Chromium**: you can also open developer tools through a launch option.
|
||||||
|
|
||||||
```js
|
```js
|
||||||
await chromium.launch({ devtools: true });
|
await chromium.launch({ devtools: true });
|
||||||
```
|
```
|
||||||
|
|
@ -282,79 +269,7 @@ await using var browser = await playwright.Chromium.LaunchAsync(new()
|
||||||
prevent the Playwright script from executing any further.
|
prevent the Playwright script from executing any further.
|
||||||
:::
|
:::
|
||||||
|
|
||||||
## Debugging Selectors
|
## Headed mode
|
||||||
|
|
||||||
- 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,
|
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
|
use `headless: false` as a launch option. You can also use the [`option: slowMo`] option
|
||||||
|
|
@ -372,12 +287,10 @@ chromium.launch(new BrowserType.LaunchOptions() // or firefox, webkit
|
||||||
|
|
||||||
```python async
|
```python async
|
||||||
await chromium.launch(headless=False, slow_mo=100) # or firefox, webkit
|
await chromium.launch(headless=False, slow_mo=100) # or firefox, webkit
|
||||||
|
|
||||||
```
|
```
|
||||||
|
|
||||||
```python sync
|
```python sync
|
||||||
chromium.launch(headless=False, slow_mo=100) # or firefox, webkit
|
chromium.launch(headless=False, slow_mo=100) # or firefox, webkit
|
||||||
|
|
||||||
```
|
```
|
||||||
|
|
||||||
```csharp
|
```csharp
|
||||||
|
|
@ -389,67 +302,4 @@ await using var browser = await playwright.Chromium.LaunchAsync(new()
|
||||||
});
|
});
|
||||||
```
|
```
|
||||||
|
|
||||||
## Verbose API logs
|
|
||||||
|
|
||||||
Playwright supports verbose logging with the `DEBUG` environment variable.
|
|
||||||
|
|
||||||
```bash tab=bash-bash lang=js
|
|
||||||
DEBUG=pw:api npm run test
|
|
||||||
```
|
|
||||||
|
|
||||||
```batch tab=bash-batch lang=js
|
|
||||||
set DEBUG=pw:api
|
|
||||||
npm run test
|
|
||||||
```
|
|
||||||
|
|
||||||
```powershell tab=bash-powershell lang=js
|
|
||||||
$env:DEBUG="pw:api"
|
|
||||||
npm run test
|
|
||||||
```
|
|
||||||
|
|
||||||
```bash tab=bash-bash lang=java
|
|
||||||
DEBUG=pw:api mvn test
|
|
||||||
```
|
|
||||||
|
|
||||||
```batch tab=bash-batch lang=java
|
|
||||||
set DEBUG=pw:api
|
|
||||||
mvn test
|
|
||||||
```
|
|
||||||
|
|
||||||
```powershell tab=bash-powershell lang=java
|
|
||||||
$env:DEBUG="pw:api"
|
|
||||||
mvn test
|
|
||||||
```
|
|
||||||
|
|
||||||
```bash tab=bash-bash lang=python
|
|
||||||
DEBUG=pw:api pytest -s
|
|
||||||
```
|
|
||||||
|
|
||||||
```batch tab=bash-batch lang=python
|
|
||||||
set DEBUG=pw:api
|
|
||||||
pytest -s
|
|
||||||
```
|
|
||||||
|
|
||||||
```powershell tab=bash-powershell lang=python
|
|
||||||
$env:DEBUG="pw:api"
|
|
||||||
pytest -s
|
|
||||||
```
|
|
||||||
|
|
||||||
```bash tab=bash-bash lang=csharp
|
|
||||||
DEBUG=pw:api dotnet run
|
|
||||||
```
|
|
||||||
|
|
||||||
```batch tab=bash-batch lang=csharp
|
|
||||||
set DEBUG=pw:api
|
|
||||||
dotnet run
|
|
||||||
```
|
|
||||||
|
|
||||||
```powershell tab=bash-powershell lang=csharp
|
|
||||||
$env:DEBUG="pw:api"
|
|
||||||
dotnet run
|
|
||||||
```
|
|
||||||
|
|
||||||
## What's Next
|
|
||||||
|
|
||||||
- [Generate tests with Codegen](./codegen.md)
|
|
||||||
- [See a trace of your tests](./trace-viewer.md)
|
|
||||||
|
|
@ -121,6 +121,7 @@ It is recommended to always pin your Docker image to a specific version if possi
|
||||||
### Base images
|
### Base images
|
||||||
|
|
||||||
We currently publish images based on the following [Ubuntu](https://hub.docker.com/_/ubuntu) versions:
|
We currently publish images based on the following [Ubuntu](https://hub.docker.com/_/ubuntu) versions:
|
||||||
|
- **Ubuntu 22.04 LTS** (Jammy Jellyfish), image tags include `jammy` (not published for Java and .NET)
|
||||||
- **Ubuntu 20.04 LTS** (Focal Fossa), image tags include `focal`
|
- **Ubuntu 20.04 LTS** (Focal Fossa), image tags include `focal`
|
||||||
- **Ubuntu 18.04 LTS** (Bionic Beaver), image tags include `bionic` (not published for Java and .NET)
|
- **Ubuntu 18.04 LTS** (Bionic Beaver), image tags include `bionic` (not published for Java and .NET)
|
||||||
|
|
||||||
|
|
|
||||||
|
|
@ -11,7 +11,7 @@ Get started by installing Playwright and generating a test to see it in action.
|
||||||
|
|
||||||
Install the [VS Code extension from the marketplace](https://marketplace.visualstudio.com/items?itemName=ms-playwright.playwright).
|
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/182146928-b2a46ce5-3008-409c-be10-d2b255bd5e91.jpeg"></img>
|
||||||
|
|
||||||
Once installed, open the command panel and type:
|
Once installed, open the command panel and type:
|
||||||
|
|
||||||
|
|
@ -21,63 +21,76 @@ Install Playwright
|
||||||
|
|
||||||
<img width="538" alt="image" src="https://user-images.githubusercontent.com/13063165/177199115-ce90eb84-f12a-4b95-bd3a-17ff870fcec2.png"></img>
|
<img width="538" alt="image" src="https://user-images.githubusercontent.com/13063165/177199115-ce90eb84-f12a-4b95-bd3a-17ff870fcec2.png"></img>
|
||||||
|
|
||||||
Select "Test: Install Playwright" and 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. You can also choose if you would like to have a GitHub Actions setup to run your tests on CI.
|
Select "Test: Install Playwright" and Choose the browsers you would like to run your tests on. These can be later configured in the [playwright.config](./test-configuration.md) file. You can also choose if you would like to have a GitHub Actions setup to run your tests on CI.
|
||||||
|
|
||||||
## Generating Tests with Codegen
|
|
||||||
|
|
||||||
[CodeGen](./codegen.md) will auto generate your tests for you and is a great way to quickly get started. Click on the Testing icon in the left menu to open the testing sidebar.
|
|
||||||
|
|
||||||
### Recording a Test
|
|
||||||
|
|
||||||
To record a test click on the record icon. This will create a `test-1.spec.ts` file as well as open up a browser window.
|
|
||||||
|
|
||||||
<img width="810" alt="image" src="https://user-images.githubusercontent.com/13063165/177197869-40b32235-ae7c-4a6e-8b7e-e69aea17ea1b.png"></img>
|
|
||||||
|
|
||||||
### Generating a Test
|
|
||||||
|
|
||||||
As you interact with the page Codegen will generate the test for you in the newly created file in VS Code. When you hover over an element Playwright will highlight the element and show the [selector](./selectors.md) underneath it.
|
|
||||||
|
|
||||||
<img width="958" alt="image" src="https://user-images.githubusercontent.com/13063165/177199982-42dc316f-3438-48b1-a6a6-417be77be658.png"></img>
|
|
||||||
|
|
||||||
|
|
||||||
## Running Tests
|
## Running Tests
|
||||||
|
|
||||||
You can run a single test by clicking the green triangle next to your test block to run your test. Playwright will run through each line of the test and when it finishes you will see a green tick next to your test block as well as the time it took to run the test.
|
You can run a single test by clicking the green triangle next to your test block to run your test. Playwright will run through each line of the test and when it finishes you will see a green tick next to your test block as well as the time it took to run the test.
|
||||||
|
|
||||||
<img width="813" alt="image" src="https://user-images.githubusercontent.com/13063165/177201109-e0a17553-88cc-496e-a717-9a60247db935.png"></img>
|
|
||||||
|
|
||||||
### View All Tests
|
|
||||||
|
|
||||||
View all tests in the testing sidebar and extend the tests by clicking on each test. Tests that have not been run will not have the green check next to them.
|
<img width="750" alt="image" src="https://user-images.githubusercontent.com/13063165/182153398-101bf809-deca-40f8-9ac7-314eab2ff119.png" />
|
||||||
|
|
||||||
<img width="812" alt="image" src="https://user-images.githubusercontent.com/13063165/177201231-f26e11da-2860-43fa-9a31-b04bba55d52e.png" />
|
### View and Run All Tests
|
||||||
|
|
||||||
### Run All Tests
|
View all tests in the testing sidebar and extend the tests by clicking on each test. Tests that have not been run will not have the green check next to them. Run all tests by clicking on the white triangle as you hover over the tests in the testing sidebar.
|
||||||
|
|
||||||
Run all tests by clicking on the white triangle as you hover over the tests in the testing sidebar.
|
<img width="755" alt="image" src="https://user-images.githubusercontent.com/13063165/182154055-6ff7af95-3787-475e-b0c0-8aa521aaa31b.png" />
|
||||||
|
|
||||||
<img width="252" alt="image" src="https://user-images.githubusercontent.com/13063165/178029941-d9555c43-0966-4699-8739-612a9664e604.png" />
|
|
||||||
|
|
||||||
### Run Tests on Specific Browsers
|
### Run Tests on Specific Browsers
|
||||||
|
|
||||||
The VS Code test runner runs your tests on the default browser of Chrome. To run on other/multiple browsers click the play button's dropdown and choose the option of "Select Default Profile" and select the browsers you wish to run your tests on.
|
The VS Code test runner runs your tests on the default browser of Chrome. To run on other/multiple browsers click the play button's dropdown and choose the option of "Select Default Profile" and select the browsers you wish to run your tests on.
|
||||||
|
|
||||||
<img width="506" alt="image" src="https://user-images.githubusercontent.com/13063165/178030111-3c422349-a501-4190-9ad6-ec0bdc187b9e.png" />
|
<img width="753" alt="image" src="https://user-images.githubusercontent.com/13063165/182154251-89f8d4f1-a9c3-42bc-9659-7db6412e96fe.png" />
|
||||||
|
|
||||||
## Debugging Tests
|
## Debugging Tests
|
||||||
|
|
||||||
With the VS Code extension you can debug your tests right in VS Code see error messages and create breakpoints. Click next to the line number so a red dot appears and then run the tests in debug mode by right clicking on the line next to the test you want to run. A browser window will open and the test will run and pause at where the breakpoint is set.
|
With the VS Code extension you can debug your tests right in VS Code see error messages, create breakpoints and live debug your tests.
|
||||||
|
|
||||||
<img width="1025" alt="image" src="https://user-images.githubusercontent.com/13063165/178027941-0d9d5f88-2426-43fb-b204-62a2add27415.png" />
|
### Error Messages
|
||||||
|
|
||||||
### Live Debugging with VS Code
|
If your test fails VS Code will show you error messages right in the editor showing what was expected, what was received as well as a complete call log.
|
||||||
|
|
||||||
Modify your test right in VS Code while debugging and Playwright Test 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="848" alt="image" src="https://user-images.githubusercontent.com/13063165/182155225-d91ec237-f69e-4ace-9a5f-a149800aba75.png" />
|
||||||
|
|
||||||
|
### Run in Debug Mode
|
||||||
|
|
||||||
|
To set a breakpoint click next to the line number where you want the breakpoint to be until a red dot appears. Run the tests in debug mode by right clicking on the line next to the test you want to run. A browser window will open and the test will run and pause at where the breakpoint is set.
|
||||||
|
|
||||||
|
<img width="847" alt="image" src="https://user-images.githubusercontent.com/13063165/182156149-f683f62d-9555-4ce2-93d2-e80de8087411.png" />
|
||||||
|
|
||||||
|
|
||||||
|
### Live Debugging
|
||||||
|
|
||||||
|
You can modify your test right in VS Code while debugging and Playwright will highlight the selector in the browser. This is a great way of seeing if the selector exits or if there is more than one result. You can step through the tests, pause the test and rerun the tests from the menu in VS Code.
|
||||||
|
|
||||||
|
<img width="858" alt="image" src="https://user-images.githubusercontent.com/13063165/182157241-c8da5eff-edbc-4ae1-80e3-8e42fa5fe659.png" />
|
||||||
|
|
||||||
|
|
||||||
|
## Generating Tests
|
||||||
|
|
||||||
|
CodeGen will auto generate your tests for you as you perform actions in the browser and is a great way to quickly get started. The viewport for the browser window is set to a specific width and height. See the [configuration guide](./test-configuration.md) to change the viewport or emulate different environments.
|
||||||
|
|
||||||
|
### Recording a Test
|
||||||
|
|
||||||
|
To record a test click on the record icon. This will create a `test-1.spec.ts` file as well as open up a browser window.
|
||||||
|
|
||||||
|
|
||||||
|
<img width="798" alt="image" src="https://user-images.githubusercontent.com/13063165/182149486-a30fbd3f-5e88-4ac2-b1df-4e33d4a893c7.png" />
|
||||||
|
|
||||||
|
### Selector Highlighting
|
||||||
|
|
||||||
|
As you interact with the page Codegen will generate the test for you in the newly created file in VS Code. When you hover over an element Playwright will highlight the element and show the [selector](./selectors.md) underneath it.
|
||||||
|
|
||||||
|
<img width="860" alt="image" src="https://user-images.githubusercontent.com/13063165/182151374-03273172-38cd-4f27-add5-cb3d3cdc7bcd.png" />
|
||||||
|
|
||||||
|
|
||||||
<img width="1044" alt="image" src="https://user-images.githubusercontent.com/13063165/178029249-e0a85f53-b8d4-451f-b3e5-df62b0c57929.png" />
|
|
||||||
|
|
||||||
## What's next
|
## What's next
|
||||||
|
|
||||||
- [Write tests using web first assertions, page fixtures and locators](./writing-tests.md)
|
- [Write tests using web first assertions, page fixtures and locators](./writing-tests.md)
|
||||||
|
- [See test reports](./running-tests.md#test-reports)
|
||||||
- [See a trace of your tests](./trace-viewer.md)
|
- [See a trace of your tests](./trace-viewer.md)
|
||||||
|
|
@ -1,236 +0,0 @@
|
||||||
---
|
|
||||||
id: inspector
|
|
||||||
title: "Inspector"
|
|
||||||
---
|
|
||||||
|
|
||||||
Playwright Inspector is a GUI tool that helps authoring and debugging Playwright scripts.
|
|
||||||
|
|
||||||
<img width="712" alt="Playwright Inspector" src="https://user-images.githubusercontent.com/883973/108614092-8c478a80-73ac-11eb-9597-67dfce110e00.png"></img>
|
|
||||||
|
|
||||||
<!-- TOC -->
|
|
||||||
|
|
||||||
## Open Playwright Inspector
|
|
||||||
|
|
||||||
There are several ways of opening Playwright Inspector:
|
|
||||||
|
|
||||||
- Set the `PWDEBUG` environment variable to run your scripts in debug mode. This
|
|
||||||
configures Playwright for debugging and opens the inspector.
|
|
||||||
|
|
||||||
```bash tab=bash-bash lang=js
|
|
||||||
PWDEBUG=1 npm run test
|
|
||||||
```
|
|
||||||
|
|
||||||
```batch tab=bash-batch lang=js
|
|
||||||
set PWDEBUG=1
|
|
||||||
npm run test
|
|
||||||
```
|
|
||||||
|
|
||||||
```powershell tab=bash-powershell lang=js
|
|
||||||
$env:PWDEBUG=1
|
|
||||||
npm run test
|
|
||||||
```
|
|
||||||
|
|
||||||
```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
|
|
||||||
```
|
|
||||||
|
|
||||||
```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
|
|
||||||
```
|
|
||||||
|
|
||||||
```bash tab=bash-bash lang=python
|
|
||||||
PWDEBUG=1 pytest -s
|
|
||||||
```
|
|
||||||
|
|
||||||
```batch tab=bash-batch lang=python
|
|
||||||
set PWDEBUG=1
|
|
||||||
pytest -s
|
|
||||||
```
|
|
||||||
|
|
||||||
```powershell tab=bash-powershell lang=python
|
|
||||||
$env:PWDEBUG=1
|
|
||||||
pytest -s
|
|
||||||
```
|
|
||||||
|
|
||||||
```bash tab=bash-bash lang=csharp
|
|
||||||
PWDEBUG=1 dotnet test
|
|
||||||
```
|
|
||||||
|
|
||||||
```batch tab=bash-batch lang=csharp
|
|
||||||
set PWDEBUG=1
|
|
||||||
dotnet test
|
|
||||||
```
|
|
||||||
|
|
||||||
```powershell tab=bash-powershell lang=csharp
|
|
||||||
$env:PWDEBUG=1
|
|
||||||
dotnet test
|
|
||||||
```
|
|
||||||
|
|
||||||
Additional useful defaults are configured when `PWDEBUG=1` is set:
|
|
||||||
- Browsers launch in the headed mode
|
|
||||||
- Default timeout is set to 0 (= no timeout)
|
|
||||||
|
|
||||||
- Call [`method: Page.pause`] method from your script when running in headed browser.
|
|
||||||
|
|
||||||
```js
|
|
||||||
// Pause on the following line.
|
|
||||||
await page.pause();
|
|
||||||
```
|
|
||||||
|
|
||||||
```java
|
|
||||||
// Pause on the following line.
|
|
||||||
page.pause();
|
|
||||||
```
|
|
||||||
|
|
||||||
```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>
|
|
||||||
|
|
||||||
## Using Browser Developer Tools
|
|
||||||
|
|
||||||
You can use browser developer tools in Chromium, Firefox and WebKit while running
|
|
||||||
a Playwright script, with or without Playwright inspector. Developer tools help to:
|
|
||||||
|
|
||||||
* Inspect the DOM tree
|
|
||||||
* **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
|
|
||||||
|
|
||||||
:::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.
|
|
||||||
|
|
@ -10,6 +10,7 @@ You can choose to use [NUnit base classes](./test-runners.md#nunit) or [MSTest b
|
||||||
1. Start by creating a new project with `dotnet new`. This will create the `PlaywrightTests` directory which includes a `UnitTest1.cs` file:
|
1. Start by creating a new project with `dotnet new`. This will create the `PlaywrightTests` directory which includes a `UnitTest1.cs` file:
|
||||||
|
|
||||||
<Tabs
|
<Tabs
|
||||||
|
groupId="test-runners"
|
||||||
defaultValue="nunit"
|
defaultValue="nunit"
|
||||||
values={[
|
values={[
|
||||||
{label: 'NUnit', value: 'nunit'},
|
{label: 'NUnit', value: 'nunit'},
|
||||||
|
|
@ -37,6 +38,7 @@ cd PlaywrightTests
|
||||||
2. Install the necessary Playwright dependencies:
|
2. Install the necessary Playwright dependencies:
|
||||||
|
|
||||||
<Tabs
|
<Tabs
|
||||||
|
groupId="test-runners"
|
||||||
defaultValue="nunit"
|
defaultValue="nunit"
|
||||||
values={[
|
values={[
|
||||||
{label: 'NUnit', value: 'nunit'},
|
{label: 'NUnit', value: 'nunit'},
|
||||||
|
|
@ -76,6 +78,7 @@ pwsh bin\Debug\netX\playwright.ps1 install
|
||||||
Edit the `UnitTest1.cs` file with the code below to create an example end-to-end test:
|
Edit the `UnitTest1.cs` file with the code below to create an example end-to-end test:
|
||||||
|
|
||||||
<Tabs
|
<Tabs
|
||||||
|
groupId="test-runners"
|
||||||
defaultValue="nunit"
|
defaultValue="nunit"
|
||||||
values={[
|
values={[
|
||||||
{label: 'NUnit', value: 'nunit'},
|
{label: 'NUnit', value: 'nunit'},
|
||||||
|
|
@ -160,6 +163,7 @@ public class UnitTest1 : PageTest
|
||||||
By default tests will be run on Chromium. This can be configured via the `BROWSER` environment variable, or by adjusting the [launch configuration options](./test-runners.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.
|
By default tests will be run on Chromium. This can be configured via the `BROWSER` environment variable, or by adjusting the [launch configuration options](./test-runners.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.
|
||||||
|
|
||||||
<Tabs
|
<Tabs
|
||||||
|
groupId="test-runners"
|
||||||
defaultValue="nunit"
|
defaultValue="nunit"
|
||||||
values={[
|
values={[
|
||||||
{label: 'NUnit', value: 'nunit'},
|
{label: 'NUnit', value: 'nunit'},
|
||||||
|
|
@ -189,7 +193,6 @@ See our doc on [Test Runners](./test-runners.md) to learn more about running tes
|
||||||
- [Write tests using web first assertions, page fixtures and locators](./writing-tests.md)
|
- [Write tests using web first assertions, page fixtures and locators](./writing-tests.md)
|
||||||
- [Run single tests, multiple tests, headed mode](./running-tests.md)
|
- [Run single tests, multiple tests, headed mode](./running-tests.md)
|
||||||
- [Learn more about the NUnit and MSTest base classes](./test-runners.md)
|
- [Learn more about the NUnit and MSTest base classes](./test-runners.md)
|
||||||
- [Debug tests with the Playwright Debugger](./debug.md)
|
|
||||||
- [Generate tests with Codegen](./codegen.md)
|
- [Generate tests with Codegen](./codegen.md)
|
||||||
- [See a trace of your tests](./trace-viewer.md)
|
- [See a trace of your tests](./trace-viewer.md)
|
||||||
- [Using Playwright as library](./library.md)
|
- [Using Playwright as library](./library.md)
|
||||||
|
|
|
||||||
|
|
@ -76,13 +76,12 @@ Once your test has finished running a [HTML Reporter](./html-reporter.md) will h
|
||||||
npx playwright show-report
|
npx playwright show-report
|
||||||
```
|
```
|
||||||
|
|
||||||
<img width="739" alt="image" src="https://user-images.githubusercontent.com/13063165/178003817-3bd2f088-4173-406c-a9e9-74c89181f381.png" />
|
<img width="739" alt="image" src="https://user-images.githubusercontent.com/13063165/181803518-1f554349-f72a-4ad3-a7aa-4d3d1b4cad13.png" />
|
||||||
|
|
||||||
|
|
||||||
## What's next
|
## What's next
|
||||||
|
|
||||||
- [Write tests using web first assertions, page fixtures and locators](./writing-tests.md)
|
- [Write tests using web first assertions, page fixtures and locators](./writing-tests.md)
|
||||||
- [Run single tests, multiple tests, headed mode](./running-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)
|
- [Generate tests with Codegen](./codegen.md)
|
||||||
- [See a trace of your tests](./trace-viewer.md)
|
- [See a trace of your tests](./trace-viewer.md)
|
||||||
|
|
@ -30,9 +30,7 @@ import re
|
||||||
from playwright.sync_api import Page, expect
|
from playwright.sync_api import Page, expect
|
||||||
|
|
||||||
|
|
||||||
def test_homepage_has_Playwright_in_title_and_get_started_link_linking_to_the_intro_page(
|
def test_homepage_has_Playwright_in_title_and_get_started_link_linking_to_the_intro_page(page: Page):
|
||||||
page: Page, foo
|
|
||||||
):
|
|
||||||
page.goto("https://playwright.dev/")
|
page.goto("https://playwright.dev/")
|
||||||
|
|
||||||
# Expect a title "to contain" a substring.
|
# Expect a title "to contain" a substring.
|
||||||
|
|
@ -65,6 +63,5 @@ See our doc on [Running Tests](./running-tests.md) to learn more about running t
|
||||||
|
|
||||||
- [Write tests using web first assertions, page fixtures and locators](./writing-tests.md)
|
- [Write tests using web first assertions, page fixtures and locators](./writing-tests.md)
|
||||||
- [Run single tests, multiple tests, headed mode](./running-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)
|
- [Generate tests with Codegen](./codegen.md)
|
||||||
- [See a trace of your tests](./trace-viewer.md)
|
- [See a trace of your tests](./trace-viewer.md)
|
||||||
|
|
|
||||||
|
|
@ -3,14 +3,139 @@ id: library
|
||||||
title: "Library"
|
title: "Library"
|
||||||
---
|
---
|
||||||
|
|
||||||
Playwright can either be used as a part of the [Playwright Test](./intro.md), or as a Playwright Library (this guide). If you are working on an application that utilizes Playwright capabilities or you are using Playwright with another test runner, read on.
|
Playwright Library provides unified APIs for launching and interacting with browsers, while Playwright Test provides all this plus a fully managed end-to-end Test Runner and experience.
|
||||||
|
|
||||||
|
Under most circumstances, for end-to-end testing, you'll want to use `@playwright/test` (Playwright Test), and not `playwright` (Playwright Library) directly. To get started with Playwright Test, follow its [Getting Started Guide](./intro.md).
|
||||||
|
|
||||||
<!-- TOC -->
|
<!-- TOC -->
|
||||||
- [Release notes](./release-notes.md)
|
- [Release notes](./release-notes.md)
|
||||||
|
|
||||||
|
## When Should Playwright Library Be Used Directly?
|
||||||
|
|
||||||
|
- creating an integration for a third party test runner (e.g. the third-party runner plugins listed [here](./test-runners.md) are built on top of Playwright Library)
|
||||||
|
- automation and scraping
|
||||||
|
|
||||||
|
## Differences
|
||||||
|
|
||||||
|
### Library Example
|
||||||
|
|
||||||
|
The following is an example of using the Playwright Library directly to launch Chromium, go to a page, and check its title:
|
||||||
|
|
||||||
|
|
||||||
|
```js tab=js-ts
|
||||||
|
import playwright, { devices } from 'playwright';
|
||||||
|
|
||||||
|
(async () => {
|
||||||
|
// Setup
|
||||||
|
const browser = await playwright.chromium.launch();
|
||||||
|
const context = await browser.newContext(devices['iPhone 11']);
|
||||||
|
const page = await context.newPage();
|
||||||
|
|
||||||
|
// The actual interesting bit
|
||||||
|
await context.route('**.jpg', route => route.abort());
|
||||||
|
await page.goto('https://example.com/');
|
||||||
|
|
||||||
|
assert(await page.title() === 'Example'); // 👎 not a Web First assertion
|
||||||
|
|
||||||
|
// Teardown
|
||||||
|
await context.close();
|
||||||
|
await browser.close();
|
||||||
|
})()
|
||||||
|
```
|
||||||
|
|
||||||
|
```js tab=js-js
|
||||||
|
const playwright = require('playwright');
|
||||||
|
|
||||||
|
(async () => {
|
||||||
|
// Setup
|
||||||
|
const browser = await playwright.chromium.launch();
|
||||||
|
const context = await browser.newContext(devices['iPhone 11']);
|
||||||
|
const page = await context.newPage();
|
||||||
|
|
||||||
|
// The actual interesting bit
|
||||||
|
await context.route('**.jpg', route => route.abort());
|
||||||
|
await page.goto('https://example.com/');
|
||||||
|
|
||||||
|
assert(await page.title() === 'Example'); // 👎 not a Web First assertion
|
||||||
|
|
||||||
|
// Teardown
|
||||||
|
await context.close();
|
||||||
|
await browser.close();
|
||||||
|
})()
|
||||||
|
```
|
||||||
|
|
||||||
|
Run via:
|
||||||
|
|
||||||
|
```bash tab=js-ts
|
||||||
|
node ./my-script.ts
|
||||||
|
```
|
||||||
|
|
||||||
|
```bash tab=js-js
|
||||||
|
node ./my-script.js
|
||||||
|
```
|
||||||
|
|
||||||
|
### Test Example
|
||||||
|
|
||||||
|
A test to achieve similar behavior, would look like:
|
||||||
|
|
||||||
|
```js tab=js-ts
|
||||||
|
import { expect, test, devices } from '@playwright/test';
|
||||||
|
|
||||||
|
test.use(devices['iPhone 11']);
|
||||||
|
|
||||||
|
test('should be titled', async ({ page, context }) => {
|
||||||
|
await context.route('**.jpg', route => route.abort());
|
||||||
|
await page.goto('https://example.com/');
|
||||||
|
|
||||||
|
await expect(page).toHaveTitle('Example');
|
||||||
|
});
|
||||||
|
```
|
||||||
|
|
||||||
|
```js tab=js-js
|
||||||
|
const { expect, test, devices } = require('@playwright/test');
|
||||||
|
|
||||||
|
test.use(devices['iPhone 11']);
|
||||||
|
|
||||||
|
test('should be titled', async ({ page, context }) => {
|
||||||
|
await context.route('**.jpg', route => route.abort());
|
||||||
|
await page.goto('https://example.com/');
|
||||||
|
|
||||||
|
await expect(page).toHaveTitle('Example');
|
||||||
|
});
|
||||||
|
```
|
||||||
|
|
||||||
|
Run via:
|
||||||
|
|
||||||
|
```
|
||||||
|
npx playwright test
|
||||||
|
```
|
||||||
|
|
||||||
|
### Key Differences
|
||||||
|
|
||||||
|
The key differences to note are as follows:
|
||||||
|
|
||||||
|
| | Library | Test |
|
||||||
|
| - | - | - |
|
||||||
|
| Installation | `npm install playwright` | `npm init playwright@latest` (note `install` vs. `init`) |
|
||||||
|
| `import`/`require` name | `playwright` | `@playwright/test` |
|
||||||
|
| Initialization | Explicitly need to: <ol><li>Pick a browser to use (e.g. `chromium`)</li><li>Create `browser` ([`method: BrowserType.launch`])</li><li>Create a `context` ([`method: Browser.newContext`]), <em>and</em> pass any context options explcitly (e.g. `devices['iPhone 11']`</li><li>Create a `page` ([`method: BrowserContext.newPage`])</li></ol> | An isolated `page` and `context` are provided to each test out-of the box (along with any other [built-in fixtures](./test-fixtures.md#built-in-fixtures)). No explicit creation. If referenced by the test in it's arguments, the Test Runner will create them for the test. (i.e. lazy-initialization) |
|
||||||
|
| Assertions | No built-in Web-First Assertions | [Web-First assertions](./test-assertions.md) like: <ul><li>[`method: PageAssertions.toHaveTitle`]</li><li>[`method: PageAssertions.toHaveScreenshot#1`]</li></ul> which auto-wait and retry for the condition to be met.|
|
||||||
|
| Cleanup | Explicitly need to: <ol><li>Close `context` ([`method: BrowserContext.close`])</li><li>Close `browser` ([`method: Browser.close`])</li></ol> | No explicit close of [built-in fixtures](./test-fixtures.md#built-in-fixtures); the Test Runner will take care of it.
|
||||||
|
| Running | When using the Library, you run the code as a node script (possibly with some compilation first). | When using the Test Runner, you use the `npx playwright test` command. Along with your [config](./test-configuration.md)), the Test Runner handles any compilation and choosing what to run and how to run it. |
|
||||||
|
|
||||||
|
In addition to the above, Playwright Test—as a full-featured Test Runner—includes:
|
||||||
|
|
||||||
|
- [Configuration Matrix and Projects](./test-configuration.md): In the above example, in the Playwright Library version, if we wanted to run with a different device or browser, we'd have to modify the script and plumb the information through. With Playwright Test, we can just specify the [matrix of configurations](./test-configuration.md) in one place, and it will create run the one test under each of these configurations.
|
||||||
|
- [Parallelization](./test-parallel.md)
|
||||||
|
- [Web-First Assertions](./test-assertions.md)
|
||||||
|
- [Reporting](./test-reporters.md)
|
||||||
|
- [Retries](./test-retries.md)
|
||||||
|
- [Easily Enabled Tracing](./test-configuration.md#record-test-trace)
|
||||||
|
- and more…
|
||||||
|
|
||||||
## Usage
|
## Usage
|
||||||
|
|
||||||
Use npm or Yarn to install Playwright library in your Node.js project. See [system requirements](#system-requirements).
|
Use npm or Yarn to install Playwright library in your Node.js project. See [system requirements](./troubleshooting.md#system-requirements).
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
npm i -D playwright
|
npm i -D playwright
|
||||||
|
|
@ -94,29 +219,3 @@ TypeScript support will work out-of-the-box. Types can also be imported explicit
|
||||||
```js
|
```js
|
||||||
let page: import('playwright').Page;
|
let page: import('playwright').Page;
|
||||||
```
|
```
|
||||||
|
|
||||||
## System requirements
|
|
||||||
|
|
||||||
Playwright requires Node.js version 14 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 11 (Big Sur) or above.
|
|
||||||
|
|
||||||
### Linux
|
|
||||||
|
|
||||||
Depending on your Linux distribution, you might need to install additional
|
|
||||||
dependencies to run the browsers.
|
|
||||||
|
|
||||||
:::note
|
|
||||||
Only Ubuntu 18.04, 20.04, and 22.04 are officially supported.
|
|
||||||
:::
|
|
||||||
|
|
||||||
See also in the [Command line tools](./cli.md#install-system-dependencies)
|
|
||||||
which has a command to install all necessary dependencies automatically for Ubuntu
|
|
||||||
LTS releases.
|
|
||||||
|
|
|
||||||
|
|
@ -177,30 +177,3 @@ On Windows Python 3.7, Playwright sets the default event loop to `ProactorEventL
|
||||||
### Threading
|
### Threading
|
||||||
|
|
||||||
Playwright's API is not thread-safe. If you are using Playwright in a multi-threaded environment, you should create a playwright instance per thread. See [threading issue](https://github.com/microsoft/playwright-python/issues/623) for more details.
|
Playwright's API is not thread-safe. If you are using Playwright in a multi-threaded environment, you should create a playwright instance per thread. See [threading issue](https://github.com/microsoft/playwright-python/issues/623) for more details.
|
||||||
|
|
||||||
|
|
||||||
## System requirements
|
|
||||||
|
|
||||||
Playwright requires Python 3.7 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 11 (Big Sur) or above.
|
|
||||||
|
|
||||||
### Linux
|
|
||||||
|
|
||||||
Depending on your Linux distribution, you might need to install additional
|
|
||||||
dependencies to run the browsers.
|
|
||||||
|
|
||||||
:::note
|
|
||||||
Only Ubuntu 18.04, 20.04, and 22.04 are officially supported.
|
|
||||||
:::
|
|
||||||
|
|
||||||
See also in the [Command line tools](./cli.md#install-system-dependencies)
|
|
||||||
which has a command to install all necessary dependencies automatically for Ubuntu
|
|
||||||
LTS releases.
|
|
||||||
|
|
|
||||||
|
|
@ -152,7 +152,7 @@ Once you're on Playwright Test, you get a lot!
|
||||||
- Built-in test artifact collection: [video recording](./test-configuration#record-video), [screenshots](./test-configuration#automatic-screenshots) and [playwright traces](./test-configuration#record-test-trace)
|
- Built-in test artifact collection: [video recording](./test-configuration#record-video), [screenshots](./test-configuration#automatic-screenshots) and [playwright traces](./test-configuration#record-test-trace)
|
||||||
|
|
||||||
Also you get all these ✨ awesome tools ✨ that come bundled with Playwright Test:
|
Also you get all these ✨ awesome tools ✨ that come bundled with Playwright Test:
|
||||||
- [Playwright Inspector](./inspector)
|
- [Playwright Inspector](./debug.md)
|
||||||
- [Playwright Test Code generation](./auth#code-generation)
|
- [Playwright Test Code generation](./auth#code-generation)
|
||||||
- [Playwright Tracing](./trace-viewer) for post-mortem debugging
|
- [Playwright Tracing](./trace-viewer) for post-mortem debugging
|
||||||
|
|
||||||
|
|
|
||||||
|
|
@ -209,7 +209,7 @@ using System.Threading.Tasks;
|
||||||
using Microsoft.Playwright.NUnit;
|
using Microsoft.Playwright.NUnit;
|
||||||
using NUnit.Framework;
|
using NUnit.Framework;
|
||||||
|
|
||||||
namespace Playwright.TestingHarnessTest.NUnit;
|
namespace PlaywrightTests;
|
||||||
|
|
||||||
public class ExampleTests : PageTest
|
public class ExampleTests : PageTest
|
||||||
{
|
{
|
||||||
|
|
|
||||||
|
|
@ -630,13 +630,13 @@ This version of Playwright was also tested against the following stable channels
|
||||||
|
|
||||||
## Version 1.9
|
## Version 1.9
|
||||||
|
|
||||||
- [Playwright Inspector](./inspector.md) is a **new GUI tool** to author and debug your tests.
|
- [Playwright Inspector](./debug.md) is a **new GUI tool** to author and debug your tests.
|
||||||
- **Line-by-line debugging** of your Playwright scripts, with play, pause and step-through.
|
- **Line-by-line debugging** of your Playwright scripts, with play, pause and step-through.
|
||||||
- Author new scripts by **recording user actions**.
|
- Author new scripts by **recording user actions**.
|
||||||
- **Generate element selectors** for your script by hovering over elements.
|
- **Generate element selectors** for your script by hovering over elements.
|
||||||
- Set the `PWDEBUG=1` environment variable to launch the Inspector
|
- Set the `PWDEBUG=1` environment variable to launch the Inspector
|
||||||
|
|
||||||
- **Pause script execution** with [`method: Page.pause`] in headed mode. Pausing the page launches [Playwright Inspector](./inspector.md) for debugging.
|
- **Pause script execution** with [`method: Page.pause`] in headed mode. Pausing the page launches [Playwright Inspector](./debug.md) for debugging.
|
||||||
|
|
||||||
- **New has-text pseudo-class** for CSS selectors. `:has-text("example")` matches any element containing `"example"` somewhere inside, possibly in a child or a descendant element. See [more examples](./selectors.md#text-selector).
|
- **New has-text pseudo-class** for CSS selectors. `:has-text("example")` matches any element containing `"example"` somewhere inside, possibly in a child or a descendant element. See [more examples](./selectors.md#text-selector).
|
||||||
|
|
||||||
|
|
|
||||||
|
|
@ -1239,13 +1239,13 @@ This version of Playwright was also tested against the following stable channels
|
||||||
|
|
||||||
## Version 1.9
|
## Version 1.9
|
||||||
|
|
||||||
- [Playwright Inspector](./inspector.md) is a **new GUI tool** to author and debug your tests.
|
- [Playwright Inspector](./debug.md) is a **new GUI tool** to author and debug your tests.
|
||||||
- **Line-by-line debugging** of your Playwright scripts, with play, pause and step-through.
|
- **Line-by-line debugging** of your Playwright scripts, with play, pause and step-through.
|
||||||
- Author new scripts by **recording user actions**.
|
- Author new scripts by **recording user actions**.
|
||||||
- **Generate element selectors** for your script by hovering over elements.
|
- **Generate element selectors** for your script by hovering over elements.
|
||||||
- Set the `PWDEBUG=1` environment variable to launch the Inspector
|
- Set the `PWDEBUG=1` environment variable to launch the Inspector
|
||||||
|
|
||||||
- **Pause script execution** with [`method: Page.pause`] in headed mode. Pausing the page launches [Playwright Inspector](./inspector.md) for debugging.
|
- **Pause script execution** with [`method: Page.pause`] in headed mode. Pausing the page launches [Playwright Inspector](./debug.md) for debugging.
|
||||||
|
|
||||||
- **New has-text pseudo-class** for CSS selectors. `:has-text("example")` matches any element containing `"example"` somewhere inside, possibly in a child or a descendant element. See [more examples](./selectors.md#text-selector).
|
- **New has-text pseudo-class** for CSS selectors. `:has-text("example")` matches any element containing `"example"` somewhere inside, possibly in a child or a descendant element. See [more examples](./selectors.md#text-selector).
|
||||||
|
|
||||||
|
|
|
||||||
|
|
@ -704,13 +704,13 @@ This version of Playwright was also tested against the following stable channels
|
||||||
|
|
||||||
## Version 1.9
|
## Version 1.9
|
||||||
|
|
||||||
- [Playwright Inspector](./inspector.md) is a **new GUI tool** to author and debug your tests.
|
- [Playwright Inspector](./debug.md) is a **new GUI tool** to author and debug your tests.
|
||||||
- **Line-by-line debugging** of your Playwright scripts, with play, pause and step-through.
|
- **Line-by-line debugging** of your Playwright scripts, with play, pause and step-through.
|
||||||
- Author new scripts by **recording user actions**.
|
- Author new scripts by **recording user actions**.
|
||||||
- **Generate element selectors** for your script by hovering over elements.
|
- **Generate element selectors** for your script by hovering over elements.
|
||||||
- Set the `PWDEBUG=1` environment variable to launch the Inspector
|
- Set the `PWDEBUG=1` environment variable to launch the Inspector
|
||||||
|
|
||||||
- **Pause script execution** with [`method: Page.pause`] in headed mode. Pausing the page launches [Playwright Inspector](./inspector.md) for debugging.
|
- **Pause script execution** with [`method: Page.pause`] in headed mode. Pausing the page launches [Playwright Inspector](./debug.md) for debugging.
|
||||||
|
|
||||||
- **New has-text pseudo-class** for CSS selectors. `:has-text("example")` matches any element containing `"example"` somewhere inside, possibly in a child or a descendant element. See [more examples](./selectors.md#text-selector).
|
- **New has-text pseudo-class** for CSS selectors. `:has-text("example")` matches any element containing `"example"` somewhere inside, possibly in a child or a descendant element. See [more examples](./selectors.md#text-selector).
|
||||||
|
|
||||||
|
|
|
||||||
|
|
@ -67,8 +67,30 @@ You can run a single test, a set of tests or all tests. Tests can be run on diff
|
||||||
|
|
||||||
For more information see [selective unit tests](https://docs.microsoft.com/en-us/dotnet/core/testing/selective-unit-tests?pivots=mstest) in the Microsoft docs.
|
For more information see [selective unit tests](https://docs.microsoft.com/en-us/dotnet/core/testing/selective-unit-tests?pivots=mstest) in the Microsoft docs.
|
||||||
|
|
||||||
|
## Debugging Tests
|
||||||
|
|
||||||
|
Since Playwright runs in .NET, you can debug it with your debugger of choice in e.g. Visual Studio Code or Visual Studio. Playwright comes with the Playwright Inspector which allows you to step through Playwright API calls, see their debug logs and explore [selectors](./selectors.md).
|
||||||
|
|
||||||
|
```bash tab=bash-bash lang=csharp
|
||||||
|
PWDEBUG=1 dotnet test
|
||||||
|
```
|
||||||
|
|
||||||
|
```batch tab=bash-batch lang=csharp
|
||||||
|
set PWDEBUG=1
|
||||||
|
dotnet test
|
||||||
|
```
|
||||||
|
|
||||||
|
```powershell tab=bash-powershell lang=csharp
|
||||||
|
$env:PWDEBUG=1
|
||||||
|
dotnet test
|
||||||
|
```
|
||||||
|
|
||||||
|
<img width="712" alt="Playwright Inspector" src="https://user-images.githubusercontent.com/883973/108614092-8c478a80-73ac-11eb-9597-67dfce110e00.png"></img>
|
||||||
|
|
||||||
|
Check out our [debugging guide](./debug.md) to learn more about the [Playwright Inspector](./debug.md#playwright-inspector) as well as debugging with [Browser Developer tools](./debug.md#browser-developer-tools).
|
||||||
|
|
||||||
|
|
||||||
## What's Next
|
## What's Next
|
||||||
|
|
||||||
- [Debug tests with the Playwright Debugger](./debug.md)
|
|
||||||
- [Generate tests with Codegen](./codegen.md)
|
- [Generate tests with Codegen](./codegen.md)
|
||||||
- [See a trace of your tests](./trace-viewer.md)
|
- [See a trace of your tests](./trace-viewer.md)
|
||||||
|
|
|
||||||
|
|
@ -3,7 +3,13 @@ id: running-tests
|
||||||
title: "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.
|
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.
|
||||||
|
|
||||||
|
:::note
|
||||||
|
For a better debugging experience check out the [VS Code Extension](./getting-started-vscode.md) for Playwright where you can run tests, add breakpoints and debug your tests right from the VS Code editor.
|
||||||
|
:::
|
||||||
|
|
||||||
|
## Command Line
|
||||||
|
|
||||||
- Running all tests
|
- Running all tests
|
||||||
|
|
||||||
|
|
@ -14,7 +20,7 @@ You can run a single test, a set of tests or all tests. Tests can be run on one
|
||||||
- Running a single test file
|
- Running a single test file
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
npx playwright test test-1
|
npx playwright test landing-page.spec.ts
|
||||||
```
|
```
|
||||||
|
|
||||||
- Run a set of test files
|
- Run a set of test files
|
||||||
|
|
@ -23,10 +29,10 @@ You can run a single test, a set of tests or all tests. Tests can be run on one
|
||||||
npx playwright test tests/todo-page/ tests/landing-page/
|
npx playwright test tests/todo-page/ tests/landing-page/
|
||||||
```
|
```
|
||||||
|
|
||||||
- Run files that have `my-spec` or `my-spec-2` in the file name
|
- Run files that have `landing` or `login` in the file name
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
npx playwright test my-spec my-spec-2
|
npx playwright test landing login
|
||||||
```
|
```
|
||||||
|
|
||||||
- Run the test with the title
|
- Run the test with the title
|
||||||
|
|
@ -38,28 +44,59 @@ You can run a single test, a set of tests or all tests. Tests can be run on one
|
||||||
- Running tests in headed mode
|
- Running tests in headed mode
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
npx playwright test test-1 --headed
|
npx playwright test landing-page.spec.ts --headed
|
||||||
```
|
```
|
||||||
|
|
||||||
- Running Tests on specific browsers
|
- Running Tests on specific browsers
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
npx playwright test test-1.spec.ts --project=chromium
|
npx playwright test landing-page.ts --project=chromium
|
||||||
```
|
```
|
||||||
|
|
||||||
|
## Debugging Tests
|
||||||
|
|
||||||
|
Since Playwright runs in Node.js, you can debug it with your debugger of choice e.g. using `console.log` or inside your IDE or directly in VS Code with the [VS Code Extension](./getting-started-vscode.md). Playwright comes with the [Playwright Inspector](./debug.md#playwright-inspector) which allows you to step through Playwright API calls, see their debug logs and explore [selectors](./selectors.md).
|
||||||
|
|
||||||
|
|
||||||
|
- Debugging all tests:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
npx playwright test --debug
|
||||||
|
```
|
||||||
|
|
||||||
|
- Debugging one test file:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
npx playwright test example.spec.ts --debug
|
||||||
|
```
|
||||||
|
|
||||||
|
- Debugging a test from the line number where the `test(..` is defined:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
npx playwright test example.spec.ts:42 --debug
|
||||||
|
```
|
||||||
|
|
||||||
|
<img width="1188" alt="Screenshot 2022-07-29 at 23 50 13" src="https://user-images.githubusercontent.com/13063165/181847661-7ec5fb6c-7c21-4db0-9931-a593b21bafc2.png" />
|
||||||
|
|
||||||
|
|
||||||
|
Check out our [debugging guide](./debug.md) to learn more about the [Playwright Inspector](./debug.md#playwright-inspector) as well as debugging with [Browser Developer tools](./debug.md#browser-developer-tools).
|
||||||
|
|
||||||
|
|
||||||
## Test Reports
|
## 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.
|
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. By default, the HTML report is opened automatically if some of the tests failed.
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
npx playwright show-report
|
npx playwright show-report
|
||||||
```
|
```
|
||||||
|
|
||||||
<img width="739" alt="image" src="https://user-images.githubusercontent.com/13063165/178003817-3bd2f088-4173-406c-a9e9-74c89181f381.png" />
|
<img width="739" alt="image" src="https://user-images.githubusercontent.com/13063165/181803518-1f554349-f72a-4ad3-a7aa-4d3d1b4cad13.png" />
|
||||||
|
|
||||||
|
You can click on each test and explore the tests errors as well as each step of the test.
|
||||||
|
|
||||||
|
<img width="739" alt="image" src="https://user-images.githubusercontent.com/13063165/181814327-a597109f-6f24-44a1-b47c-0de9dc7f5912.png" />
|
||||||
|
|
||||||
## What's Next
|
## What's Next
|
||||||
|
|
||||||
- [Debug tests with the Playwright Debugger](./debug.md)
|
|
||||||
- [Generate tests with Codegen](./codegen.md)
|
- [Generate tests with Codegen](./codegen.md)
|
||||||
- [See a trace of your tests](./trace-viewer.md)
|
- [See a trace of your tests](./trace-viewer.md)
|
||||||
|
|
@ -49,8 +49,30 @@ You can run a single test, a set of tests or all tests. Tests can be run on one
|
||||||
|
|
||||||
For more information see [Playwright Pytest usage](./test-runners.md) or the Pytest documentation for [general CLI usage](https://docs.pytest.org/en/stable/usage.html).
|
For more information see [Playwright Pytest usage](./test-runners.md) or the Pytest documentation for [general CLI usage](https://docs.pytest.org/en/stable/usage.html).
|
||||||
|
|
||||||
|
## Running Tests
|
||||||
|
|
||||||
|
Since Playwright runs in Python, you can debug it with your debugger of choice with e.g. the [Python extension](https://code.visualstudio.com/docs/python/python-tutorial) in Visual Studio Code. Playwright comes with the Playwright Inspector which allows you to step through Playwright API calls, see their debug logs and explore [selectors](./selectors.md).
|
||||||
|
|
||||||
|
|
||||||
|
```bash tab=bash-bash lang=python
|
||||||
|
PWDEBUG=1 pytest -s
|
||||||
|
```
|
||||||
|
|
||||||
|
```batch tab=bash-batch lang=python
|
||||||
|
set PWDEBUG=1
|
||||||
|
pytest -s
|
||||||
|
```
|
||||||
|
|
||||||
|
```powershell tab=bash-powershell lang=python
|
||||||
|
$env:PWDEBUG=1
|
||||||
|
pytest -s
|
||||||
|
```
|
||||||
|
<img width="712" alt="Playwright Inspector" src="https://user-images.githubusercontent.com/883973/108614092-8c478a80-73ac-11eb-9597-67dfce110e00.png"></img>
|
||||||
|
|
||||||
|
Check out our [debugging guide](./debug.md) to learn more about the [Playwright Inspector](./debug.md#playwright-inspector) as well as debugging with [Browser Developer tools](./debug.md#browser-developer-tools).
|
||||||
|
|
||||||
|
|
||||||
## What's Next
|
## What's Next
|
||||||
|
|
||||||
- [Debug tests with the Playwright Debugger](./debug.md)
|
|
||||||
- [Generate tests with Codegen](./codegen.md)
|
- [Generate tests with Codegen](./codegen.md)
|
||||||
- [See a trace of your tests](./trace-viewer.md)
|
- [See a trace of your tests](./trace-viewer.md)
|
||||||
|
|
@ -3,7 +3,7 @@ id: selectors
|
||||||
title: "Selectors"
|
title: "Selectors"
|
||||||
---
|
---
|
||||||
|
|
||||||
Selectors are strings that are used to create [Locator]s. Locators are used to perform actions on the elements by means of methods such as [`method: Locator.click`], [`method: Locator.fill`] and alike.
|
Selectors are strings that are used to create [Locator]s. Locators are used to perform actions on the elements by means of methods such as [`method: Locator.click`], [`method: Locator.fill`] and alike. For debugging selectors, see [here](./debug-selectors).
|
||||||
|
|
||||||
Writing good selectors is part art, part science so be sure to checkout the [Best Practices](#best-practices) section.
|
Writing good selectors is part art, part science so be sure to checkout the [Best Practices](#best-practices) section.
|
||||||
|
|
||||||
|
|
@ -1323,7 +1323,7 @@ await page.Locator("data-test-id=directions").ClickAsync();
|
||||||
### Avoid selectors tied to implementation
|
### Avoid selectors tied to implementation
|
||||||
|
|
||||||
[xpath] and [css] can be tied to the DOM structure or implementation. These selectors can break when
|
[xpath] and [css] can be tied to the DOM structure or implementation. These selectors can break when
|
||||||
the DOM structure changes.
|
the DOM structure changes. Similarly, [`method: Locator.nth`], [`method: Locator.first`], and [`method: Locator.last`] are tied to implementation and the structure of the DOM, and will target the incorrect element if the DOM changes.
|
||||||
|
|
||||||
```js
|
```js
|
||||||
// avoid long css or xpath chains
|
// avoid long css or xpath chains
|
||||||
|
|
|
||||||
|
|
@ -59,7 +59,7 @@ Here are the most common options available in the command line.
|
||||||
npx playwright test --reporter=dot
|
npx playwright test --reporter=dot
|
||||||
```
|
```
|
||||||
|
|
||||||
- Run in debug mode with [Playwright Inspector](./inspector.md)
|
- Run in debug mode with [Playwright Inspector](./debug.md)
|
||||||
```bash
|
```bash
|
||||||
npx playwright test --debug
|
npx playwright test --debug
|
||||||
```
|
```
|
||||||
|
|
|
||||||
|
|
@ -237,68 +237,76 @@ There is no guarantee about the order of test execution across the files, becaus
|
||||||
|
|
||||||
### Sort test files alphabetically
|
### Sort test files alphabetically
|
||||||
|
|
||||||
When you **disable parallel test execution**, Playwright Test runs test files in alphabetical order. You can use some naming convention to control the test order, for example `test001.spec.ts`, `test002.spec.ts` and so on.
|
When you **disable parallel test execution**, Playwright Test runs test files in alphabetical order. You can use some naming convention to control the test order, for example `001-user-signin-flow.spec.ts`, `002-create-new-document.spec.ts` and so on.
|
||||||
|
|
||||||
### Use a "test list" file
|
### Use a "test list" file
|
||||||
|
|
||||||
Suppose we have two test files.
|
You can put your tests in helper functions in multiple files. Consider the following example where tests are not defined directly in the file, but rather in a wrapper function.
|
||||||
|
|
||||||
```js tab=js-js
|
```js tab=js-js
|
||||||
// feature-a.spec.js
|
// feature-a.spec.js
|
||||||
const { test, expect } = require('@playwright/test');
|
const { test, expect } = require('@playwright/test');
|
||||||
|
|
||||||
test.describe('feature-a', () => {
|
module.exports = function createTests() {
|
||||||
test('example test', async ({ page }) => {
|
test('feature-a example test', async ({ page }) => {
|
||||||
// ... test goes here
|
// ... test goes here
|
||||||
});
|
});
|
||||||
});
|
};
|
||||||
|
|
||||||
|
|
||||||
// feature-b.spec.js
|
// feature-b.spec.js
|
||||||
const { test, expect } = require('@playwright/test');
|
const { test, expect } = require('@playwright/test');
|
||||||
|
|
||||||
test.describe('feature-b', () => {
|
module.exports = function createTests() {
|
||||||
test.use({ viewport: { width: 500, height: 500 } });
|
test.use({ viewport: { width: 500, height: 500 } });
|
||||||
test('example test', async ({ page }) => {
|
|
||||||
|
test('feature-b example test', async ({ page }) => {
|
||||||
// ... test goes here
|
// ... test goes here
|
||||||
});
|
});
|
||||||
});
|
};
|
||||||
```
|
```
|
||||||
|
|
||||||
```js tab=js-ts
|
```js tab=js-ts
|
||||||
// feature-a.spec.ts
|
// feature-a.spec.ts
|
||||||
import { test, expect } from '@playwright/test';
|
import { test, expect } from '@playwright/test';
|
||||||
|
|
||||||
test.describe('feature-a', () => {
|
export default function createTests() {
|
||||||
test('example test', async ({ page }) => {
|
test('feature-a example test', async ({ page }) => {
|
||||||
// ... test goes here
|
// ... test goes here
|
||||||
});
|
});
|
||||||
});
|
}
|
||||||
|
|
||||||
|
|
||||||
// feature-b.spec.ts
|
// feature-b.spec.ts
|
||||||
import { test, expect } from '@playwright/test';
|
import { test, expect } from '@playwright/test';
|
||||||
|
|
||||||
test.describe('feature-b', () => {
|
export default function createTests() {
|
||||||
test.use({ viewport: { width: 500, height: 500 } });
|
test.use({ viewport: { width: 500, height: 500 } });
|
||||||
test('example test', async ({ page }) => {
|
|
||||||
|
test('feature-b example test', async ({ page }) => {
|
||||||
// ... test goes here
|
// ... test goes here
|
||||||
});
|
});
|
||||||
});
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
We can create a test list file that will control the order of tests - first run `feature-b` tests, then `feature-a` tests.
|
You can create a test list file that will control the order of tests - first run `feature-b` tests, then `feature-a` tests. Note how each test file is wrapped in a `test.describe()` block that calls the function where tests are defined. This way `test.use()` calls only affect tests from a single file.
|
||||||
|
|
||||||
|
|
||||||
```js tab=js-js
|
```js tab=js-js
|
||||||
// test.list.js
|
// test.list.js
|
||||||
require('./feature-b.spec.js');
|
const { test } = require('@playwright/test');
|
||||||
require('./feature-a.spec.js');
|
|
||||||
|
test.describe(require('./feature-b.spec.js'));
|
||||||
|
test.describe(require('./feature-a.spec.js'));
|
||||||
```
|
```
|
||||||
|
|
||||||
```js tab=js-ts
|
```js tab=js-ts
|
||||||
// test.list.ts
|
// test.list.ts
|
||||||
import './feature-b.spec.ts';
|
import { test } from '@playwright/test';
|
||||||
import './feature-a.spec.ts';
|
import featureBTests from './feature-b.spec.ts';
|
||||||
|
import featureATests from './feature-a.spec.ts';
|
||||||
|
|
||||||
|
test.describe(featureBTests);
|
||||||
|
test.describe(featureATests);
|
||||||
```
|
```
|
||||||
|
|
||||||
Now **disable parallel execution** by setting workers to one, and specify your test list file.
|
Now **disable parallel execution** by setting workers to one, and specify your test list file.
|
||||||
|
|
@ -328,5 +336,6 @@ export default config;
|
||||||
```
|
```
|
||||||
|
|
||||||
:::note
|
:::note
|
||||||
Make sure to wrap tests with `test.describe()` blocks so that any `test.use()` calls only affect tests from a single file.
|
Do not define your tests directly in a helper file. This could lead to unexpected results because your
|
||||||
|
tests are now dependent on the order of `import`/`require` statements. Instead, wrap tests in a function that will be explicitly called by a test list file, as in the example above.
|
||||||
:::
|
:::
|
||||||
|
|
|
||||||
|
|
@ -67,6 +67,10 @@ test('example', async ({ page }) => {
|
||||||
});
|
});
|
||||||
```
|
```
|
||||||
|
|
||||||
|
:::note
|
||||||
|
TypeScript with ESM requires Node.js 16 or higher.
|
||||||
|
:::
|
||||||
|
|
||||||
## TypeScript path mapping
|
## TypeScript path mapping
|
||||||
|
|
||||||
If you use [path mapping](https://www.typescriptlang.org/docs/handbook/module-resolution.html#path-mapping) in your `tsconfig.json`, Playwright Test will pick it up. Make sure that `baseUrl` is also set.
|
If you use [path mapping](https://www.typescriptlang.org/docs/handbook/module-resolution.html#path-mapping) in your `tsconfig.json`, Playwright Test will pick it up. Make sure that `baseUrl` is also set.
|
||||||
|
|
|
||||||
|
|
@ -142,7 +142,7 @@ Once you're on Playwright Test, you get a lot!
|
||||||
- Built-in test artifact collection: [video recording](./test-configuration#record-video), [screenshots](./test-configuration#automatic-screenshots) and [playwright traces](./test-configuration#record-test-trace)
|
- Built-in test artifact collection: [video recording](./test-configuration#record-video), [screenshots](./test-configuration#automatic-screenshots) and [playwright traces](./test-configuration#record-test-trace)
|
||||||
|
|
||||||
Also you get all these ✨ awesome tools ✨ that come bundled with Playwright Test:
|
Also you get all these ✨ awesome tools ✨ that come bundled with Playwright Test:
|
||||||
- [Playwright Inspector](./inspector)
|
- [Playwright Inspector](./debug.md)
|
||||||
- [Playwright Test Code generation](./auth#code-generation)
|
- [Playwright Test Code generation](./auth#code-generation)
|
||||||
- [Playwright Tracing](./trace-viewer) for post-mortem debugging
|
- [Playwright Tracing](./trace-viewer) for post-mortem debugging
|
||||||
|
|
||||||
|
|
|
||||||
|
|
@ -3,8 +3,6 @@ id: troubleshooting
|
||||||
title: "Troubleshooting"
|
title: "Troubleshooting"
|
||||||
---
|
---
|
||||||
|
|
||||||
<!-- TOC -->
|
|
||||||
|
|
||||||
## Browser dependencies
|
## Browser dependencies
|
||||||
|
|
||||||
Playwright does self-inspection every time it runs to make sure the browsers can be launched successfully. If there are missing
|
Playwright does self-inspection every time it runs to make sure the browsers can be launched successfully. If there are missing
|
||||||
|
|
@ -15,6 +13,7 @@ which has a command to install all necessary dependencies automatically for Ubun
|
||||||
LTS releases.
|
LTS releases.
|
||||||
|
|
||||||
## Code transpilation issues
|
## Code transpilation issues
|
||||||
|
* langs: js
|
||||||
|
|
||||||
If you are using a JavaScript transpiler like babel or TypeScript, calling `evaluate()` with an async function might not work. This is because while `playwright` uses `Function.prototype.toString()` to serialize functions while transpilers could be changing the output code in such a way it's incompatible with `playwright`.
|
If you are using a JavaScript transpiler like babel or TypeScript, calling `evaluate()` with an async function might not work. This is because while `playwright` uses `Function.prototype.toString()` to serialize functions while transpilers could be changing the output code in such a way it's incompatible with `playwright`.
|
||||||
|
|
||||||
|
|
@ -27,11 +26,55 @@ await page.evaluate(`(async() => {
|
||||||
```
|
```
|
||||||
|
|
||||||
## Node.js requirements
|
## Node.js requirements
|
||||||
|
* langs: js
|
||||||
|
|
||||||
|
Playwright requires Node.js version 14 or above
|
||||||
|
|
||||||
### ReferenceError: URL is not defined
|
### ReferenceError: URL is not defined
|
||||||
|
|
||||||
Playwright requires Node.js 14 or higher. Node.js 8 is not supported, and will cause you to receive this error.
|
Playwright requires Node.js 14 or higher.
|
||||||
|
|
||||||
# Please file an issue
|
### Unknown file extension ".ts"
|
||||||
|
|
||||||
|
Running TypeScript tests in `"type": "module"` project requires Node.js 16 or higher.
|
||||||
|
|
||||||
|
## .NET requirements
|
||||||
|
* langs: csharp
|
||||||
|
|
||||||
|
Playwright is distributed as a **.NET Standard 2.0** library. We recommend .NET 6 or newer.
|
||||||
|
|
||||||
|
## Python requirements
|
||||||
|
* langs: python
|
||||||
|
|
||||||
|
Playwright requires **Python 3.7** or newer.
|
||||||
|
|
||||||
|
## Java requirements
|
||||||
|
* langs: java
|
||||||
|
|
||||||
|
Playwright requires **Java 8** or newer.
|
||||||
|
|
||||||
|
## System requirements
|
||||||
|
|
||||||
|
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 11 (Big Sur) or above.
|
||||||
|
|
||||||
|
### Linux
|
||||||
|
|
||||||
|
Depending on your Linux distribution, you might need to install additional
|
||||||
|
dependencies to run the browsers.
|
||||||
|
|
||||||
|
:::note
|
||||||
|
Only Ubuntu 18.04, 20.04, and 22.04 are officially supported.
|
||||||
|
:::
|
||||||
|
|
||||||
|
See also in the [Command line tools](./cli.md#install-system-dependencies)
|
||||||
|
which has a command to install all necessary dependencies automatically for Ubuntu
|
||||||
|
LTS releases.
|
||||||
|
|
||||||
Playwright is a new project, and we are watching the issues very closely. As we solve common issues, this document will grow to include the common answers.
|
|
||||||
|
|
@ -8,6 +8,7 @@ Playwright assertions are created specifically for the dynamic web. Checks are a
|
||||||
Take a look at the example test below to see how to write a test using web first assertions, locators and selectors.
|
Take a look at the example test below to see how to write a test using web first assertions, locators and selectors.
|
||||||
|
|
||||||
<Tabs
|
<Tabs
|
||||||
|
groupId="test-runners"
|
||||||
defaultValue="nunit"
|
defaultValue="nunit"
|
||||||
values={[
|
values={[
|
||||||
{label: 'NUnit', value: 'nunit'},
|
{label: 'NUnit', value: 'nunit'},
|
||||||
|
|
@ -117,6 +118,7 @@ await Expect(Page.Locator("text=Installation")).ToBeVisibleAsync();
|
||||||
The Playwright NUnit and MSTest test framework base classes will isolate each test from each other by providing a separate `Page` instance. 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.
|
The Playwright NUnit and MSTest test framework base classes will isolate each test from each other by providing a separate `Page` instance. 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.
|
||||||
|
|
||||||
<Tabs
|
<Tabs
|
||||||
|
groupId="test-runners"
|
||||||
defaultValue="nunit"
|
defaultValue="nunit"
|
||||||
values={[
|
values={[
|
||||||
{label: 'NUnit', value: 'nunit'},
|
{label: 'NUnit', value: 'nunit'},
|
||||||
|
|
@ -169,6 +171,7 @@ public class UnitTest1 : PageTest
|
||||||
You can use `SetUp`/`TearDown` in NUnit or `TestInitialize`/`TestCleanup` in MSTest to prepare and clean up your test environment:
|
You can use `SetUp`/`TearDown` in NUnit or `TestInitialize`/`TestCleanup` in MSTest to prepare and clean up your test environment:
|
||||||
|
|
||||||
<Tabs
|
<Tabs
|
||||||
|
groupId="test-runners"
|
||||||
defaultValue="nunit"
|
defaultValue="nunit"
|
||||||
values={[
|
values={[
|
||||||
{label: 'NUnit', value: 'nunit'},
|
{label: 'NUnit', value: 'nunit'},
|
||||||
|
|
@ -233,6 +236,5 @@ public class UnitTest1 : PageTest
|
||||||
## What's Next
|
## What's Next
|
||||||
|
|
||||||
- [Run single tests, multiple tests, headed mode](./running-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)
|
- [Generate tests with Codegen](./codegen.md)
|
||||||
- [See a trace of your tests](./trace-viewer.md)
|
- [See a trace of your tests](./trace-viewer.md)
|
||||||
|
|
@ -135,6 +135,5 @@ test.describe("navigation", () => {
|
||||||
## What's Next
|
## What's Next
|
||||||
|
|
||||||
- [Run single tests, multiple tests, headed mode](./running-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)
|
- [Generate tests with Codegen](./codegen.md)
|
||||||
- [See a trace of your tests](./trace-viewer.md)
|
- [See a trace of your tests](./trace-viewer.md)
|
||||||
|
|
@ -12,9 +12,7 @@ import re
|
||||||
from playwright.sync_api import Page, expect
|
from playwright.sync_api import Page, expect
|
||||||
|
|
||||||
|
|
||||||
def test_homepage_has_Playwright_in_title_and_get_started_link_linking_to_the_intro_page(
|
def test_homepage_has_Playwright_in_title_and_get_started_link_linking_to_the_intro_page(page: Page):
|
||||||
page: Page, foo
|
|
||||||
):
|
|
||||||
page.goto("https://playwright.dev/")
|
page.goto("https://playwright.dev/")
|
||||||
|
|
||||||
# Expect a title "to contain" a substring.
|
# Expect a title "to contain" a substring.
|
||||||
|
|
@ -105,6 +103,5 @@ def test_main_navigation(page: Page):
|
||||||
## What's Next
|
## What's Next
|
||||||
|
|
||||||
- [Run single tests, multiple tests, headed mode](./running-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)
|
- [Generate tests with Codegen](./codegen.md)
|
||||||
- [See a trace of your tests](./trace-viewer.md)
|
- [See a trace of your tests](./trace-viewer.md)
|
||||||
12
packages/playwright-core/types/types.d.ts
vendored
12
packages/playwright-core/types/types.d.ts
vendored
|
|
@ -10379,7 +10379,9 @@ export interface BrowserType<Unused = {}> {
|
||||||
*/
|
*/
|
||||||
connectOverCDP(options: ConnectOverCDPOptions & { wsEndpoint?: string }): Promise<Browser>;
|
connectOverCDP(options: ConnectOverCDPOptions & { wsEndpoint?: string }): Promise<Browser>;
|
||||||
/**
|
/**
|
||||||
* This method attaches Playwright to an existing browser instance.
|
* This method attaches Playwright to an existing browser instance. When connecting to another browser launched via
|
||||||
|
* `BrowserType.launchServer` in Node.js, the major and minor version needs to match the client version (1.2.3 → is
|
||||||
|
* compatible with 1.2.x).
|
||||||
* @param wsEndpoint A browser websocket endpoint to connect to.
|
* @param wsEndpoint A browser websocket endpoint to connect to.
|
||||||
* @param options
|
* @param options
|
||||||
*/
|
*/
|
||||||
|
|
@ -10391,7 +10393,9 @@ export interface BrowserType<Unused = {}> {
|
||||||
* @deprecated
|
* @deprecated
|
||||||
*/
|
*/
|
||||||
/**
|
/**
|
||||||
* This method attaches Playwright to an existing browser instance.
|
* This method attaches Playwright to an existing browser instance. When connecting to another browser launched via
|
||||||
|
* `BrowserType.launchServer` in Node.js, the major and minor version needs to match the client version (1.2.3 → is
|
||||||
|
* compatible with 1.2.x).
|
||||||
* @param wsEndpoint A browser websocket endpoint to connect to.
|
* @param wsEndpoint A browser websocket endpoint to connect to.
|
||||||
* @param options
|
* @param options
|
||||||
*/
|
*/
|
||||||
|
|
@ -10835,7 +10839,9 @@ export interface BrowserType<Unused = {}> {
|
||||||
}): Promise<BrowserContext>;
|
}): Promise<BrowserContext>;
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* Returns the browser app instance.
|
* Returns the browser app instance. You can connect to it via
|
||||||
|
* [browserType.connect(wsEndpoint[, options])](https://playwright.dev/docs/api/class-browsertype#browser-type-connect),
|
||||||
|
* which requires the major/minor client/server version to match (1.2.3 → is compatible with 1.2.x).
|
||||||
*
|
*
|
||||||
* Launches browser server that client can connect to. An example of launching a browser executable and connecting to it
|
* Launches browser server that client can connect to. An example of launching a browser executable and connecting to it
|
||||||
* later:
|
* later:
|
||||||
|
|
|
||||||
Loading…
Reference in a new issue