Pytest 插件参考

简介

Playwright 提供了一个 Pytest 插件来编写端到端测试。要开始使用它，请参阅入门指南。

用法

要运行您的测试，请使用 Pytest CLI。

pytest --browser webkit --headed

如果您想自动添加 CLI 参数而不指定它们，可以使用 pytest.ini 文件

# content of pytest.ini
[pytest]
# Run firefox with UI
addopts = --headed --browser firefox

CLI 参数

请注意，CLI 参数仅应用于默认的 browser、context 和 page fixture。如果您使用像 browser.new_context() 这样的 API 调用创建浏览器、上下文或页面，则 CLI 参数不适用。

--headed：在有界面的模式下运行测试（默认：无界面）。
--browser：在不同的浏览器 chromium、firefox 或 webkit 中运行测试。可以指定多次（默认：chromium）。
--browser-channel 浏览器通道。
--slowmo 以指定的毫秒数减慢 Playwright 操作的速度。这有助于您看到正在发生的事情（默认：0）。
--device 设备进行模拟。
--output 测试生成的工件目录（默认：test-results）。
--tracing 是否为每个测试记录一个跟踪。on、off 或 retain-on-failure（默认：off）。
--video 是否为每个测试录制视频。on、off 或 retain-on-failure（默认：off）。
--screenshot 是否在每个测试后自动捕获屏幕截图。on、off 或 only-on-failure（默认：off）。
--full-page-screenshot 是否在失败时截取全页截图。默认情况下，仅捕获视口。需要启用 --screenshot（默认：off）。

Fixtures

此插件配置了 Playwright 特有的 pytest fixture。要使用这些 fixture，请将 fixture 名称用作测试函数的参数。

def test_my_app_is_working(fixture_name):
    pass
    # Test using fixture_name
    # ...

函数作用域：这些 fixture 在测试函数中请求时创建，并在测试结束时销毁。

context：测试的新浏览器上下文。
page：测试的新浏览器页面。
new_context：允许为测试创建不同的浏览器上下文。适用于多用户场景。接受与 browser.new_context() 相同的参数。

会话作用域：这些 fixture 在测试函数中请求时创建，并在所有测试结束时销毁。

playwright：Playwright 实例。
browser_type：当前浏览器的 BrowserType 实例。
browser：由 Playwright 启动的 Browser 实例。
browser_name：浏览器名称（字符串）。
browser_channel：浏览器通道（字符串）。
is_chromium、is_webkit、is_firefox：分别为相应浏览器类型的布尔值。

自定义 fixture 选项：对于 browser 和 context fixture，使用以下 fixture 定义自定义启动选项。

browser_type_launch_args：覆盖 browser_type.launch() 的启动参数。应返回一个字典。
browser_context_args：覆盖 browser.new_context() 的选项。应返回一个字典。
connect_options：通过 WebSocket 端点连接到现有浏览器。应返回一个包含 browser_type.connect() 选项的字典。

还可以通过 browser_context_args 标记为单个测试覆盖上下文选项（browser.new_context()）。

import pytest

@pytest.mark.browser_context_args(timezone_id="Europe/Berlin", locale="en-GB")
def test_browser_context_args(page):
    assert page.evaluate("window.navigator.userAgent") == "Europe/Berlin"
    assert page.evaluate("window.navigator.languages") == ["de-DE"]

并行性：同时运行多个测试

如果您的测试运行在具有大量 CPU 的机器上，您可以使用 pytest-xdist 同时运行多个测试，从而加快您的测试套件的整体执行时间。

# install dependency
pip install pytest-xdist
# use the --numprocesses flag
pytest --numprocesses auto

根据硬件和测试性质，您可以将 numprocesses 设置为从 2 到机器 CPU 数量之间的任意值。如果设置过高，您可能会遇到意外行为。

有关 pytest 选项的一般信息，请参阅运行测试。

示例

为自动补全配置类型提示

test_my_application.py
from playwright.sync_api import Page

def test_visit_admin_dashboard(page: Page):
    page.goto("/admin")
    # ...

如果您正在使用 VSCode 和 Pylance，可以通过启用 python.testing.pytestEnabled 设置来推断这些类型，这样您就不需要类型注解。

使用多个上下文

为了模拟多个用户，您可以创建多个 BrowserContext 实例。

test_my_application.py
from playwright.sync_api import Page, BrowserContext
from pytest_playwright.pytest_playwright import CreateContextCallback

def test_foo(page: Page, new_context: CreateContextCallback) -> None:
    page.goto("https://example.com")
    context = new_context()
    page2 = context.new_page()
    # page and page2 are in different contexts

按浏览器跳过测试

test_my_application.py
import pytest

@pytest.mark.skip_browser("firefox")
def test_visit_example(page):
    page.goto("https://example.com")
    # ...

在特定浏览器上运行

conftest.py
import pytest

@pytest.mark.only_browser("chromium")
def test_visit_example(page):
    page.goto("https://example.com")
    # ...

使用自定义浏览器通道（如 Google Chrome 或 Microsoft Edge）运行

pytest --browser-channel chrome

test_my_application.py
def test_example(page):
    page.goto("https://example.com")

配置基础 URL

使用 base-url 参数启动 Pytest。为此使用了 pytest-base-url 插件，该插件允许您从配置、CLI 参数或 fixture 设置基础 URL。

pytest --base-url https://:8080

test_my_application.py
def test_visit_example(page):
    page.goto("/admin")
    # -> Will result in https://:8080/admin

忽略 HTTPS 错误

conftest.py
import pytest

@pytest.fixture(scope="session")
def browser_context_args(browser_context_args):
    return {
        **browser_context_args,
        "ignore_https_errors": True
    }

使用自定义视口大小

conftest.py
import pytest

@pytest.fixture(scope="session")
def browser_context_args(browser_context_args):
    return {
        **browser_context_args,
        "viewport": {
            "width": 1920,
            "height": 1080,
        }
    }

设备模拟 / BrowserContext 选项覆盖

conftest.py
import pytest

@pytest.fixture(scope="session")
def browser_context_args(browser_context_args, playwright):
    iphone_11 = playwright.devices['iPhone 11 Pro']
    return {
        **browser_context_args,
        **iphone_11,
    }

或通过 CLI --device="iPhone 11 Pro"

连接到远程浏览器

conftest.py
import pytest

@pytest.fixture(scope="session")
def connect_options():
    return {
        "wsEndpoint": "ws://:8080/ws"
    }

与 `unittest.TestCase` 一起使用

请参阅以下示例，了解如何将其与 unittest.TestCase 一起使用。这有一个限制，即只能指定一个浏览器，并且在指定多个时不会生成多个浏览器的矩阵。

import pytest
import unittest

from playwright.sync_api import Page


class MyTest(unittest.TestCase):
    @pytest.fixture(autouse=True)
    def setup(self, page: Page):
        self.page = page

    def test_foobar(self):
        self.page.goto("https://microsoft.com")
        self.page.locator("#foobar").click()
        assert self.page.evaluate("1 + 1") == 2

调试

与 pdb 一起使用

在测试代码中使用 breakpoint() 语句来暂停执行并获得一个 pdb REPL。

def test_bing_is_working(page):
    page.goto("https://bing.com")
    breakpoint()
    # ...

部署到 CI

有关将您的测试部署到 CI/CD，请参阅 CI 提供商指南。

异步 Fixtures

要使用异步 Fixtures，请安装 pytest-playwright-asyncio。

请确保您正在使用 pytest-asyncio>=0.26.0 并在您的配置（pytest.ini/pyproject.toml/setup.cfg）中设置 asyncio_default_test_loop_scope = session。

import pytest
from playwright.async_api import Page

@pytest.mark.asyncio(loop_scope="session")
async def test_foo(page: Page):
    await page.goto("https://github.com")
    # ...

简介​

用法​

CLI 参数​

Fixtures​

并行性：同时运行多个测试​

示例​

为自动补全配置类型提示​

使用多个上下文​

按浏览器跳过测试​

在特定浏览器上运行​

使用自定义浏览器通道（如 Google Chrome 或 Microsoft Edge）运行​

配置基础 URL​

忽略 HTTPS 错误​

使用自定义视口大小​

设备模拟 / BrowserContext 选项覆盖​

连接到远程浏览器​

与 unittest.TestCase 一起使用​

调试​

与 pdb 一起使用​

部署到 CI​

异步 Fixtures​

简介

用法