docs: new Python onboarding story (#15782)
This commit is contained in:
Max Schmitt
GitHub
parent
9b3bd92071
commit
dcb83d9db0
|
|
@ -114,7 +114,7 @@ def test_should_create_feature_request(api_request_context: APIRequestContext) -
|
|||
|
||||
### Setup and teardown
|
||||
|
||||
These tests assume that repository exists. You probably want to create a new one before running tests and delete it afterwards. Use a [session fixture](https://docs.pytest.org/en/6.2.x/fixture.html#fixture-scopes) for that. The part before `yield` is the before all and after is the after all.
|
||||
These tests assume that repository exists. You probably want to create a new one before running tests and delete it afterwards. Use a [session fixture](https://docs.pytest.org/en/stable/fixture.html#fixture-scopes) for that. The part before `yield` is the before all and after is the after all.
|
||||
|
||||
```python
|
||||
# ...
|
||||
|
|
|
|||
|
|
@ -5,9 +5,9 @@ title: "Installation"
|
|||
|
||||
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#nunit) 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.
|
||||
You can choose to use [NUnit base classes](./test-runners.md#nunit) or [MSTest base classes](./test-runners.md#nunit) 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.
|
||||
|
||||
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
|
||||
defaultValue="nunit"
|
||||
|
|
@ -34,7 +34,7 @@ cd PlaywrightTests
|
|||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
Install the necessary Playwright dependencies:
|
||||
2. Install the necessary Playwright dependencies:
|
||||
|
||||
<Tabs
|
||||
defaultValue="nunit"
|
||||
|
|
@ -59,13 +59,13 @@ dotnet add package Microsoft.Playwright.MSTest
|
|||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
Build the project so the `playwright.ps1` is available inside the `bin` directory:
|
||||
3. Build the project so the `playwright.ps1` is available inside the `bin` directory:
|
||||
|
||||
```bash
|
||||
dotnet build
|
||||
```
|
||||
|
||||
Install required browsers by replacing `netX` with the actual output folder name, e.g. `net6.0`:
|
||||
4. Install required browsers by replacing `netX` with the actual output folder name, e.g. `net6.0`:
|
||||
|
||||
```bash
|
||||
pwsh bin\Debug\netX\playwright.ps1 install
|
||||
|
|
@ -95,25 +95,24 @@ namespace PlaywrightTests;
|
|||
public class Tests : PageTest
|
||||
{
|
||||
[Test]
|
||||
async public Task ShouldHaveTheCorrectSlogan()
|
||||
async public Task HomepageHasPlaywrightInTitleAndGetStartedLinkLinkingtoTheIntroPage()
|
||||
{
|
||||
await Page.GotoAsync("https://playwright.dev");
|
||||
await Expect(Page.Locator("text=enables reliable end-to-end testing for modern web apps")).ToBeVisibleAsync();
|
||||
}
|
||||
|
||||
[Test]
|
||||
public async Task ShouldHaveTheCorrectTitle()
|
||||
{
|
||||
await Page.GotoAsync("https://playwright.dev");
|
||||
var title = Page.Locator(".navbar__inner .navbar__title");
|
||||
await Expect(title).ToHaveTextAsync("Playwright");
|
||||
}
|
||||
// Expect a title "to contain" a substring.
|
||||
await Expect(Page).ToHaveTitleAsync(new Regex("Playwright"));
|
||||
|
||||
[Test]
|
||||
public async Task ShouldAdd()
|
||||
{
|
||||
var result = await Page.EvaluateAsync<int>("() => 7 + 3");
|
||||
Assert.AreEqual(10, result);
|
||||
// create a locator
|
||||
var getStarted = Page.Locator("text=Get Started");
|
||||
|
||||
// Expect an attribute "to be strictly equal" to the value.
|
||||
await Expect(getStarted).ToHaveAttributeAsync("href", "/docs/intro");
|
||||
|
||||
// Click the get started link.
|
||||
await getStarted.ClickAsync();
|
||||
|
||||
// Expects the URL to contain intro.
|
||||
await Expect(Page).ToHaveURLAsync(new Regex(".*intro"));
|
||||
}
|
||||
}
|
||||
```
|
||||
|
|
@ -129,25 +128,24 @@ namespace PlaywrightTests;
|
|||
public class UnitTest1 : PageTest
|
||||
{
|
||||
[TestMethod]
|
||||
async public Task ShouldHaveTheCorrectSlogan()
|
||||
async public Task HomepageHasPlaywrightInTitleAndGetStartedLinkLinkingtoTheIntroPage()
|
||||
{
|
||||
await Page.GotoAsync("https://playwright.dev");
|
||||
await Expect(Page.Locator("text=enables reliable end-to-end testing for modern web apps")).ToBeVisibleAsync();
|
||||
}
|
||||
|
||||
[TestMethod]
|
||||
public async Task ShouldHaveTheCorrectTitle()
|
||||
{
|
||||
await Page.GotoAsync("https://playwright.dev");
|
||||
var title = Page.Locator(".navbar__inner .navbar__title");
|
||||
await Expect(title).ToHaveTextAsync("Playwright");
|
||||
}
|
||||
// Expect a title "to contain" a substring.
|
||||
await Expect(Page).ToHaveTitleAsync(new Regex("Playwright"));
|
||||
|
||||
[TestMethod]
|
||||
public async Task ShouldAdd()
|
||||
{
|
||||
var result = await Page.EvaluateAsync<int>("() => 7 + 3");
|
||||
Assert.AreEqual(10, result);
|
||||
// create a locator
|
||||
var getStarted = Page.Locator("text=Get Started");
|
||||
|
||||
// Expect an attribute "to be strictly equal" to the value.
|
||||
await Expect(getStarted).ToHaveAttributeAsync("href", "/docs/intro");
|
||||
|
||||
// Click the get started link.
|
||||
await getStarted.ClickAsync();
|
||||
|
||||
// Expects the URL to contain intro.
|
||||
await Expect(Page).ToHaveURLAsync(new Regex(".*intro"));
|
||||
}
|
||||
}
|
||||
```
|
||||
|
|
|
|||
|
|
@ -1,222 +1,70 @@
|
|||
---
|
||||
id: intro
|
||||
title: "Getting started"
|
||||
title: "Installation"
|
||||
---
|
||||
|
||||
<!-- TOC -->
|
||||
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.
|
||||
|
||||
- [Release notes](./release-notes.md)
|
||||
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.
|
||||
|
||||
## Installation
|
||||
Get started by installing Playwright and running the example test to see it in action.
|
||||
|
||||
See [system requirements](#system-requirements).
|
||||
|
||||
### Pip
|
||||
|
||||
[](https://pypi.python.org/pypi/playwright/)
|
||||
Install the [Pytest plugin](https://pypi.org/project/pytest-playwright/):
|
||||
|
||||
```bash
|
||||
pip install pytest-playwright
|
||||
```
|
||||
|
||||
Install the required browsers:
|
||||
|
||||
```bash
|
||||
pip install --upgrade pip
|
||||
pip install playwright
|
||||
playwright install
|
||||
```
|
||||
|
||||
### Conda
|
||||
## Add Example Test
|
||||
|
||||
[](https://anaconda.org/Microsoft/playwright)
|
||||
Create a `test_my_application.py` file inside the current working directory or in a sub-directory with the code below:
|
||||
|
||||
```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, foo
|
||||
):
|
||||
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.locator("text=Get Started")
|
||||
|
||||
# Expect an attribute "to be strictly equal" to the value.
|
||||
expect(get_started).to_have_attribute("href", "/docs/intro")
|
||||
|
||||
# Click the get started link.
|
||||
get_started.click()
|
||||
|
||||
# Expects the URL to contain intro.
|
||||
expect(page).to_have_url(re.compile(".*intro"))
|
||||
```
|
||||
|
||||
## 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.
|
||||
|
||||
```bash
|
||||
conda config --add channels conda-forge
|
||||
conda config --add channels microsoft
|
||||
conda install playwright
|
||||
playwright install
|
||||
pytest
|
||||
```
|
||||
|
||||
These commands download the Playwright package and install browser binaries for Chromium, Firefox and WebKit. To modify this behavior see [installation parameters](./browsers.md#installing-browsers).
|
||||
See our doc on [Running Tests](./running-tests.md) to learn more about running tests in headed mode, running multiple tests, running specific tests etc.
|
||||
|
||||
## Usage
|
||||
## What's next
|
||||
|
||||
Once installed, you can `import` Playwright in a Python script, and launch any of the 3 browsers (`chromium`, `firefox` and `webkit`).
|
||||
|
||||
```py
|
||||
from playwright.sync_api import sync_playwright
|
||||
|
||||
with sync_playwright() as p:
|
||||
browser = p.chromium.launch()
|
||||
page = browser.new_page()
|
||||
page.goto("http://playwright.dev")
|
||||
print(page.title())
|
||||
browser.close()
|
||||
```
|
||||
|
||||
Playwright supports two variations of the API: synchronous and asynchronous. If your modern project uses [asyncio](https://docs.python.org/3/library/asyncio.html), you should use async API:
|
||||
|
||||
```py
|
||||
import asyncio
|
||||
from playwright.async_api import async_playwright
|
||||
|
||||
async def main():
|
||||
async with async_playwright() as p:
|
||||
browser = await p.chromium.launch()
|
||||
page = await browser.new_page()
|
||||
await page.goto("http://playwright.dev")
|
||||
print(await page.title())
|
||||
await browser.close()
|
||||
|
||||
asyncio.run(main())
|
||||
```
|
||||
|
||||
## First script
|
||||
|
||||
In our first script, we will navigate to `whatsmyuseragent.org` and take a screenshot in WebKit.
|
||||
|
||||
```py
|
||||
from playwright.sync_api import sync_playwright
|
||||
|
||||
with sync_playwright() as p:
|
||||
browser = p.webkit.launch()
|
||||
page = browser.new_page()
|
||||
page.goto("http://whatsmyuseragent.org/")
|
||||
page.screenshot(path="example.png")
|
||||
browser.close()
|
||||
```
|
||||
|
||||
By default, Playwright runs the browsers in headless mode. To see the browser UI, pass the `headless=False` flag while launching the browser. You can also use [`option: slowMo`] to slow down execution. Learn more in the debugging tools [section](./debug.md).
|
||||
|
||||
```py
|
||||
firefox.launch(headless=False, slow_mo=50)
|
||||
```
|
||||
|
||||
## Record scripts
|
||||
|
||||
[Command line tools](./cli.md) can be used to record user interactions and generate Python code.
|
||||
|
||||
```bash
|
||||
playwright codegen wikipedia.org
|
||||
```
|
||||
|
||||
## With Pytest
|
||||
|
||||
See [here](./test-runners.md) for Pytest instructions and examples.
|
||||
|
||||
## Interactive mode (REPL)
|
||||
|
||||
Blocking REPL, as in CLI via Python directly:
|
||||
|
||||
```bash
|
||||
python
|
||||
```
|
||||
|
||||
```py
|
||||
>>> from playwright.sync_api import sync_playwright
|
||||
>>> playwright = sync_playwright().start()
|
||||
# Use playwright.chromium, playwright.firefox or playwright.webkit
|
||||
# Pass headless=False to launch() to see the browser UI
|
||||
>>> browser = playwright.chromium.launch()
|
||||
>>> page = browser.new_page()
|
||||
>>> page.goto("http://whatsmyuseragent.org/")
|
||||
>>> page.screenshot(path="example.png")
|
||||
>>> browser.close()
|
||||
>>> playwright.stop()
|
||||
```
|
||||
|
||||
Async REPL such as `asyncio` REPL:
|
||||
|
||||
```bash
|
||||
python -m asyncio
|
||||
```
|
||||
|
||||
```py
|
||||
>>> from playwright.async_api import async_playwright
|
||||
>>> playwright = await async_playwright().start()
|
||||
>>> browser = await playwright.chromium.launch()
|
||||
>>> page = await browser.new_page()
|
||||
>>> await page.goto("http://whatsmyuseragent.org/")
|
||||
>>> await page.screenshot(path="example.png")
|
||||
>>> await browser.close()
|
||||
>>> await playwright.stop()
|
||||
```
|
||||
|
||||
## Pyinstaller
|
||||
|
||||
You can use Playwright with [Pyinstaller](https://www.pyinstaller.org/) to create standalone executables.
|
||||
|
||||
```py
|
||||
# main.py
|
||||
from playwright.sync_api import sync_playwright
|
||||
|
||||
with sync_playwright() as p:
|
||||
browser = p.chromium.launch()
|
||||
page = browser.new_page()
|
||||
page.goto("http://whatsmyuseragent.org/")
|
||||
page.screenshot(path="example.png")
|
||||
browser.close()
|
||||
```
|
||||
|
||||
If you want to bundle browsers with the executables:
|
||||
|
||||
```bash tab=bash-bash
|
||||
PLAYWRIGHT_BROWSERS_PATH=0 playwright install chromium
|
||||
pyinstaller -F main.py
|
||||
```
|
||||
|
||||
```batch tab=bash-batch
|
||||
set PLAYWRIGHT_BROWSERS_PATH=0
|
||||
playwright install chromium
|
||||
pyinstaller -F main.py
|
||||
```
|
||||
|
||||
```powershell tab=bash-powershell
|
||||
$env:PLAYWRIGHT_BROWSERS_PATH="0"
|
||||
playwright install chromium
|
||||
pyinstaller -F main.py
|
||||
```
|
||||
|
||||
:::note
|
||||
Bundling the browsers with the executables will generate bigger binaries.
|
||||
It is recommended to only bundle the browsers you use.
|
||||
:::
|
||||
|
||||
## Known issues
|
||||
|
||||
### `time.sleep()` leads to outdated state
|
||||
|
||||
You should use `page.wait_for_timeout(5000)` instead of `time.sleep(5)` and it is better to not wait for a timeout at all, but sometimes it is useful for debugging. In these cases, use our wait method instead of the `time` module. This is because we internally rely on asynchronous operations and when using `time.sleep(5)` they can't get processed correctly.
|
||||
|
||||
|
||||
### incompatible with `SelectorEventLoop` of `asyncio` on Windows
|
||||
|
||||
Playwright runs the driver in a subprocess, so it requires `ProactorEventLoop` of `asyncio` on Windows because `SelectorEventLoop` does not supports async subprocesses.
|
||||
|
||||
On Windows Python 3.7, Playwright sets the default event loop to `ProactorEventLoop` as it is default on Python 3.8+.
|
||||
|
||||
### 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.
|
||||
|
||||
|
||||
## 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.
|
||||
- [Write tests using web first assertions, page fixtures and locators](./writing-tests.md)
|
||||
- [Run single tests, multiple tests, headed mode](./running-tests.md)
|
||||
- [Debug tests with the Playwright Debugger](./debug.md)
|
||||
- [Generate tests with Codegen](./codegen.md)
|
||||
- [See a trace of your tests](./trace-viewer.md)
|
||||
|
|
|
|||
206
docs/src/library-python.md
Normal file
206
docs/src/library-python.md
Normal file
|
|
@ -0,0 +1,206 @@
|
|||
---
|
||||
id: library
|
||||
title: "Library"
|
||||
---
|
||||
|
||||
## Installation
|
||||
|
||||
### Pip
|
||||
|
||||
[](https://pypi.python.org/pypi/playwright/)
|
||||
|
||||
```bash
|
||||
pip install --upgrade pip
|
||||
pip install playwright
|
||||
playwright install
|
||||
```
|
||||
|
||||
### Conda
|
||||
|
||||
[](https://anaconda.org/Microsoft/playwright)
|
||||
|
||||
```bash
|
||||
conda config --add channels conda-forge
|
||||
conda config --add channels microsoft
|
||||
conda install playwright
|
||||
playwright install
|
||||
```
|
||||
|
||||
These commands download the Playwright package and install browser binaries for Chromium, Firefox and WebKit. To modify this behavior see [installation parameters](./browsers.md#installing-browsers).
|
||||
|
||||
## Usage
|
||||
|
||||
Once installed, you can `import` Playwright in a Python script, and launch any of the 3 browsers (`chromium`, `firefox` and `webkit`).
|
||||
|
||||
```py
|
||||
from playwright.sync_api import sync_playwright
|
||||
|
||||
with sync_playwright() as p:
|
||||
browser = p.chromium.launch()
|
||||
page = browser.new_page()
|
||||
page.goto("http://playwright.dev")
|
||||
print(page.title())
|
||||
browser.close()
|
||||
```
|
||||
|
||||
Playwright supports two variations of the API: synchronous and asynchronous. If your modern project uses [asyncio](https://docs.python.org/3/library/asyncio.html), you should use async API:
|
||||
|
||||
```py
|
||||
import asyncio
|
||||
from playwright.async_api import async_playwright
|
||||
|
||||
async def main():
|
||||
async with async_playwright() as p:
|
||||
browser = await p.chromium.launch()
|
||||
page = await browser.new_page()
|
||||
await page.goto("http://playwright.dev")
|
||||
print(await page.title())
|
||||
await browser.close()
|
||||
|
||||
asyncio.run(main())
|
||||
```
|
||||
|
||||
## First script
|
||||
|
||||
In our first script, we will navigate to `whatsmyuseragent.org` and take a screenshot in WebKit.
|
||||
|
||||
```py
|
||||
from playwright.sync_api import sync_playwright
|
||||
|
||||
with sync_playwright() as p:
|
||||
browser = p.webkit.launch()
|
||||
page = browser.new_page()
|
||||
page.goto("http://whatsmyuseragent.org/")
|
||||
page.screenshot(path="example.png")
|
||||
browser.close()
|
||||
```
|
||||
|
||||
By default, Playwright runs the browsers in headless mode. To see the browser UI, pass the `headless=False` flag while launching the browser. You can also use [`option: slowMo`] to slow down execution. Learn more in the debugging tools [section](./debug.md).
|
||||
|
||||
```py
|
||||
firefox.launch(headless=False, slow_mo=50)
|
||||
```
|
||||
|
||||
## Interactive mode (REPL)
|
||||
|
||||
You can launch the interactive python REPL:
|
||||
|
||||
```bash
|
||||
python
|
||||
```
|
||||
|
||||
and then launch Playwright within it for quick experimentation:
|
||||
|
||||
```py
|
||||
>>> from playwright.sync_api import sync_playwright
|
||||
>>> playwright = sync_playwright().start()
|
||||
# Use playwright.chromium, playwright.firefox or playwright.webkit
|
||||
# Pass headless=False to launch() to see the browser UI
|
||||
>>> browser = playwright.chromium.launch()
|
||||
>>> page = browser.new_page()
|
||||
>>> page.goto("http://whatsmyuseragent.org/")
|
||||
>>> page.screenshot(path="example.png")
|
||||
>>> browser.close()
|
||||
>>> playwright.stop()
|
||||
```
|
||||
|
||||
Async REPL such as `asyncio` REPL:
|
||||
|
||||
```bash
|
||||
python -m asyncio
|
||||
```
|
||||
|
||||
```py
|
||||
>>> from playwright.async_api import async_playwright
|
||||
>>> playwright = await async_playwright().start()
|
||||
>>> browser = await playwright.chromium.launch()
|
||||
>>> page = await browser.new_page()
|
||||
>>> await page.goto("http://whatsmyuseragent.org/")
|
||||
>>> await page.screenshot(path="example.png")
|
||||
>>> await browser.close()
|
||||
>>> await playwright.stop()
|
||||
```
|
||||
|
||||
## Pyinstaller
|
||||
|
||||
You can use Playwright with [Pyinstaller](https://www.pyinstaller.org/) to create standalone executables.
|
||||
|
||||
```py
|
||||
# main.py
|
||||
from playwright.sync_api import sync_playwright
|
||||
|
||||
with sync_playwright() as p:
|
||||
browser = p.chromium.launch()
|
||||
page = browser.new_page()
|
||||
page.goto("http://whatsmyuseragent.org/")
|
||||
page.screenshot(path="example.png")
|
||||
browser.close()
|
||||
```
|
||||
|
||||
If you want to bundle browsers with the executables:
|
||||
|
||||
```bash tab=bash-bash
|
||||
PLAYWRIGHT_BROWSERS_PATH=0 playwright install chromium
|
||||
pyinstaller -F main.py
|
||||
```
|
||||
|
||||
```batch tab=bash-batch
|
||||
set PLAYWRIGHT_BROWSERS_PATH=0
|
||||
playwright install chromium
|
||||
pyinstaller -F main.py
|
||||
```
|
||||
|
||||
```powershell tab=bash-powershell
|
||||
$env:PLAYWRIGHT_BROWSERS_PATH="0"
|
||||
playwright install chromium
|
||||
pyinstaller -F main.py
|
||||
```
|
||||
|
||||
:::note
|
||||
Bundling the browsers with the executables will generate bigger binaries.
|
||||
It is recommended to only bundle the browsers you use.
|
||||
:::
|
||||
|
||||
## Known issues
|
||||
|
||||
### `time.sleep()` leads to outdated state
|
||||
|
||||
Most likely you don't need to wait manually, since Playwright has [auto-waiting](./actionability.md). If you still rely on it, you should use `page.wait_for_timeout(5000)` instead of `time.sleep(5)` and it is better to not wait for a timeout at all, but sometimes it is useful for debugging. In these cases, use our wait (`wait_for_timeout`) method instead of the `time` module. This is because we internally rely on asynchronous operations and when using `time.sleep(5)` they can't get processed correctly.
|
||||
|
||||
|
||||
### incompatible with `SelectorEventLoop` of `asyncio` on Windows
|
||||
|
||||
Playwright runs the driver in a subprocess, so it requires `ProactorEventLoop` of `asyncio` on Windows because `SelectorEventLoop` does not supports async subprocesses.
|
||||
|
||||
On Windows Python 3.7, Playwright sets the default event loop to `ProactorEventLoop` as it is default on Python 3.8+.
|
||||
|
||||
### 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.
|
||||
|
||||
|
||||
## 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.
|
||||
56
docs/src/running-tests-python.md
Normal file
56
docs/src/running-tests-python.md
Normal file
|
|
@ -0,0 +1,56 @@
|
|||
---
|
||||
id: running-tests
|
||||
title: "Running Tests"
|
||||
---
|
||||
|
||||
You can run a single test, a set of tests or all tests. Tests can be run on one browser or multiple browsers. By default tests are run in a headless manner meaning no browser window will be opened while running the tests and results will be seen in the terminal. If you prefer you can run your tests in headed mode by using the `--headed` flag.
|
||||
|
||||
- Running tests on Chromium
|
||||
|
||||
```bash
|
||||
pytest
|
||||
```
|
||||
|
||||
- Running a single test file
|
||||
|
||||
```bash
|
||||
pytest test_login.py
|
||||
```
|
||||
|
||||
- Run a set of test files
|
||||
|
||||
```bash
|
||||
pytest tests/todo-page/ tests/landing-page/
|
||||
```
|
||||
|
||||
- Run the test with the function name
|
||||
|
||||
```bash
|
||||
pytest -k "test_add_a_todo_item"
|
||||
```
|
||||
|
||||
- Running tests in headed mode
|
||||
|
||||
```bash
|
||||
pytest --headed test_login.py
|
||||
```
|
||||
|
||||
- Running Tests on specific browsers
|
||||
|
||||
```bash
|
||||
pytest test_login.py --browser webkit
|
||||
```
|
||||
|
||||
- Running Tests on multiple browsers
|
||||
|
||||
```bash
|
||||
pytest test_login.py --browser webkit --browser firefox
|
||||
```
|
||||
|
||||
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).
|
||||
|
||||
## What's Next
|
||||
|
||||
- [Debug tests with the Playwright Debugger](./debug.md)
|
||||
- [Generate tests with Codegen](./codegen.md)
|
||||
- [See a trace of your tests](./trace-viewer.md)
|
||||
|
|
@ -1,42 +1,16 @@
|
|||
---
|
||||
id: test-runners
|
||||
title: "Pytest plugin"
|
||||
title: "Pytest Plugin Reference"
|
||||
---
|
||||
|
||||
Write end-to-end tests for your web apps with [Pytest](https://docs.pytest.org/en/stable/).
|
||||
|
||||
<!-- TOC -->
|
||||
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
|
||||
|
||||
```bash
|
||||
pip install pytest-playwright
|
||||
```
|
||||
|
||||
Use the `page` fixture to write a basic test. See [more examples](#examples).
|
||||
|
||||
```py
|
||||
# test_my_application.py
|
||||
def test_example_is_working(page):
|
||||
page.goto("https://example.com")
|
||||
assert page.inner_text('h1') == 'Example Domain'
|
||||
page.locator("text=More information").click()
|
||||
```
|
||||
|
||||
To run your tests, use pytest CLI.
|
||||
To run your tests, use [Pytest](https://docs.pytest.org/en/stable/) CLI.
|
||||
|
||||
```bash
|
||||
# Run tests (Chromium and headless by default)
|
||||
pytest
|
||||
|
||||
# Run tests in headed mode
|
||||
pytest --headed
|
||||
|
||||
# Run tests in a different browser (chromium, firefox, webkit)
|
||||
pytest --browser firefox
|
||||
|
||||
# Run tests in multiple browsers
|
||||
pytest --browser chromium --browser webkit
|
||||
pytest --browser webkit --headedd
|
||||
```
|
||||
|
||||
If you want to add the CLI arguments automatically without specifying them, you can use the [pytest.ini](https://docs.pytest.org/en/stable/reference.html#ini-options-ref) file:
|
||||
|
|
|
|||
|
|
@ -3,9 +3,9 @@ id: writing-tests
|
|||
title: "Writing Tests"
|
||||
---
|
||||
|
||||
Playwright assertions are created specifically for the dynamic web. Checks are automatically retried until the necessary conditions are met. Playwright comes with auto-wait built in meaning it waits for elements to be actionable prior to performing actions. Playwright provides the [Expect](./test-assertions) function to write assertions.
|
||||
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 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
|
||||
defaultValue="nunit"
|
||||
|
|
@ -96,7 +96,7 @@ await Expect(Page).ToHaveTitleAsync(new Regex("Playwright"));
|
|||
|
||||
### Locators
|
||||
|
||||
[Locators](./locators.md) are the central piece of Playwright's auto-waiting and retry-ability. Locators represent a way to find element(s) on the page at any moment and are used to perform actions on elements such as .click .fill etc. Custom locators can be created with the [`method: Page.locator`] method.
|
||||
[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 `.ClickAsync` `.FillAsync` etc. Custom locators can be created with the [`method: Page.locator`] method.
|
||||
|
||||
```csharp
|
||||
var getStarted = Page.Locator("text=Get Started");
|
||||
|
|
|
|||
|
|
@ -3,7 +3,7 @@ id: writing-tests
|
|||
title: "Writing Tests"
|
||||
---
|
||||
|
||||
Playwright assertions are created specifically for the dynamic web. Checks are automatically retried until the necessary conditions are met. Playwright comes with auto-wait built in meaning it waits for elements to be actionable prior to performing actions. Playwright provides a [test](./api/class-test.md) function to declare tests and the [expect](https://jestjs.io/docs/expect) function to write assertions.
|
||||
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 a [test](./api/class-test.md) function to declare tests and the [expect](https://jestjs.io/docs/expect) function to write assertions.
|
||||
|
||||
Take a look at the example test included when installing Playwright to see how to write a test using web first assertions, locators and selectors.
|
||||
|
||||
|
|
@ -69,7 +69,7 @@ await expect(page).toHaveTitle(/Playwright/);
|
|||
|
||||
### Locators
|
||||
|
||||
[Locators](./locators.md) are the central piece of Playwright's auto-waiting and retry-ability. Locators represent a way to find element(s) on the page at any moment and are used to perform actions on elements such as .click .fill etc. Custom locators can be created with the [`method: Page.locator`] method.
|
||||
[Locators](./locators.md) are the central piece of Playwright's auto-waiting and retry-ability. Locators represent a way to find element(s) on the page at any moment and are used to perform actions on elements such as `.click` `.fill` etc. Custom locators can be created with the [`method: Page.locator`] method.
|
||||
|
||||
```js
|
||||
const getStarted = page.locator('text=Get Started');
|
||||
|
|
|
|||
109
docs/src/writing-tests-python.md
Normal file
109
docs/src/writing-tests-python.md
Normal file
|
|
@ -0,0 +1,109 @@
|
|||
---
|
||||
id: writing-tests
|
||||
title: "Writing Tests"
|
||||
---
|
||||
|
||||
Playwright assertions are created specifically for the dynamic web. Checks are automatically retried until the necessary conditions are met. Playwright comes with [auto-wait](./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.
|
||||
|
||||
Take a look at the example test below to see how to write a test using web first assertions, locators and selectors.
|
||||
|
||||
```python
|
||||
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, foo
|
||||
):
|
||||
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.locator("text=Get Started")
|
||||
|
||||
# Expect an attribute "to be strictly equal" to the value.
|
||||
expect(get_started).to_have_attribute("href", "/docs/intro")
|
||||
|
||||
# Click the get started link.
|
||||
get_started.click()
|
||||
|
||||
# Expects the URL to contain intro.
|
||||
expect(page).to_have_url(re.compile(".*intro"))
|
||||
```
|
||||
|
||||
|
||||
### Assertions
|
||||
|
||||
Playwright provides the [`expect`](./test-assertions.md) function which will wait until the expected condition is met.
|
||||
|
||||
```python
|
||||
import re
|
||||
from playwright.sync_api import expect
|
||||
|
||||
expect(page).to_have_title(re.compile("Playwright"))
|
||||
```
|
||||
|
||||
|
||||
### Locators
|
||||
|
||||
[Locators](./locators.md) are the central piece of Playwright's auto-waiting and retry-ability. Locators represent a way to find element(s) on the page at any moment and are used to perform actions on elements such as `.click` `.fill` etc. Custom locators can be created with the [`method: Page.locator`] method.
|
||||
|
||||
```python
|
||||
from playwright.sync_api import expect
|
||||
|
||||
get_started = page.locator("text=Get Started")
|
||||
|
||||
expect(get_started).to_have_attribute("href", "/docs/installation")
|
||||
get_started.click()
|
||||
```
|
||||
|
||||
[Selectors](./selectors.md) are strings that are used to create Locators. Playwright supports many different selectors like [Text](./selectors.md#text-selector), [CSS](./selectors.md#css-selector), [XPath](./selectors.md#xpath-selectors) and many more.
|
||||
|
||||
```python
|
||||
from playwright.sync_api import expect
|
||||
|
||||
expect(page.locator("text=Installation")).to_be_visible()
|
||||
```
|
||||
|
||||
|
||||
### 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.
|
||||
|
||||
```python
|
||||
from playwright.sync_api import Page
|
||||
|
||||
def test_basic_test(page: Page):
|
||||
# ...
|
||||
```
|
||||
|
||||
### 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
|
||||
import pytest
|
||||
from playwright.sync_api import Page
|
||||
|
||||
|
||||
@pytest.fixture(scope="function", autouse=True)
|
||||
def before_each_after_each(page: Page):
|
||||
print("beforeEach")
|
||||
# Go to the starting url before each test.
|
||||
page.goto("https://playwright.dev/")
|
||||
yield
|
||||
print("afterEach")
|
||||
|
||||
def test_main_navigation(page: Page):
|
||||
# Assertions use the expect API.
|
||||
expect(page).to_have_url("https://playwright.dev/")
|
||||
```
|
||||
|
||||
## What's Next
|
||||
|
||||
- [Run single tests, multiple tests, headed mode](./running-tests.md)
|
||||
- [Debug tests with the Playwright Debugger](./debug.md)
|
||||
- [Generate tests with Codegen](./codegen.md)
|
||||
- [See a trace of your tests](./trace-viewer.md)
|
||||
Loading…
Reference in a new issue