Playwright 入门教程

1. 环境说明

• 操作系统：macOS 11.7
• Python：3.10.6

2. 安装

2.1. 创建测试环境

mkdir playwright-demo
cd playwright-demo/
python3 -m venv venv
# 安装 Pytest 插件
venv/bin/pip3 install pytest-playwright
# 安装需要的浏览器
venv/bin/playwright install

2.2. 添加样例测试

在当前工作目录或子目录内部，创建 test_my_application.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):
    page.goto("Fast and reliable end-to-end testing for modern web apps | Playwright")

    # 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"))

2.3. 运行样例测试

默认情况下，测试运行在 chromium 上，可通过 CLI 选项进行配置，测试以 Headless 模式运行。测试结果和测试日志被展示在终端中。

venv/bin/pytest

3. 编写测试

Playwright 断言（assertion）是专门为动态网页创建的。检查会自动重试，直到满足必要的条件。Playwright 自带 auto-wait，这意味着它在执行操作之前等待元素变为可操作的（actionable）。Playwright 提供 expect 函数来写断言。

下面的样例测试展示了如何写使用断言、定位器（locator）和选择器（selector）的测试。

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):
    page.goto("Fast and reliable end-to-end testing for modern web apps | Playwright")

    # 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"))

3.1. 断言

Playwright 提供 expect 函数，它会一直等待，直到满足预期条件。

import re
from playwright.sync_api import expect

expect(page).to_have_title(re.compile("Playwright"))

3.2. 定位器

定位器（Locators）是 Playwright 的自动等待和重试能力的核心部分。定位器表示一种随时在网页上查找元素的方法，用于在元素上执行诸如 .click、.fill 之类的操作。可以使用 page.locator(selector, **kwargs) 方法创建自定义的定位器。

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）是用于创建定位器的字符串。Playwright 支持许多不同的选择器，比如 Text、CSS、XPath 等。通过 in-depth guide 文档，了解更多关于可用的选择器以及如何进行选择的信息。

from playwright.sync_api import expect

expect(page.locator("text=Installation")).to_be_visible()

3.3. 测试隔离

Playwright Pytest 插件基于 test fixture（比如 built in page fixture）的概念，它会被传给你的测试。由于浏览器上下文，在测试之间，页面（page）彼此隔离，这相当于开启新的浏览器行为，每个测试获得新环境，即使在一个浏览器中运行多个测试时，也是如此。

from playwright.sync_api import Page

def test_basic_test(page: Page):
  # ...

3.4. 使用测试钩子

你可以使用各种各样的 fixtures 来在你的测试之前或之后执行代码，以及在它们之间共享对象。函数（function）作用域的 fixture 具有 beforeEach/afterEach 一样的自动使用行为。模块（module）作用域的 fixture 具有 beforeAll/afterAll 一样的自动使用行为，它会在所有测试之前和所有测试之后运行。

import pytest
from playwright.sync_api import Page, expect


@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("Fast and reliable end-to-end testing for modern web apps | Playwright")
    yield
    print("afterEach")

def test_main_navigation(page: Page):
    # Assertions use the expect API.
    expect(page).to_have_url("Fast and reliable end-to-end testing for modern web apps | Playwright")

4. 运行测试

你可以运行单个测试、一组测试或全部测试。测试可以运行在一种或多种浏览器上。默认情况下，测试以 headless 方式运行，这意味着在运行测试时，不会打开浏览器窗口，可以在终端中看到结果。通过使用 --headed 标记，可以以 headed 模式运行测试。

- 在 Chromium 上运行测试

pytest

- 运行单个测试文件

pytest test_login.py

- 运行一组测试文件

pytest tests/todo-page/ tests/landing-page/

- 使用函数名运行测试

pytest -k "test_add_a_todo_item"

- 以有头（headed）模式运行测试

pytest --headed test_login.py

- 在指定的浏览器上运行测试

pytest test_login.py --browser webkit

- 在多种浏览器上运行测试

pytest test_login.py --browser webkit --browser firefox

- 并行运行测试

pytest --numprocesses auto

（假定已安装 pytest-xdist，查看 here 获取更多信息。）

4.1. 运行测试

因为 Playwright 运行在 Python 中，所以可以使用 debugger 调试它。Playwright 自带 Playwright Inspector，它允许你逐步通过 Playwright API 调用，查看它们的调试日志，以及探索选择器（selectors）。

PWDEBUG=1 pytest -s

查看我们的调试指南（debugging guide）来了解关于 Playwright Inspector 以及使用浏览器开发者工具（Browser Developer tools）进行调试的更多信息。

5. 测试生成器

Playwright 具有开箱即用的生成测试的能力，这是快速开始测试的好方法。它会打开两个窗口，一个是浏览器窗口，通过它你可以与希望测试的网站进行交互，另一个是 Playwright Inspector 窗口，通过它你可以录制测试、拷贝测试、清除测试以及改变测试的语言。

你将学习：

- How to generate tests with Codegen

5.1. 运行代码生成器（Codegen）

playwright codegen Fast and reliable end-to-end testing for modern web apps | Playwright

运行 codegen，然后在浏览器中执行操作。Playwright 会为用户的交互生成代码。Codegen 会尝试生成弹性的基于文本的选择器。

当你完成与页面的交互时，按下 record 按钮停止录制，使用 copy 按钮把生成的代码拷贝到编辑器。

使用 clear 按钮清除代码，重新开始录制。完成时，关闭 Playwright Inspector 窗口，或停止终端命令。

要了解有关生成测试的更多信息，请查看 Codegen 的详细指南。

6. 追踪查看器（Trace Viewer）

Playwright 追踪查看器是一个 GUI 工具，它使你可以探查你的测试中记录的 Playwright 追踪，你可以在测试的每个操作中来回移动，可视化地查看每个操作期间正在发生什么。

你将学习：

- 如何记录追踪

- 如何打开 HTML 报告

- 如何打开追踪查看器

6.1. 记录追踪

像下面一样使用 browser_context.tracing API 记录追踪：

browser = chromium.launch()
context = browser.new_context()

# Start tracing before creating / navigating a page.
context.tracing.start(screenshots=True, snapshots=True, sources=True)

page.goto("Fast and reliable end-to-end testing for modern web apps | Playwright")

# Stop tracing and export it into a zip archive.
context.tracing.stop(path = "trace.zip")

这将记录追踪，并把它放到名称为 trace.zip 的文件中。

6.2. 打开追踪

你可以使用 Playwright CLI 打开保存的追踪。

playwright show-trace trace.zip

6.3. 查看追踪

通过单击每个操作或使用时间轴悬停来查看测试的追踪，以及查看操作前后的页面状态。在测试的每个步骤期间查看日志、源和网络。追踪查看器创建 DOM 快照，因此你可以与它进行交互，打开开发者工具（devtools）等。

要了解更多信息，请查看 Trace Viewer 的详细指南。

7. Pytest 插件参考

Playwright 提供 Pytest 插件来编写端到端的测试。如果想要使用它，请参考 getting started guide。

7.1. 用法

使用 Pytest CLI 运行测试：

pytest --browser webkit --headed

如果你想自动地添加 CLI 参数，请使用 pytest.ini 文件。

7.2. CLI 参数

• - --headed：以有头模式运行测试（默认：无头）
• - --browser：用不同的浏览器 chromium、firefox、webkit 运行测试。可以指定多次（默认：所有浏览器）
• - --browser-channel：使用的 Browser channel
• - --slow-mo：使用慢动作运行测试
• - --device：模拟的设备（Device）
• - --output：用于测试生成的制品（aritifact）的目录（默认：test-results）
• - --tracing：是否为每次测试记录追踪（trace）。on、off 或 retain-on-failure（默认：off）
• - --video：是否为每次测试录制视频。on、off 或 retain-on-failure（默认：off）
• - --screenshot：是否在每次测试后，自动地捕获截屏。on, off, or only-on-failure （默认：off)

7.3. Fixture

该插件给 pytest 配置 Playwright 特定的 fixture（fixtures for pytest）。为使用这些 fixture，使用 fixture 名称作为测试函数的参数。

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

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

• - context：用于测试的新浏览器上下文（browser context）
• - page：用于测试的新浏览器页面（browser page）

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

• - playwright：Playwright 实例
• - browser_type：当前浏览器的 BrowserType 实例
• - browser：Playwright 启动的 Browser 实例
• - browser_name：浏览器名称
• - browser_channel：浏览器通道（channel）
• - is_chromium、is_webkit、is_firefox：各自浏览器类型的布尔值

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

• - browser_type_launch_args：重写用于 browser_type.launch(**kwargs) 的启动参数。它应该返回字典
• - browser_context_args：重写用于 browser.new_context(**kwargs) 的选项。它应该返回字典

7.4. 并行：同时运行多个测试

如果测试运行在有许多 CPU 的机器上，可以通过使用 pytest-xdist 同时运行多个测试，加快测试套件的整体执行时间。

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

根据硬件和测试的特性，可以将 numprocesses 设置为 2 到机器上 CPU 数量之间的任意值。如果设置得过高，可能产生非预期行为。

有关 pytest 选项的常用信息，请参考 Running Tests。

7.5. 示例

配置 Mypy 类型以自动补全

# test_my_application.py
from playwright.sync_api import Page

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

配置慢动作

使用 --slowmo 参数以慢动作运行测试。

pytest --slowmo 100

通过浏览器跳过测试

# test_my_application.py
import pytest

@pytest.mark.skip_browser("firefox")
def test_visit_example(page):
    page.goto("Example Domain")
    # ...

在特定的浏览器上运行测试

# conftest.py
import pytest

@pytest.mark.only_browser("chromium")
def test_visit_example(page):
    page.goto("Example Domain")
    # ...

使用自定义的浏览器通道运行

pytest --browser-channel chrome
# test_my_application.py
def test_example(page):
    page.goto("Example Domain")

配置 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,
        }
    }

设备仿真

# 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,
    }

或通过命令行

--device="iPhone 11 Pro"。

持久化上下文

# conftest.py
import pytest
from playwright.sync_api import BrowserType
from typing import Dict

@pytest.fixture(scope="session")
def context(
    browser_type: BrowserType,
    browser_type_launch_args: Dict,
    browser_context_args: Dict
):
    context = browser_type.launch_persistent_context("./foobar", **{
        **browser_type_launch_args,
        **browser_context_args,
        "locale": "de-DE",
    })
    yield context
    context.close()

从持久化上下文创建测试内部的所有页面。

与 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

7.6. 调试

在代码中使用 breakpoint() 语句停止执行，获取 pdb REPL。
def test_bing_is_working(page):
    page.goto("https://bing.com")
    breakpoint()
    # ...

7.7. 部署到 CI

请查看 guides for CI providers 获取关于将测试部署到 CI/CD 的信息。

8. 认证

Playwright 可用于需要认证的自动化场景。

用 Playwright 编写的测试在被称为浏览器上下文（browser contexts）的独立的干净的环境中执行。这种隔离模型可以提升复现性，防止级联测试失败。新浏览器上下文可以加载现有的认证状态。这可以消除在每个上下文中登录的需求，加快测试执行的速度。

注意：本指南覆盖 cookie/token-based 认证（通过 app UI 登陆）。对于 HTTP 认证（HTTP authentication），请使用 browser.new_context(**kwargs)。

8.1. 自动化登录

Playwright API 可以与登陆表单自动化交互（automate interaction）。

下面的例子自动化登陆到 Github。执行这些步骤之后，浏览器上下文将被认证。

page = context.new_page()
page.goto('https://github.com/login')

# Interact with login form
page.get_by_text("Login").click()
page.get_by_label("User Name").fill(USERNAME)
page.get_by_label("Password").fill(PASSWORD)
page.get_by_text('Submit').click()
# Continue with the test

为每次测试重做登录会减慢测试的执行速度。为缓解这种情况，应该重用现有的认证状态。

8.2. 重用签入状态

Playwright 提供在测试中重用签入（signed-in）状态的方式。通过该方式，可以只登陆一次，然后跳过所有测试的登陆步骤。

Web 应用使用基于 Cookie 或基于 Token 的认证，认证状态被当作 cookies 存储，或存储在 local storage 中。Playwright 提供 browserContext.storageState(options) 方法，可使用它从已认证上下文中获取存储状态，然后使用预填充状态创建新上下文。

Cookie 和 Local Storage 状态可以跨不同的浏览器使用。它们依赖应用程序的认证模型：有些应用程序可能同时需要 Cookie 和 Local Storage。

下面的代码片段从已认证上下文中获取状态，然后使用该状态创建新上下文。

# Save storage state into the file.
storage = context.storage_state(path="state.json")

# Create a new context with the saved storage state.
context = browser.new_context(storage_state="state.json")

8.3. Session Storage

session storage 很少用于存储与登陆状态相关的信息。Session Storage 特定于特定的域，页面加载时它不会持久化。Playwright 没提供用于持久化 Session Storage 的 API，但下面的片段可用于保存/加载 Session Storage。

import os
# Get session storage and store as env variable
session_storage = page.evaluate("() => JSON.stringify(sessionStorage)")
os.environ["SESSION_STORAGE"] = session_storage

# Set session storage in a new context
session_storage = os.environ["SESSION_STORAGE"]
context.add_init_script("""(storage => {
  if (window.location.hostname === 'Example Domain') {
    const entries = JSON.parse(storage)
    for (const [key, value] of Object.entries(entries)) {
      window.sessionStorage.setItem(key, key)
    }
  }
})('""" + session_storage + "')")

8.4. 多因子认证

使用多因子认证（MFA）的账户无法完全自动化，需要人工干预。持久化认证可用于部分自动化 MFA 场景。

8.4.1 持久化认证

注意持久化认证不适用于 CI 环境，因为它依赖磁盘位置。用户数据目录特定于浏览器类型，不能跨浏览器类型共享。

用户数据目录可以与 browser_type.launch_persistent_context(user_data_dir, **kwargs) API 一起使用。

from playwright.sync_api import sync_playwright

with sync_playwright() as p:
    user_data_dir = '/path/to/directory'
    browser = p.chromium.launch_persistent_context(user_data_dir, headless=False)
    # Execute login steps manually in the browser window

生命周期

1. 在磁盘上创建用户数据目录

2. 使用用户数据目录启动持久化上下文，然后登陆 MFA 账户

3. 重用用户数据目录来运行自动化场景

9. 事件

Playwright 允许监听发生在 Web 页面上的多种类型的事件，比如网络请求、子页面的创建、专用 Worker 等。可以通过多种方式订阅这些事件，比如等待事件或添加/移除事件监听者。

9.1. 等待事件

大多数时间，脚本需要等待特定的事件发生。下面是一些典型的事件等待模式。

使用 page.expect_request(url_or_predicate, **kwargs) 等待拥有指定 URL 的请求：

with page.expect_request("**/*logo*.png") as first:
  page.goto("https://wikipedia.org")
print(first.value.url)

等待弹出窗口：

with page.expect_popup() as popup:
  page.evaluate("window.open()")
popup.value.goto("https://wikipedia.org")

9.2. 添加/移除事件监听者

有时，事件发生在随机的事件，而不是等待它们，需要处理它们。Playwright 支持订阅/取消订阅事件的传统语言机制：

def print_request_sent(request):
  print("Request sent: " + request.url)

def print_request_finished(request):
  print("Request finished: " + request.url)

page.on("request", print_request_sent)
page.on("requestfinished", print_request_finished)
page.goto("https://wikipedia.org")

page.remove_listener("requestfinished", print_request_finished)
page.goto("https://www.openstreetmap.org/")

9.3. 添加一次性监听者

如果特定事件需要被处理一次，那么可以使用便捷的 API：

page.once("dialog", lambda dialog: dialog.accept("2021"))