Playwright Python 测试入门

本文依据官方文档整理，未执行运行验证或性能基准。代码片段展示局部用法，业务函数、数据和环境需按项目补齐；版本与配置以所引文档为准。

直接回答：Playwright 提供一等公民的 Python 绑定，配合 pytest 插件即可获得核心浏览器自动化能力（测试运行器及插件选项并非与JS版完全相同）——自动等待、多内核、网络拦截一应俱全，Python 团队无需切换语言就能搭建现代 E2E 测试体系。

什么是 Playwright

Playwright 是微软开源的浏览器自动化框架，支持 Chromium、Firefox、WebKit。Python 版通过 playwright 包提供同步与异步两套 API，并有官方 pytest-playwright 插件把浏览器上下文管理成 pytest fixture。

环境搭建

pip install pytest-playwright
playwright install

第二条命令下载浏览器二进制。建议 Python 3.10+。

第一个测试

test_homepage.py：

from playwright.sync_api import Page, expect

def test_homepage_has_title(page: Page):
    page.goto("https://example.com")
    expect(page).to_have_title("Example Domain")

pytest 直接运行——page fixture 由插件提供，每条用例自动获得干净的浏览器上下文。

核心概念

定位器（Locator）：描述"如何找到元素"的惰性对象，操作时才解析，配合自动等待减少部分时序抖动：

page.get_by_role("button", name="提交").click()
page.get_by_label("邮箱").fill("demo@example.com")
page.get_by_test_id("submit-btn").click()

自动等待：动作执行前检查对应条件：click检查可见、稳定、可接收事件及enabled；fill另要求editable，不执行完全同一组检查；expect 断言内置轮询直到超时：

expect(page.get_by_text("提交成功")).to_be_visible()

上下文隔离：browser.new_context() 等价于全新无痕窗口，用例间互不污染；context 级还能设置视口、语言、地理位置、权限。

真实用户场景

import re

def test_login_flow(page: Page):
    page.goto("https://app.example.com/login")
    page.get_by_label("邮箱").fill("demo@example.com")
    page.get_by_label("密码").fill("secret123")
    page.get_by_role("button", name="登录").click()

    expect(page).to_have_url(re.compile(r"/dashboard(?:[?#].*)?$"))
    expect(page.get_by_text("欢迎回来")).to_be_visible()

第三方依赖可以拦截 Mock：

page.route("**/api/payment", lambda route: route.fulfill(json={"status": "ok"}))

进阶功能

• 多浏览器：pytest --browser chromium --browser webkit；
• 移动端模拟：device 描述符一键模拟 iPhone/Pixel；
• 截图与视频：需显式配置 pytest 插件选项，如 --screenshot only-on-failure、--video retain-on-failure、--tracing retain-on-failure；
• 并行：pytest-xdist 多进程并行加速套件。

调试

PWDEBUG=1 pytest -k test_login   # Inspector 模式
pytest --tracing on              # 收集 trace
playwright show-trace trace.zip  # 回放失败现场

page.pause() 在脚本中插断点，配合 Inspector 交互式探索页面。

常见问题（FAQ）

Q：同步 API 还是异步 API？
A：测试场景用同步 API（配 pytest）最省心；高并发爬虫类场景用 async_playwright。两者能力一致。

Q：和 Selenium 比优势在哪？
A：自动等待消灭手写 sleep；locator及上下文隔离帮助降低部分不确定性；原生支持多上下文、网络拦截、移动端模拟。新项目建议直接上 Playwright。

Q：CI 上怎么跑？
A：官方 Docker 镜像含浏览器及系统依赖，但项目的 Python 包仍需安装并匹配镜像版本；GitHub Actions 里 playwright install --with-deps 即可。记得开启 trace/video 收集，失败时便于回放定位。

官方参考

• 官方文档 1
• 官方文档 2
• 官方文档 3

资料核对日期：2026-09-29。

延伸阅读

• Playwright 测试核心概念入门
• 用 Playwright 端到端测试注册与登录流程