跳到主要内容

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 参数仅适用于默认的 browsercontextpage fixtures。如果使用 API 调用(如 browser.new_context())创建浏览器、上下文或页面,则不应用 CLI 参数。

  • --headed: 在有头模式下运行测试(默认:无头)。
  • --browser: 在不同的浏览器 chromiumfirefoxwebkit 中运行测试。可以多次指定(默认:chromium)。
  • --browser-channel 使用的浏览器通道
  • --slowmo 将 Playwright 操作减慢指定的毫秒数。这很有用,以便你可以看到正在发生什么(默认:0)。
  • --device 要模拟的设备
  • --output 测试生成的工件目录(默认:test-results)。
  • --tracing 是否为每个测试记录跟踪onoffretain-on-failure(默认:off)。
  • --video 是否为每个测试记录视频。onoffretain-on-failure(默认:off)。
  • --screenshot 是否在每个测试后自动捕获截图。onoffonly-on-failure(默认:off)。
  • --full-page-screenshot 失败时是否截取全页截图。默认情况下,只截取视口。需要启用 --screenshot(默认:off)。

Fixtures

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

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

函数作用域:这些 fixtures 在测试函数中被请求时创建,并在测试结束时销毁。

会话作用域:这些 fixtures 在测试函数中被请求时创建,并在所有测试结束时销毁。

  • playwrightPlaywright 实例。
  • browser_type:当前浏览器的 BrowserType 实例。
  • browser:Playwright 启动的 Browser 实例。
  • browser_name:浏览器名称字符串。
  • browser_channel:浏览器通道字符串。
  • is_chromiumis_webkitis_firefox:对应浏览器类型的布尔值。

自定义 fixture 选项:对于 browsercontext fixtures,使用以下 fixtures 定义自定义启动选项。

也可以使用 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")
# ...

如果您正在使用带有 Pylance 的 VSCode,可以通过启用 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")

配置 base-url

使用 base-url 参数启动 Pytest。这使用了 pytest-base-url 插件,该插件允许从配置、CLI 参数或作为 fixture 设置 base url。

pytest --base-url http://localhost:8080
test_my_application.py
def test_visit_example(page):
page.goto("/admin")
# -> Will result in http://localhost: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"

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 提供商指南,将您的测试部署到 CI/CD。

异步 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")
# ...