Pytest 插件参考
介绍
🌐 Introduction
Playwright 提供了一个 Pytest 插件，用于编写端到端测试。要开始使用它，请参考 入门指南。
🌐 Playwright provides a Pytest plugin to write end-to-end tests. To get started with it, refer to the getting started guide.
用法
🌐 Usage
要运行你的测试，请使用 Pytest 命令行工具。
🌐 To run your tests, use Pytest CLI.
pytest --browser webkit --headed
如果你想自动添加 CLI 参数而无需手动指定，可以使用 pytest.ini 文件：
🌐 If you want to add the CLI arguments automatically without specifying them, you can use the pytest.ini file:
# content of pytest.ini
[pytest]
# Run firefox with UI
addopts = --headed --browser firefox
CLI 参数
🌐 CLI arguments
请注意，CLI 参数仅适用于默认的 browser、context 和 page 夹具。如果你通过像 browser.new_context() 这样的 API 调用创建浏览器、上下文或页面，CLI 参数将不会被应用。
🌐 Note that CLI arguments are only applied to the default browser, context and page fixtures. If you create a browser, a context or a page with the API call like browser.new_context(), the CLI arguments are not applied.
--headed：以有头模式运行测试（默认值：无头模式）。--browser：在不同的浏览器chromium、firefox或webkit中运行测试。可以多次指定（默认：chromium）。--browser-channelBrowser channel to be used.--slowmo会将 Playwright 操作减慢指定的毫秒数。这样做很有用，可以让你看到发生了什么（默认值：0）。--deviceDevice to be emulated.--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 夹具。要使用这些夹具，请在测试函数中将夹具名称作为参数使用。
🌐 This plugin configures Playwright-specific fixtures for pytest. To use these fixtures, use the fixture name as an argument to the test function.
def test_my_app_is_working(fixture_name):
pass
# Test using fixture_name
# ...
函数作用域：这些测试夹具在测试函数中被请求时创建，并在测试结束时销毁。
context：用于测试的新浏览器上下文。page：用于测试的新浏览器页面。new_context：允许为测试创建不同的 浏览器上下文。适用于多用户场景。参数与 browser.new_context() 相同。
会话范围：这些测试夹具在测试函数中被请求时创建，并在所有测试结束时销毁。
playwright：Playwright 实例。browser_type：BrowserType 当前浏览器的实例。browser：由 Playwright 启动的 浏览器 实例。browser_name：浏览器名称为字符串。browser_channel：浏览器通道为字符串。is_chromium、is_webkit、is_firefox：分别对应浏览器类型的布尔值。
自定义夹具选项：对于 browser 和 context 夹具，使用以下夹具来定义自定义启动选项。
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())：
🌐 Its also possible to override the context options (browser.new_context()) for a single test by using the browser_context_args marker:
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"]
并行处理：同时运行多个测试
🌐 Parallelism: Running Multiple Tests at Once
如果你的测试在一台拥有大量CPU的机器上运行，你可以使用 pytest-xdist 同时运行多个测试，从而加快整个测试套件的执行时间：
🌐 If your tests are running on a machine with a lot of CPUs, you can speed up the overall execution time of your test suite by using pytest-xdist to run multiple tests at once:
# install dependency
pip install pytest-xdist
# use the --numprocesses flag
pytest --numprocesses auto
根据硬件和测试的性质，你可以将 numprocesses 设置在 2 到机器 CPU 数量之间的任何值。如果设置过高，可能会出现意想不到的行为。
🌐 Depending on the hardware and nature of your tests, you can set numprocesses to be anywhere from 2 to the number of CPUs on the machine. If set too high, you may notice unexpected behavior.
有关 pytest 选项的一般信息，请参见 运行测试。
🌐 See Running Tests for general information on pytest options.
示例
🌐 Examples
配置自动补齐的类型
🌐 Configure typings for auto-completion
from playwright.sync_api import Page
def test_visit_admin_dashboard(page: Page):
page.goto("/admin")
# ...
如果你在使用带有 Pylance 的 VSCode，可以通过启用 python.testing.pytestEnabled 设置来推断这些类型，这样就不需要类型注解了。
🌐 If you're using VSCode with Pylance, these types can be inferred by enabling the python.testing.pytestEnabled setting so you don't need the type annotation.
使用多个上下文
🌐 Using multiple contexts
为了模拟多个用户，你可以创建多个 BrowserContext 实例。
🌐 In order to simulate multiple users, you can create multiple BrowserContext instances.
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
按浏览器跳过测试
🌐 Skip test by browser
import pytest
@pytest.mark.skip_browser("firefox")
def test_visit_example(page):
page.goto("https://example.com")
# ...
在特定浏览器上运行
🌐 Run on a specific browser
import pytest
@pytest.mark.only_browser("chromium")
def test_visit_example(page):
page.goto("https://example.com")
# ...
使用自定义浏览器通道（例如 Google Chrome 或 Microsoft Edge）运行
🌐 Run with a custom browser channel like Google Chrome or Microsoft Edge
pytest --browser-channel chrome
def test_example(page):
page.goto("https://example.com")
配置 base-url
🌐 Configure base-url
从 base-url 参数开始Pytest。用 ['pytest-base-url']（https://github.com/pytest-dev/pytest-base-url） 插件来设置配置文件、CLI ARG 或作为 fixture 的基础 URL。
🌐 Start Pytest with the base-url argument. The pytest-base-url plugin is used for that which allows you to set the base url from the config, CLI arg or as a fixture.
pytest --base-url http://localhost:8080
def test_visit_example(page):
page.goto("/admin")
# -> Will result in http://localhost:8080/admin
忽略 HTTPS 错误
🌐 Ignore HTTPS errors
import pytest
@pytest.fixture(scope="session")
def browser_context_args(browser_context_args):
return {
**browser_context_args,
"ignore_https_errors": True
}
使用自定义视口大小
🌐 Use custom viewport size
import pytest
@pytest.fixture(scope="session")
def browser_context_args(browser_context_args):
return {
**browser_context_args,
"viewport": {
"width": 1920,
"height": 1080,
}
}
设备模拟 / BrowserContext 选项覆盖
🌐 Device emulation / BrowserContext option overrides
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"
🌐 Or via the CLI --device="iPhone 11 Pro"
连接到远程浏览器
🌐 Connect to remote browsers
import pytest
@pytest.fixture(scope="session")
def connect_options():
return {
"wsEndpoint": "ws://localhost:8080/ws"
}
与 unittest.TestCase 一起使用
🌐 Using with unittest.TestCase
请参阅以下使用 unittest.TestCase 的示例。这有一个限制，只能指定一个浏览器，并且当指定多个浏览器时不会生成多个浏览器的矩阵。
🌐 See the following example for using it with unittest.TestCase. This has a limitation, that only a single browser can be specified and no matrix of multiple browsers gets generated when specifying multiple.
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
调试
🌐 Debugging
与 pdb 一起使用
🌐 Use with pdb
在你的测试代码中使用 breakpoint() 语句来暂停执行并获取一个 pdb REPL。
🌐 Use the breakpoint() statement in your test code to pause execution and get a pdb REPL.
def test_bing_is_working(page):
page.goto("https://bing.com")
breakpoint()
# ...
部署到 CI
🌐 Deploy to CI
查看 CI 提供商指南 将你的测试部署到 CI/CD。
🌐 See the guides for CI providers to deploy your tests to CI/CD.
异步 Fixtures
🌐 Async Fixtures
要使用异步夹具，请安装 pytest-playwright-asyncio。
🌐 To use async fixtures, install pytest-playwright-asyncio.
确保你正在使用 pytest-asyncio>=0.26.0 并在你的配置 (pytest.ini/pyproject.toml/setup.cfg) 中设置 asyncio_default_test_loop_scope = session。
🌐 Ensure you are using pytest-asyncio>=0.26.0 and set asyncio_default_test_loop_scope = session in your configuration (pytest.ini/pyproject.toml/setup.cfg).
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")
# ...