docs: add intros for all pages (#27480)

This commit is contained in:
Debbie O'Brien 2023-10-06 15:08:51 +02:00 committed by GitHub
parent cf29d1baa9
commit 3773f004db
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
70 changed files with 127 additions and 17 deletions

View File

@ -3,6 +3,8 @@ id: accessibility-testing
title: "Accessibility testing"
---
## Introduction
Playwright can be used to test your application for many types of accessibility issues.
A few examples of problems this can catch include:

View File

@ -3,6 +3,8 @@ id: accessibility-testing
title: "Accessibility testing"
---
## Introduction
Playwright can be used to test your application for many types of accessibility issues.
A few examples of problems this can catch include:

View File

@ -3,6 +3,8 @@ id: actionability
title: "Auto-waiting"
---
## Introduction
Playwright performs a range of actionability checks on the elements before making actions to ensure these actions
behave as expected. It auto-waits for all the relevant checks to pass and only then performs the requested action. If the required checks do not pass within the given `timeout`, action fails with the `TimeoutError`.

View File

@ -3,6 +3,8 @@ id: api-testing
title: "API testing"
---
## Introduction
Playwright can be used to get access to the [REST](https://en.wikipedia.org/wiki/Representational_state_transfer) API of
your application.

View File

@ -3,6 +3,8 @@ id: api-testing
title: "API testing"
---
## Introduction
Playwright can be used to get access to the [REST](https://en.wikipedia.org/wiki/Representational_state_transfer) API of
your application.

View File

@ -3,6 +3,8 @@ id: api-testing
title: "API testing"
---
## Introduction
Playwright can be used to get access to the [REST](https://en.wikipedia.org/wiki/Representational_state_transfer) API of
your application.

View File

@ -3,6 +3,8 @@ id: api-testing
title: "API testing"
---
## Introduction
Playwright can be used to get access to the [REST](https://en.wikipedia.org/wiki/Representational_state_transfer) API of
your application.

View File

@ -3,6 +3,8 @@ id: auth
title: "Authentication"
---
## Introduction
Playwright executes tests in isolated environments called [browser contexts](./browser-contexts.md). This isolation model improves reproducibility and prevents cascading test failures. Tests can load existing authenticated state. This eliminates the need to authenticate in every test and speeds up test execution.
## Core concepts

View File

@ -3,6 +3,7 @@ id: best-practices
title: "Best Practices"
---
## Introduction
This guide should help you to make sure you are following our best practices and writing tests that are more resilient.

View File

@ -3,6 +3,8 @@ id: browser-contexts
title: "Isolation"
---
## Introduction
Tests written with Playwright execute in isolated clean-slate environments called browser contexts. This isolation model improves reproducibility and prevents cascading test failures.
## What is Test Isolation?

View File

@ -3,6 +3,8 @@ id: browsers
title: "Browsers"
---
## Introduction
Each version of Playwright needs specific versions of browser binaries to operate. You will need to use the Playwright CLI to install these browsers.
With every release, Playwright updates the versions of the browsers it supports, so that the latest Playwright would support the latest browsers at any moment. It means that every time you update Playwright, you might need to re-run the `install` CLI command.

View File

@ -3,6 +3,8 @@ id: canary-releases
title: "Canary releases"
---
## Introduction
Playwright for Node.js has a canary releases system.
It permits you to **test new unreleased features** instead of waiting for a full release. They get released daily on the `next` NPM tag of Playwright.

View File

@ -3,6 +3,8 @@ id: chrome-extensions
title: "Chrome extensions"
---
## Introduction
:::note
Extensions only work in Chrome / Chromium launched with a persistent context.
:::

View File

@ -2,12 +2,11 @@
id: ci
title: "Continuous Integration"
---
## Introduction
Playwright tests can be executed in CI environments. We have created sample
configurations for common CI providers.
## Introduction
3 steps to get your tests running on CI:
1. **Ensure CI agent can run browsers**: Use [our Docker image](./docker.md)

View File

@ -5,6 +5,7 @@ title: "Test generator"
import LiteYouTube from '@site/src/components/LiteYouTube';
## Introduction
Playwright comes with the ability to generate tests for you as you perform actions in the browser and is a great way to quickly get started with testing. Playwright will look at your page and figure out the best locator, prioritizing [role, text and test id locators](./locators.md). If the generator finds multiple elements matching the locator, it will improve the locator to make it resilient that uniquely identify the target element.

View File

@ -3,6 +3,8 @@ id: dialogs
title: "Dialogs"
---
## Introduction
Playwright can interact with the web page dialogs such as [`alert`](https://developer.mozilla.org/en-US/docs/Web/API/Window/alert), [`confirm`](https://developer.mozilla.org/en-US/docs/Web/API/Window/confirm), [`prompt`](https://developer.mozilla.org/en-US/docs/Web/API/Window/prompt) as well as [`beforeunload`](https://developer.mozilla.org/en-US/docs/Web/API/Window/beforeunload_event) confirmation.
## alert(), confirm(), prompt() dialogs

View File

@ -3,9 +3,9 @@ id: docker
title: "Docker"
---
[Dockerfile.jammy] can be used to run Playwright scripts in Docker environment. These image includes all the dependencies needed to run browsers in a Docker container, and also include the browsers themselves.
## Introduction
<!-- TOC -->
[Dockerfile.jammy] can be used to run Playwright scripts in Docker environment. These image includes all the dependencies needed to run browsers in a Docker container, and also include the browsers themselves.
## Usage

View File

@ -3,7 +3,7 @@ id: downloads
title: "Downloads"
---
## Introduction
For every attachment downloaded by the page, [`event: Page.download`] event is emitted. All these attachments are downloaded into a temporary folder. You can obtain the download url, file name and payload stream using the [Download] object from the event.

View File

@ -3,6 +3,8 @@ id: emulation
title: "Emulation"
---
## Introduction
With Playwright you can test your app on any browser as well as emulate a real device such as a mobile phone or tablet. Simply configure the devices you would like to emulate and Playwright will simulate the browser behavior such as `"userAgent"`, `"screenSize"`, `"viewport"` and if it `"hasTouch"` enabled. You can also emulate the `"geolocation"`, `"locale"` and `"timezone"` for all tests or for a specific test as well as set the `"permissions"` to show notifications or change the `"colorScheme"`.
## Devices

View File

@ -3,6 +3,8 @@ id: evaluating
title: "Evaluating JavaScript"
---
## Introduction
Playwright scripts run in your Playwright environment. Your page scripts run in the browser page environment. Those environments don't intersect, they are running in different virtual machines in different processes and even potentially on different computers.
The [`method: Page.evaluate`] API can run a JavaScript function in the context

View File

@ -3,6 +3,8 @@ id: events
title: "Events"
---
## Introduction
Playwright allows listening to various types of events happening on the web page, such as network requests, creation of child pages, dedicated workers etc. There are several ways to subscribe to such events such as waiting for events or adding or removing event listeners.
## Waiting for event

View File

@ -2,9 +2,6 @@
id: extensibility
title: "Extensibility"
---
<!-- TOC -->
## Custom selector engines
Playwright supports custom selector engines, registered with [`method: Selectors.register`].

View File

@ -3,6 +3,8 @@ id: frames
title: "Frames"
---
## Introduction
A [Page] can have one or more [Frame] objects attached to it. Each page has a main frame and page-level interactions
(like `click`) are assumed to operate in the main frame.

View File

@ -5,6 +5,8 @@ title: "Getting started - VS Code"
import LiteYouTube from '@site/src/components/LiteYouTube';
## Introduction
Playwright Test was created specifically to accommodate the needs of end-to-end testing. Playwright supports all modern rendering engines including Chromium, WebKit, and Firefox. Test on Windows, Linux, and macOS, locally or on CI, headless or headed with native mobile emulation of Google Chrome for Android and Mobile Safari.
Get started by installing Playwright and generating a test to see it in action. Alternatively you can also get started and run your tests using the [CLI](./intro.md).

View File

@ -3,6 +3,8 @@ id: handles
title: "Handles"
---
## Introduction
Playwright can create handles to the page DOM elements or any other objects inside the
page. These handles live in the Playwright process, whereas the actual objects live
in the browser. There are two types of handles:

View File

@ -3,6 +3,8 @@ id: input
title: "Actions"
---
## Introduction
Playwright can interact with HTML Input elements such as text inputs, checkboxes, radio buttons, select options, mouse clicks, type characters, keys and shortcuts as well as upload files and focus elements.
## Text input

View File

@ -3,6 +3,8 @@ id: intro
title: "Installation"
---
## Introduction
Playwright was created specifically to accommodate the needs of end-to-end testing. Playwright supports all modern rendering engines including Chromium, WebKit, and Firefox. Test on Windows, Linux, and macOS, locally or on CI, headless or headed with native mobile emulation.
You can choose to use [NUnit base classes](./test-runners.md#nunit) or [MSTest base classes](./test-runners.md#mstest) that Playwright provides to write end-to-end tests. These classes support running tests on multiple browser engines, parallelizing tests, adjusting launch/context options and getting a [Page]/[BrowserContext] instance per test out of the box. Alternatively you can use the [library](./library.md) to manually write the testing infrastructure.

View File

@ -3,6 +3,8 @@ id: intro
title: "Installation"
---
## Introduction
Playwright was created specifically to accommodate the needs of end-to-end testing. Playwright supports all modern rendering engines including Chromium, WebKit, and Firefox. Test on Windows, Linux, and macOS, locally or on CI, headless or headed with native mobile emulation.
Playwright is distributed as a set of [Maven](https://maven.apache.org/what-is-maven.html) modules. The easiest way to use it is to add one dependency to your project's `pom.xml` as described below. If you're not familiar with Maven please refer to its [documentation](https://maven.apache.org/guides/getting-started/maven-in-five-minutes.html).

View File

@ -3,6 +3,8 @@ id: languages
title: "Supported languages"
---
## Introduction
Playwright is available in multiple languages that share the same underlying implementation. All core features for automating the browser are supported in all languages, while testing ecosystem integration is different. Pick the language based on your experience, familiarity with its testing ecosystem and your project constraints. For the best experience pick the test runner that we recommend for each language.
## JavaScript and TypeScript

View File

@ -3,6 +3,8 @@ id: library
title: "Getting started - Library"
---
## Introduction
Playwright can either be used with the [NUnit](./test-runners.md#nunit) or [MSTest](./test-runners.md#mstest), 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.
## Usage

View File

@ -3,6 +3,8 @@ id: library
title: "Library"
---
## Introduction
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 the [Getting Started Guide](./intro.md).

View File

@ -3,6 +3,8 @@ id: locators
title: "Locators"
---
## Introduction
[Locator]s are the central piece of Playwright's auto-waiting and retry-ability. In a nutshell, locators represent
a way to find element(s) on the page at any moment.

View File

@ -3,6 +3,8 @@ id: mock-browser-apis
title: "Mock browser APIs"
---
## Introduction
Playwright provides native support for most of the browser features. However, there are some experimental APIs
and APIs which are not (yet) fully supported by all browsers. Playwright usually doesn't provide dedicated
automation APIs in such cases. You can use mocks to test the behavior of your application in such cases. This guide gives a few examples.

View File

@ -3,6 +3,8 @@ id: navigations
title: "Navigations"
---
## Introduction
Playwright can navigate to URLs and handle navigations caused by the page interactions.
## Basic navigation

View File

@ -3,6 +3,8 @@ id: other-locators
title: "Other locators"
---
## Introduction
:::note
Check out the main [locators guide](./locators) for most common and recommended locators.
:::

View File

@ -3,8 +3,6 @@ id: pages
title: "Pages"
---
<!-- TOC -->
## Pages
Each [BrowserContext] can have multiple pages. A [Page] refers to a single tab or a popup window within a browser

View File

@ -2,6 +2,9 @@
id: pom
title: "Page object models"
---
## Introduction
Large test suites can be structured to optimize ease of authoring and maintenance. Page object models are one such approach to structure your test suite.
A page object represents a part of your web application. An e-commerce web application might have a home page, a listings page and a checkout page. Each of them can be represented by page object models.

View File

@ -3,8 +3,6 @@ id: protractor
title: "Migrating from Protractor"
---
<!-- TOC -->
## Migration Principles
- No need for "webdriver-manager" / Selenium.

View File

@ -3,8 +3,6 @@ id: puppeteer
title: "Migrating from Puppeteer"
---
<!-- TOC -->
## Migration Principles
This guide describes migration to [Playwright Library](./library) and [Playwright Test](./intro.md) from Puppeteer. The APIs have similarities, but Playwright offers much more possibilities for web testing and cross-browser automation.

View File

@ -3,6 +3,8 @@ id: running-tests
title: "Running and debugging tests"
---
## Introduction
You can run a single test, a set of tests or all tests. Tests can be run on different 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 `headless` test run parameter.
- Running all tests

View File

@ -3,6 +3,8 @@ id: running-tests
title: "Running and debugging tests"
---
## Introduction
Playwright tests can be run in a variety of ways. We recommend hooking it up to your favorite test runner, e.g. [JUnit](./test-runners.md) since it gives you the ability to run tests in parallel, run single test, etc.
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 `launch(new BrowserType.LaunchOptions().setHeadless(false))` option.

View File

@ -3,6 +3,8 @@ id: screenshots
title: "Screenshots"
---
## Introduction
Here is a quick way to capture a screenshot and save it into a file:
```js

View File

@ -3,6 +3,8 @@ id: selenium-grid
title: "Selenium Grid"
---
## Introduction
Playwright can connect to [Selenium Grid Hub](https://www.selenium.dev/documentation/grid/) that runs Selenium 4 to launch **Google Chrome** or **Microsoft Edge** browser, instead of running browser on the local machine.
:::warning

View File

@ -3,6 +3,8 @@ id: service-workers-experimental
title: "(Experimental) Service Worker Network Events"
---
## Introduction
:::warning
If you're looking to do general network mocking, routing, and interception, please see the [Network Guide](./network.md) first. Playwright provides built-in APIs for this use case that don't require the information below. However, if you're interested in requests made by Service Workers themselves, please read below.
:::

View File

@ -3,6 +3,8 @@ id: test-annotations
title: "Annotations"
---
## Introduction
Playwright Test supports test annotations to deal with failures, flakiness, skip, focus and tag tests:
- [`method: Test.skip#1`] marks the test as irrelevant. Playwright Test does not run such a test. Use this annotation when the test is not applicable in some configuration.
- [`method: Test.fail#1`] marks the test as failing. Playwright Test will run this test and ensure it does indeed fail. If the test does not fail, Playwright Test will complain.

View File

@ -3,6 +3,8 @@ id: test-assertions
title: "Assertions"
---
## Introduction
Playwright includes test assertions in the form of `expect` function. To make an assertion, call `expect(value)` and choose a matcher that reflects the expectation. There are many [generic matchers](./api/class-genericassertions.md) like `toEqual`, `toContain`, `toBeTruthy` that can be used to assert any conditions.
```js

View File

@ -3,6 +3,8 @@ id: test-cli
title: "Command line"
---
## Introduction
Here are the most common options available in the command line.
- Run all the tests

View File

@ -5,6 +5,8 @@ title: "Components (experimental)"
import LiteYouTube from '@site/src/components/LiteYouTube';
## Introduction
Playwright Test can now test your components.
<LiteYouTube

View File

@ -3,6 +3,8 @@ id: test-configuration
title: "Test configuration"
---
## Introduction
Playwright has many options to configure how your tests are run. You can specify these options in the configuration file. Note that test runner options are **top-level**, do not put them into the `use` section.
## Basic Configuration

View File

@ -3,6 +3,8 @@ id: test-fixtures
title: "Fixtures"
---
## Introduction
Playwright Test is based on the concept of test fixtures. Test fixtures are used to establish environment for each test, giving the test everything it needs and nothing else. Test fixtures are isolated between tests. With fixtures, you can group tests based on their meaning, instead of their common setup.
### Built-in fixtures

View File

@ -3,6 +3,8 @@ id: test-parallel
title: "Parallelism"
---
## Introduction
Playwright Test runs tests in parallel. In order to achieve that, it runs several worker processes that run at the same time. By default, **test files** are run in parallel. Tests in a single file are run in order, in the same worker process.
- You can configure tests using [`test.describe.configure`](#parallelize-tests-in-a-single-file) to run **tests in a single file** in parallel.

View File

@ -2,6 +2,7 @@
id: test-parameterize
title: "Parameterize tests"
---
## Introduction
You can either parameterize tests on a test level or on a project level.

View File

@ -3,6 +3,8 @@ id: test-projects
title: "Projects"
---
## Introduction
A project is logical group of tests running with the same configuration. We use projects so we can run tests on different browsers and devices. Projects are configured in the `playwright.config.ts` file and once configured you can then run your tests on all projects or only on a specific project. You can also use projects to run the same tests in different configurations. For example, you can run the same tests in a logged-in and logged-out state.
By setting up projects you can also run a group of tests with different timeouts or retries or a group of tests against different environments such as staging and production, splitting tests per package/functionality and more.

View File

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

View File

@ -3,6 +3,8 @@ id: test-retries
title: "Retries"
---
## Introduction
Test retries are a way to automatically re-run a test when it fails. This is useful when a test is flaky and fails intermittently. Test retries are configured in the [configuration file](./test-configuration.md).
## Failures

View File

@ -3,6 +3,8 @@ id: test-runners
title: "Test Runners"
---
## Introduction
While Playwright for .NET isn't tied to a particular test runner or testing framework, in our experience
it works best with the built-in .NET test runner, and using NUnit as the test framework. NUnit is
also what we use internally for [our tests](https://github.com/microsoft/playwright-dotnet/tree/main/src/Playwright.Tests).

View File

@ -3,6 +3,8 @@ id: test-runners
title: "Test Runners"
---
## Introduction
With a few lines of code, you can hook up Playwright to your favorite Java test runner.
Playwright and Browser instances can be reused between tests for better performance. We

View File

@ -3,6 +3,8 @@ id: test-runners
title: "Pytest Plugin Reference"
---
## Introduction
Playwright provides a [Pytest](https://docs.pytest.org/en/stable/) plugin to write end-to-end tests. To get started with it, refer to the [getting started guide](./intro.md).
## Usage

View File

@ -3,6 +3,8 @@ id: test-sharding
title: "Sharding"
---
## Introduction
By default, Playwright runs tests in [parallel](/test-parallel.md) and strives for optimal utilization of CPU cores on your machine. In order to achieve even greater parallelisation, you can further scale Playwright test execution by running tests on multiple machines simultaneously. We call this mode of operation "sharding".
## Sharding tests between multiple machines

View File

@ -3,6 +3,8 @@ id: test-snapshots
title: "Visual comparisons"
---
## Introduction
Playwright Test includes the ability to produce and visually compare screenshots using `await expect(page).toHaveScreenshot()`. On first execution, Playwright test will generate reference screenshots. Subsequent runs will compare against the reference.
```js title="example.spec.ts"

View File

@ -3,6 +3,8 @@ id: test-timeouts
title: "Timeouts"
---
## Introduction
Playwright Test has multiple configurable timeouts for various tasks.
|Timeout |Default |Description |

View File

@ -3,6 +3,8 @@ id: test-typescript
title: "TypeScript"
---
## Introduction
Playwright supports TypeScript out of the box. You just write tests in TypeScript, and Playwright will read them, transform to JavaScript and run.
## tsconfig.json

View File

@ -3,6 +3,8 @@ id: test-use-options
title: "Test use options"
---
## Introduction
In addition to configuring the test runner you can also configure [Emulation](#emulation-options), [Network](#network-options) and [Recording](#recording-options) for the [Browser] or [BrowserContext]. These options are passed to the `use: {}` object in the Playwright config.
### Basic Options

View File

@ -3,6 +3,8 @@ id: test-webserver
title: "Web server"
---
## Introduction
Playwright comes with a `webserver` option in the config file which gives you the ability to launch a local dev server before running your tests. This is ideal for when writing your tests during development and when you don't have a staging or production url to test against.
## Configuring a web server

View File

@ -3,8 +3,6 @@ id: testing-library
title: "Migrating from Testing Library"
---
<!-- TOC -->
## Migration principles
This guide describes migration to Playwright's [Experimental Component Testing](./test-components) from [DOM Testing Library](https://testing-library.com/docs/dom-testing-library/intro/), [React Testing Library](https://testing-library.com/docs/react-testing-library/intro/), [Vue Testing Library](https://testing-library.com/docs/vue-testing-library/intro) and [Svelte Testing Library](https://testing-library.com/docs/svelte-testing-library/intro).

View File

@ -3,6 +3,8 @@ id: multithreading
title: "Multithreading"
---
## Introduction
Playwright Java is not thread safe, i.e. all its methods as well as methods on all objects created by it (such as [BrowserContext], [Browser], [Page] etc.) are expected to be called on the same thread where the Playwright object was created or proper synchronization should be implemented to ensure only one thread calls Playwright methods at any given time. Having said that it's okay to create multiple Playwright instances each on its own thread.
Here is an example where three playwright instances are created each on its own thread. Each instance launches its own browser process and runs the test against it.
@ -76,4 +78,4 @@ page.navigate("https://playwright.dev");
System.out.println("-- did navigate --");
// Block current thread for 60s and ensure the events are dispatched.
page.waitForTimeout(60_000);
```
```

View File

@ -3,6 +3,8 @@ id: videos
title: "Videos"
---
## Introduction
With Playwright you can record videos for your tests.
## Record video

View File

@ -3,6 +3,8 @@ id: webview2
title: "WebView2"
---
## Introduction
The following will explain how to use Playwright with [Microsoft Edge WebView2](https://docs.microsoft.com/en-us/microsoft-edge/webview2/). WebView2 is a WinForms control, which will use Microsoft Edge under the hood to render web content. It is a part of the Microsoft Edge browser and is available on Windows 10 and Windows 11. Playwright can be used to automate WebView2 applications and can be used to test web content in WebView2. For connecting to WebView2, Playwright uses [`method: BrowserType.connectOverCDP`] which connects to it via the Chrome DevTools Protocol (CDP).
## Overview

View File

@ -3,6 +3,8 @@ id: writing-tests
title: "Writing tests"
---
## Introduction
Playwright assertions are created specifically for the dynamic web. Checks are automatically retried until the necessary conditions are met. Playwright comes with [auto-wait](./actionability.md) built in meaning it waits for elements to be actionable prior to performing actions. Playwright provides the [Expect](./test-assertions) function to write assertions.
Take a look at the example test below to see how to write a test using using [locators](/locators.md) and web first assertions.

View File

@ -3,6 +3,8 @@ id: writing-tests
title: "Writing tests"
---
## Introduction
Playwright assertions are created specifically for the dynamic web. Checks are automatically retried until the necessary conditions are met. Playwright comes with [auto-wait](./actionability.md) built in meaning it waits for elements to be actionable prior to performing actions. Playwright provides [assertThat](./test-assertions.md) overloads to write assertions.
Take a look at the example test below to see how to write a test using web first assertions, locators and selectors.