From 829609dac01728d3d8c4154f1326a04a12497c8f Mon Sep 17 00:00:00 2001 From: Debbie O'Brien Date: Fri, 8 Sep 2023 17:13:00 +0200 Subject: [PATCH] docs: writing tests python merge with node (#26926) --- docs/src/intro-python.md | 26 +++--- docs/src/writing-tests-js.md | 47 +++++----- docs/src/writing-tests-python.md | 152 ++++++++++++++++++++++++------- 3 files changed, 159 insertions(+), 66 deletions(-) diff --git a/docs/src/intro-python.md b/docs/src/intro-python.md index 77bf361a12..c4e4f778fe 100644 --- a/docs/src/intro-python.md +++ b/docs/src/intro-python.md @@ -2,9 +2,17 @@ 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 will learn** + +- [How to install Playwright](/intro.md#installing-playwright) +- [How to run the example test](/intro.md#running-the-example-test) + +## Installing Playwright + Playwright recommends using the official [Playwright Pytest plugin](./test-runners.md) to write end-to-end tests. It provides context isolation, running it on multiple browser configurations out of the box. Alternatively you can use the [library](./library.md) to manually write the testing infrastructure with your preferred test-runner. The Pytest plugin utilizes the sync version of Playwright, there is also an async version accessible via the library. Get started by installing Playwright and running the example test to see it in action. @@ -47,27 +55,23 @@ playwright install ## Add Example Test -Create a file that follows the `test_` prefix convention, such as `test_my_application.py`, inside the current working directory or in a sub-directory with the code below: +Create a file that follows the `test_` prefix convention, such as `test_example.py`, inside the current working directory or in a sub-directory with the code below. Make sure your test name also follows the `test_` prefix convention. -```py title="test_my_application.py" +```py title="test_example.py" import re from playwright.sync_api import Page, expect - -def test_homepage_has_Playwright_in_title_and_get_started_link_linking_to_the_intro_page(page: Page): +def test_has_title(page: Page): page.goto("https://playwright.dev/") # Expect a title "to contain" a substring. expect(page).to_have_title(re.compile("Playwright")) - # create a locator - get_started = page.get_by_role("link", name="Get started") - - # Expect an attribute "to be strictly equal" to the value. - expect(get_started).to_have_attribute("href", "/docs/intro") +def test_get_started_link(page: Page): + page.goto("https://playwright.dev/") # Click the get started link. - get_started.click() + page.get_by_role("link", name="Get started").click() # Expects page to have a heading with the name of Installation. expect(page.get_by_role("heading", name="Installation")).to_be_visible() @@ -75,7 +79,7 @@ def test_homepage_has_Playwright_in_title_and_get_started_link_linking_to_the_in ## Running the Example Test -By default tests will be run on chromium. This can be configured via the CLI options. Tests are run in headless mode meaning no browser UI 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 [CLI options](./running-tests.md). Tests are run in headless mode meaning no browser UI will open up when running the tests. Results of the tests and test logs will be shown in the terminal. ```bash pytest diff --git a/docs/src/writing-tests-js.md b/docs/src/writing-tests-js.md index cfa1e9075e..2cabde1564 100644 --- a/docs/src/writing-tests-js.md +++ b/docs/src/writing-tests-js.md @@ -2,6 +2,7 @@ id: writing-tests title: "Writing tests" --- +## Introduction Playwright tests are simple, they @@ -51,12 +52,12 @@ test('get started link', async ({ page }) => { await expect(page.getByRole('heading', { name: 'Installation' })).toBeVisible(); }); ``` - + :::note -Add `// @ts-check` at the start of each test file when using JavaScript in -VS Code to get automatic type checking. +Add `// @ts-check` at the start of each test file when using JavaScript in VS Code to get automatic type checking. ::: + ## Actions ### Navigation @@ -68,21 +69,22 @@ will be able to interact with the page elements. await page.goto('https://playwright.dev/'); ``` +```python +page.goto("https://playwright.dev/") +``` + Playwright will wait for page to reach the load state prior to moving forward. Learn more about the [`method: Page.goto`] options. ### Interactions -Performing actions starts with locating the elements. Playwright uses -[Locators API](./locators.md) for that. Locators represent a way to find -element(s) on the page at any moment, learn more about the -[different types](./locators.md) of locators available. Playwright will wait for the element to be [actionable](./actionability.md) -prior to performing the action, so there is no need to wait for it to become available. +Performing actions starts with locating the elements. Playwright uses [Locators API](./locators.md) for that. Locators represent a way to find element(s) on the page at any moment, learn more about the [different types](./locators.md) of locators available. Playwright will wait for the element to be [actionable](./actionability.md) prior to performing the action, so there is no need to wait for it to become available. ```js // Create a locator. const getStarted = page.getByRole('link', { name: 'Get started' }); + // Click it. await getStarted.click(); ``` @@ -93,11 +95,9 @@ In most cases, it'll be written in one line: await page.getByRole('link', { name: 'Get started' }).click(); ``` - ### Basic actions -This is the list of the most popular Playwright actions. Note that there are -many more, so make sure to check the [Locator API](./api/class-locator.md) section to +This is the list of the most popular Playwright actions. Note that there are many more, so make sure to check the [Locator API](./api/class-locator.md) section to learn more about them. | Action | Description | @@ -113,7 +113,7 @@ learn more about them. | [`method: Locator.selectOption`] | Select option in the drop down | ## Assertions - + Playwright includes [test assertions](./test-assertions.md) 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 like `toEqual`, `toContain`, `toBeTruthy` that can be used to assert any conditions. @@ -127,9 +127,7 @@ Playwright also includes async matchers that will wait until the expected condit ```js await expect(page).toHaveTitle(/Playwright/); ``` - - - + Here is the list of the most popular async assertions. Note that there are [many more](./test-assertions.md) to get familiar with: | Assertion | Description | @@ -144,16 +142,20 @@ Here is the list of the most popular async assertions. Note that there are [many | [`method: LocatorAssertions.toHaveValue`] | Input element has value | | [`method: PageAssertions.toHaveTitle`] | Page has title | | [`method: PageAssertions.toHaveURL`] | Page has URL | -| [`method: PageAssertions.toHaveScreenshot#1`] | Page has screenshot | - ### Test Isolation - -Playwright Test is based on the concept of [test fixtures](./test-fixtures.md) such as the [built in page fixture](./test-fixtures#built-in-fixtures), which is passed into your test. Pages are isolated between tests due to the Browser Context, which is equivalent to a brand new browser profile, where every test gets a fresh environment, even when multiple tests run in a single Browser. + +Playwright Test is based on the concept of [test fixtures](./test-fixtures.md) such as the [built in page fixture](./test-fixtures#built-in-fixtures), which is passed into your test. Pages are [isolated between tests due to the Browser Context](./browser-contexts), which is equivalent to a brand new browser profile, where every test gets a fresh environment, even when multiple tests run in a single Browser. ```js title="tests/example.spec.ts" -test('basic test', async ({ page }) => { - // ... +import { test } from '@playwright/test'; + +test('example test', async ({ page }) => { + // "page" belongs to an isolated BrowserContext, created for this specific test. +}); + +test('another test', async ({ page }) => { + // "page" in this second test is completely isolated from the first test. }); ``` @@ -182,3 +184,6 @@ test.describe('navigation', () => { - [Run single test, multiple tests, headed mode](./running-tests.md) - [Generate tests with Codegen](./codegen-intro.md) - [See a trace of your tests](./trace-viewer-intro.md) +- [Explore UI Mode](./test-ui-mode.md) +- [Run tests on CI with GitHub Actions](./ci-intro.md) + diff --git a/docs/src/writing-tests-python.md b/docs/src/writing-tests-python.md index 45efdb2223..fb59362e05 100644 --- a/docs/src/writing-tests-python.md +++ b/docs/src/writing-tests-python.md @@ -2,39 +2,114 @@ 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 an [expect](./test-assertions.md) function to write assertions. +Playwright tests are simple, they -Take a look at the example test below to see how to write a test using [locators](/locators.md) and web first assertions. +- **perform actions**, and +- **assert the state** against expectations. -```python +There is no need to wait for anything prior to performing an action: Playwright +automatically waits for the wide range of [actionability](./actionability.md) +checks to pass prior to performing each action. + +There is also no need to deal with the race conditions when performing the checks - +Playwright assertions are designed in a way that they describe the expectations +that need to be eventually met. + +That's it! These design choices allow Playwright users to forget about flaky +timeouts and racy checks in their tests altogether. + +**You will learn** + +- [How to write the first test](/writing-tests.md#first-test) +- [How to perform actions](/writing-tests.md#actions) +- [How to use assertions](/writing-tests.md#assertions) +- [How tests run in isolation](/writing-tests.md#test-isolation) +- [How to use test hooks](/writing-tests.md#using-test-hooks) + +## First test + +Take a look at the following example to see how to write a test. Note how the file name follows the `test_` prefix convention as well as each test name. + +```python title="test_example.py" import re from playwright.sync_api import Page, expect - -def test_homepage_has_Playwright_in_title_and_get_started_link_linking_to_the_intro_page(page: Page): +def test_has_title(page: Page): page.goto("https://playwright.dev/") # Expect a title "to contain" a substring. expect(page).to_have_title(re.compile("Playwright")) - # create a locator - get_started = page.get_by_role("link", name="Get started") - - # Expect an attribute "to be strictly equal" to the value. - expect(get_started).to_have_attribute("href", "/docs/intro") +def test_get_started_link(page: Page): + page.goto("https://playwright.dev/") # Click the get started link. - get_started.click() + page.get_by_role("link", name="Get started").click() # Expects page to have a heading with the name of Installation. expect(page.get_by_role("heading", name="Installation")).to_be_visible() ``` +## Actions -### Assertions +### Navigation -Playwright provides the [`expect`](./test-assertions.md) function which will wait until the expected condition is met. +Most of the tests will start with navigating page to the URL. After that, test +will be able to interact with the page elements. + +```js +await page.goto('https://playwright.dev/'); +``` + +```python +page.goto("https://playwright.dev/") +``` + +Playwright will wait for page to reach the load state prior to moving forward. +Learn more about the [`method: Page.goto`] options. + +### Interactions + +Performing actions starts with locating the elements. Playwright uses [Locators API](./locators.md) for that. Locators represent a way to find element(s) on the page at any moment, learn more about the [different types](./locators.md) of locators available. Playwright will wait for the element to be [actionable](./actionability.md) prior to performing the action, so there is no need to wait for it to become available. + + +```python +# Create a locator. +get_started = page.get_by_role("link", name="Get started") + +# Click it. +get_started.click() +``` + +In most cases, it'll be written in one line: + +```python +page.get_by_role("link", name="Get started").click() +``` + +### Basic actions + +This is the list of the most popular Playwright actions. Note that there are many more, so make sure to check the [Locator API](./api/class-locator.md) section to +learn more about them. + +| Action | Description | +| :- | :- | +| [`method: Locator.check`] | Check the input checkbox | +| [`method: Locator.click`] | Click the element | +| [`method: Locator.uncheck`] | Uncheck the input checkbox | +| [`method: Locator.hover`] | Hover mouse over the element | +| [`method: Locator.fill`] | Fill the form field, input text | +| [`method: Locator.focus`] | Focus the element | +| [`method: Locator.press`] | Press single key | +| [`method: Locator.setInputFiles`] | Pick files to upload | +| [`method: Locator.selectOption`] | Select option in the drop down | + +## Assertions +* langs: python + +Playwright includes [assertions](./test-assertions.md) that will wait until the expected condition is met. Using these assertions allows making the tests non-flaky and resilient. For example, this code will wait until the page gets the title containing "Playwright": ```python import re @@ -43,48 +118,56 @@ from playwright.sync_api import expect expect(page).to_have_title(re.compile("Playwright")) ``` +Here is the list of the most popular async assertions. Note that there are [many more](./test-assertions.md) to get familiar with: -### Locators +| Assertion | Description | +| :- | :- | +| [`method: LocatorAssertions.toBeChecked`] | Checkbox is checked | +| [`method: LocatorAssertions.toBeEnabled`] | Control is enabled | +| [`method: LocatorAssertions.toBeVisible`] | Element is visible | +| [`method: LocatorAssertions.toContainText`] | Element contains text | +| [`method: LocatorAssertions.toHaveAttribute`] | Element has attribute | +| [`method: LocatorAssertions.toHaveCount`] | List of elements has given length | +| [`method: LocatorAssertions.toHaveText`] | Element matches text | +| [`method: LocatorAssertions.toHaveValue`] | Input element has value | +| [`method: PageAssertions.toHaveTitle`] | Page has title | +| [`method: PageAssertions.toHaveURL`] | Page has URL | -[Locators](./locators.md) are the central piece of Playwright's auto-waiting and retry-ability. Locators represent a way to find element(s) on the page at any moment and are used to perform actions on elements such as `.click` `.fill` etc. - -```python -from playwright.sync_api import expect - -get_started = page.get_by_role("link", name="Get started") - -expect(get_started).to_have_attribute("href", "/docs/installation") -get_started.click() -``` ### Test Isolation -The Playwright Pytest plugin is based on the concept of test fixtures such as the [built in page fixture](./test-runners.md), which is passed into your test. Pages are isolated between tests due to the Browser Context, which is equivalent to a brand new browser profile, where every test gets a fresh environment, even when multiple tests run in a single Browser. +The Playwright Pytest plugin is based on the concept of test fixtures such as the [built in page fixture](./test-runners.md), which is passed into your test. Pages are [isolated between tests due to the Browser Context](./browser-contexts), 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. -```python +```python title="test_example.py" from playwright.sync_api import Page -def test_basic_test(page: Page): +def test_example_test(page: Page): pass - # ... + # "page" belongs to an isolated BrowserContext, created for this specific test. + +def test_another_test(page: Page): + pass + # "page" in this second test is completely isolated from the first test. ``` ### Using Test Hooks You can use various [fixtures](https://docs.pytest.org/en/6.2.x/fixture.html#autouse-fixtures-fixtures-you-don-t-have-to-request) to execute code before or after your tests and to share objects between them. A `function` scoped fixture e.g. with autouse behaves like a beforeEach/afterEach. And a `module` scoped fixture with autouse behaves like a beforeAll/afterAll which runs before all and after all the tests. -```python +```python title="test_example.py" import pytest -from playwright.sync_api import Page - +from playwright.sync_api import Page, expect @pytest.fixture(scope="function", autouse=True) def before_each_after_each(page: Page): - print("beforeEach") + + print("before the test runs") + # Go to the starting url before each test. page.goto("https://playwright.dev/") yield - print("afterEach") + + print("after the test runs") def test_main_navigation(page: Page): # Assertions use the expect API. @@ -94,5 +177,6 @@ def test_main_navigation(page: Page): ## What's Next - [Run single test, multiple tests, headed mode](./running-tests.md) -- [Generate tests with Codegen](./codegen.md) +- [Generate tests with Codegen](./codegen-intro.md) - [See a trace of your tests](./trace-viewer-intro.md) +- [Run tests on CI with GitHub Actions](./ci-intro.md)