写这篇东西的起因很简单我经常看到有人在测试群里问“pytest-playwright到底是干嘛的我用 pytest 也能自己写 launch、new_page、close为什么还要装这个插件”还有不少人以为它就是个“让 Playwright 能跑在 pytest 里的翻译器”。实际上pytest-playwright 干的事情远比表面看到的要多。它在你写def test_login(page)的那一刻起就把浏览器启停、上下文隔离、失败截图、视频、Trace、并发策略、命令行参数这些东西全部接管了。这篇文章我就以实际使用者的视角把插件默默帮你做的那些事拆开逐一过一遍顺便把藏在命令背后的原理和我在生产环境里踩过的坑一起说了。1. 没有 pytest-playwright 时我们是怎么被 Playwright 折磨的先说句实在话Playwright 本身的 API 设计是同类工具里数一数二舒服的但“API 舒服”和“写测试舒服”是两回事。你脱离 pytest-playwright直接用 pytest 裸写 Playwright 测试很快就会撞上三个让人烦躁的问题。1.1 资源管理全靠手工忘一句 close 就多一个僵尸进程如果不用插件最朴素的写法差不多是这样from playwright.sync_api import sync_playwright def test_login(): with sync_playwright() as p: browser p.chromium.launch(headlessFalse) context browser.new_context() page context.new_page() try: page.goto(https://example.com) # ... 测试逻辑 finally: context.close() browser.close()这段代码看起来没毛病但它把“测试逻辑”和“资源生命周期”死死地耦合在了一起。一旦中间某个断言抛了异常finally里的清理代码确实还会执行但你在每个测试函数里都要重复写这么一套十个人能写出十种不同的清理顺序。更隐蔽的问题是browser.close()之后Playwright 的浏览器子进程在某些操作系统上并不会立刻消失如果你再开了多个 context 没有关干净跑完一整个测试套件后进程列表里会挂着一堆 Chromium 残留。这个问题的解决思路其实应该由框架层统一处理而不是靠每个测试作者自觉。1.2 失败现场全靠自己抢救截图代码比测试代码还长等测试真的红了之后第二个痛点就来了你想留现场。要截图要录视频要抓 HAR要保存 DOM 快照Playwright 确实都支持但你在裸写 pytest 的情况下每个都需要自己手动在except里写对应代码。我见过最夸张的一个项目失败处理的辅助函数有三百多行维护成本比业务测试本身还高。1.3 配置散落各处换浏览器要靠改代码第三个痛点最伤团队协作浏览器类型、headless 模式、base_url、超时时间、跳过逻辑——这些东西如果没有统一的入口就会散落在各个 fixture、conftest.py、甚至 CI 脚本里。你想在本地用 headed 模式调试在 CI 用 headless不改代码基本做不到。想临时跑一遍 webkit得去改launch()的参数。这些正是 pytest-playwright 存在的理由它把“浏览器进程管理”“测试环境配置”“失败产物收集”这三件跟业务无关的事从你的测试代码里彻底剥离出去。所以看完这一章你应该意识到pytest-playwright 不是一个“翻译层”而是一个完整的测试执行基础设施。2. 插件塞给你的四个 fixture每一个背后都是一套设计决策pytest 的核心武器是 fixturepytest-playwright 的核心武器是内置的 fixture。很多初学者只知道无脑声明page其实插件一共给了你四个标准 fixtureplaywright、browser、browser_context、page。这四个东西作用域不同、生成逻辑不同、彼此之间的依赖关系也不同把它们搞清楚很多诡异问题就能迎刃而解。2.1 每个 fixture 的作用域为什么要这样设计我用一张表把这四个 fixture 的核心特性列出来这是我们项目组内部培训时必讲的一张表。Fixture作用域是否自动使用典型用途playwrightsession是提供 Playwright 入口对象负责全局启停browsersession是默认持久化浏览器实例可被 context 共用browser_contextfunction否每个测试独立上下文隔离登录态和 Cookiepagefunction否每个测试独立标签页绝大多数测试直接用这个playwright和browser是 session 级的这比较好理解启动浏览器是重操作每个测试都重新启动一次浏览器跑几百条用例时间直接爆炸。但browser_context和page却是 function 级的每个测试都新建、每个测试结束就销毁。这个设计的核心逻辑是隔离。浏览器进程可以共享但用户的登录态、localStorage、Cookie 绝对不能在测试之间串。你想想看你测试 A 往购物车里加了一件商品测试 B 如果复用同一个 context就会继承这个脏状态测试 B 的隔离性就废了。pytest-playwright 让 context 和 page 都按测试粒度重建本质上是在“性能”和“隔离性”之间选了一个非常合理的折中。2.2 page fixture 背后发生了什么当你写def test_search(page):时插件实际的执行顺序是这样的先检查playwrightfixture启动 Playwright 内部驱动再拿browserfixture按你命令行里指定的浏览器类型和参数启动真实浏览器接着browser_context创建全新的上下文最后page在 context 上新建标签页。测试执行完毕后清理顺序正好反过来page 关闭、context 关闭、驱动收尾。这意味着你根本不需要写任何 try/finally异常抛出时清理流程也会照常走完。可能有人会疑惑既然playwright和browser是 session 级怎么保证每个测试拿到的 context 是新的答案是这两个 fixture 只负责“进程级”共享而 context 的创建动作绑定在 function 级 fixture 上所以同一浏览器进程里可以不断产出新的隔离环境这就是它们分层的意义。2.3 自定义 fixture 时的一个推荐姿势实际项目里你很少会只用一个裸的page一般都要在测试前做登录、切账号、注入某个 token。这时候正确姿势不是自己去 launch而是基于插件的 fixture 再做一层封装pytest.fixture def admin_page(page): page.goto(/login) page.get_by_label(用户名).fill(admin) page.get_by_label(密码).fill(pass) page.get_by_role(button, name登录).click() yield page注意这里page参数的注入完全由插件完成你只负责“登录”这个业务动作。这个封装的好处是底层浏览器是复用 session 级的而登录状态只存在于当前测试的 context 中不会污染其他测试。这是生产项目中最常见也最合理的 fixture 叠加方式。3. 命令行里那些参数每敲一个都在改变插件的运行行为pytest-playwright 最讨喜的一点是它把大量运行行为做成了命令行参数让“调试环境”和“CI 环境”的切换从改代码变成了改命令。3.1 控制浏览器行为的一组核心参数举几个我很常用的例子--browserchromium或--browserfirefox --browserwebkit指定浏览器可以传多次从而实现多浏览器矩阵。--headed默认是无头模式跑调试时加上这个参数你就看得见浏览器界面了。--browser-channelchrome用本机的 Chrome 而不是 Playwright 自带的 Chromium。--slow-mo500每一步操作之间加 500ms 延迟非常适合演示和调试定位器失效。--deviceiPhone 13模拟移动端设备。--base-urlhttps://staging.example.com给页面访问设置根路径配合page.goto(/path)使用。这些参数最终都会被读取然后注入到browserfixture 的 launch 逻辑和 context 的创建逻辑里。核心逻辑是插件通过pytest_addoption注册这些参数在创建 fixture 时读取配置值再决定启动什么样的浏览器、往 context 里塞什么设备模拟属性。3.2 失败产物的自动收集比你想的更周到这一块是 pytest-playwright 相对于手动方案最有感知度的价值之一。它支持三种产物截图、视频、Trace。命令行参数分别是--screenshot、--video、--tracing每种都有on、off、retain-on-failure三种级别。retain-on-failure的意思是测试通过了就把产物丢掉失败了才保留。这个设计非常聪明既不会让成功用例白白占用磁盘又能保证失败时一定有现场。我强烈建议所有项目默认都开--videoretain-on-failure --tracingretain-on-failure --screenshotonly-on-failure。Trace 文件尤其重要它在trace.zip里记录了页面完整的操作时间线、网络请求、控制台日志排一个偶发失败用例的时候Trace 基本能还原案发现场。产物默认生成在test-results目录下每个失败用例会按测试名生成独立子目录。你还可以用--output自定义目录名。需要注意的是这些产物的收集逻辑同样是通过 fixture teardown 来实现的测试结束的瞬间插件去检查测试结果是 PASS 还是 FAIL再决定保留或删除产物。3.3 用 parametrize 和多浏览器跑出兼容性矩阵除了命令行手选浏览器插件和 pytest 的parametrize配合起来才是完全体。你可以在同一个测试类上跑三种浏览器pytest.mark.parametrize(browser_name, [chromium, firefox, webkit]) def test_checkout(browser_name, page): page.goto(/checkout) # ...看到这里你应该明白了pytest-playwright 做的本质上是把 Playwright 的能力和 pytest 的参数化体系焊接在一起。你不需要写任何代码去判断当前是哪个浏览器因为browser_name参数本身就是插件暴露的 fixture 参数浏览器已经提前按你的要求启动了。4. 插件内部到底接入了 pytest 的哪些机制才让它这么“聪明”很多人用过插件但不知道它为什么能“自动”做那么多事。其实原理并不神秘pytest 本身是一套高度可扩展的框架pytest-playwright 只是充分利用了这几个扩展点。4.1 选项注入与钩子函数pytest 允许插件通过pytest_addoption钩子往命令行里添加自定义参数。插件在启动阶段把这些参数全部注册好再通过pytest_configure做目录初始化。你在命令行看到的那些--browser、--headed、--video就是这么来的。后面创建 fixture 时插件再通过request.config.getoption(...)把配置值取出用来决定浏览器进程的启动方式。整套链路和 pytest 官方插件比如 pytest-html是同构的理解了这一层以后看任何 pytest 生态的插件都会很快上手。4.2 生命周期绑定从 setup 到 teardown 的完整闭环插件最核心的实现是几个带yield的 fixture。yield之前的代码负责创建资源yield之后的代码负责清理。这正好对应 pytest 的 setup/teardown 阶段。测试函数一旦开始执行page 已经可用无论测试结果是 PASS 还是 FAILteardown 都会执行。插件在 teardown 阶段会做以下几件事检查测试状态是否需要保留截图/视频/Trace产物关闭页面与上下文如果有 trace 被保留生成 trace.zip 并写入输出目录。我早年写自动化测试有一个执念总想自己处理“浏览器崩了怎么办”“页面超时怎么办”。用了插件之后我发现这些异常场景插件同样会兜住——浏览器崩溃导致测试失败时teardown 依然会尝试收集产物尽量留下可排查信息。4.3 和 MCP、AI Agent 类工具的边界你最好分清楚最近圈子里总有人把 pytest-playwright 和 MCP、AI Agent 放在一起聊我看有不少人已经搞混了。这里说个我的判断pytest-playwright 是纯测试编排层解决的是“测试怎么写、怎么跑、失败怎么留证据”而 MCP、Agent 类工具比如 Chrome DevTools MCP、Playwright MCP是在另一个层面把浏览器能力抽象成工具接口供大模型或外部程序去调用。虽然底层都依赖 Playwright 的自动化能力但定位完全不同。你在测试框架里关心的是断言、fixture、并发、报告你在 MCP 场景里关心的是如何让模型能够导航页面、点击元素、抽取信息。两者的关注点不重叠不要指望 pytest-playwright 去实现 Agent 的编排也不要指望 MCP 工具给你 pytest 的 fixture 体系。5. 我在实际项目里踩过的坑你大概率也会遇到工具再好生产环境才是试金石。这几年我把 pytest-playwright 用在了好几个中型项目上下面这几个坑不是文档里会写清楚的但杀伤力都很大。5.1 并行跑测试时session 级 browser 不是你想的那样安全既然是 session 级那么多人就会以为所有测试共享同一个浏览器实例是安全的。危险恰恰在这里browser实例确实被共享但每个测试都有自己的 context互不干扰。并行模式下如果你用了pytest-xdist每个 worker 进程其实是独立的 Python 进程所以每个 worker 会各自创建一个 session 级的浏览器实例这个没问题。真正容易踩坑的是你自己在 conftest.py 里定义了一个共享的可变对象比如全局登录态、全局 Cookie 池并期望多个 worker 之间同步这就会出大问题。请记住session 级共享只存在于同一个 worker 进程内部跨进程没有任何状态共享。5.2 Linux CI 上最常见的内存小水管问题在 Docker 或 Linux CI 容器里跑 Chromium经常出现页面突然白屏、链接全部点击无效、随机超时这类看起来“很玄学”的问题。顺着日志查半天最终极大概率是/dev/shm太小。Chromium 默认会把渲染进程的内存映射到共享内存上容器里/dev/shm默认只有 64MB跑复杂页面直接炸。解决办法有两个一是给容器启动加--shm-size1g二是在browserfixture 层设置 Chromium 的 launch 参数禁用共享内存。如果你用不用插件的裸 API这事得你自己处理用插件的话可以通过自定义 fixture 或pytest.ini里的配置来传递 launch 参数。这里我给一个通用的处理思路pytest.fixture(scopesession) def browser_context_args(browser_context_args): return { **browser_context_args, ignore_https_errors: True, }注意这个是覆盖 context 参数的但 launch 级的参数如args[--disable-dev-shm-usage]需要你额外处理。这也是一个文档里不太会强调的坑。5.3 失败重试和 Trace 产物的相互干扰给测试加失败重试是常规操作但和 pytest-playwright 的产物策略一起用就要小心了。默认情况下retain-on-failure只在最终失败时保存 Trace。如果你用pytest-rerunfailures重试了三次插件只会保留最后一次失败的产物前两次失败的原因就看不到了。这有一个很实用的处理办法给重试的用例单独开 Trace用--tracingon强制所有尝试都留档配合pytest-rerunfailures的--reruns参数能还原整个失败链条。不过代价是产物体积和耗时明显上升建议只在排查偶发问题时临时开启日常跑回归还是用retain-on-failure更划算。5.4 等待机制和 pytest 断言的错配很多新手从 Selenium 转过来喜欢写time.sleep(2)这种硬等待。Playwright 内置了一整套自动等待机制比如page.click会自动等待元素可点击get_by_text会自动等待元素出现。但这里有一个容易被忽略的边界Playwright 的自动等待只覆盖它自己的操作如果你拿到元素后直接用assert去断言它的一些状态比如判断某个 class 是否存在这一步 Playwright 不会帮你等。正确的做法是使用expect断言让插件在背后帮你做轮询等待from playwright.sync_api import expect expect(page.locator(.toast)).to_be_visible() expect(page).to_have_title(订单完成)expect的默认超时是 5 秒你可以通过--timeout参数统一调整。这一条非常影响测试稳定性是线上用例 flaky 的重要来源之一。看到这里已经有不少同学意识到过去以为自己写的用例不稳定其实是没搞清楚 Playwright 的自动等待只在操作层生效断言层需要你自己配合expect才行。5.5 浏览器进程清理不干净怎么办回到第一章那个问题浏览器子进程残留。插件虽然会自动关闭浏览器但有些场景下比如浏览器崩溃、机器突然休眠、CI 超时被强杀还是会留下进程。我在 Linux 下排查过不少次两个命令可以快速确认ps -ef | grep chrome | grep -v grep pkill -f chrome真正解决这个问题建议在 CI 的任务结束命令里加清理动作。这不是插件的 bug而是浏览器进程固有的生命周期模型。插件能管的是“正常流程”的启停管不了外部因素的强杀这点需要团队在基础设施层面兜底。最后再说一个我自己使用四年多最真实的体会pytest-playwright 厉害的地方不在于它的代码量有多大而在于它对测试生命周期做了极其克制的设计——该自动的自动浏览器启停、产物收集该显式的显式业务动作、断言逻辑。当你适应了这个节奏之后写测试的体验会非常顺滑上午写的用例下午就能稳稳跑在 CI 上不用再和浏览器进程、等待时间死磕。如果你现在还在手动管理浏览器生命周期真心建议花一个下午把这个插件的能力完整过一遍它替你省下的时间会远远超过你学习它花掉的时间。
pytest-playwright核心原理与生产实践：从fixture到失败产物管理
写这篇东西的起因很简单我经常看到有人在测试群里问“pytest-playwright到底是干嘛的我用 pytest 也能自己写 launch、new_page、close为什么还要装这个插件”还有不少人以为它就是个“让 Playwright 能跑在 pytest 里的翻译器”。实际上pytest-playwright 干的事情远比表面看到的要多。它在你写def test_login(page)的那一刻起就把浏览器启停、上下文隔离、失败截图、视频、Trace、并发策略、命令行参数这些东西全部接管了。这篇文章我就以实际使用者的视角把插件默默帮你做的那些事拆开逐一过一遍顺便把藏在命令背后的原理和我在生产环境里踩过的坑一起说了。1. 没有 pytest-playwright 时我们是怎么被 Playwright 折磨的先说句实在话Playwright 本身的 API 设计是同类工具里数一数二舒服的但“API 舒服”和“写测试舒服”是两回事。你脱离 pytest-playwright直接用 pytest 裸写 Playwright 测试很快就会撞上三个让人烦躁的问题。1.1 资源管理全靠手工忘一句 close 就多一个僵尸进程如果不用插件最朴素的写法差不多是这样from playwright.sync_api import sync_playwright def test_login(): with sync_playwright() as p: browser p.chromium.launch(headlessFalse) context browser.new_context() page context.new_page() try: page.goto(https://example.com) # ... 测试逻辑 finally: context.close() browser.close()这段代码看起来没毛病但它把“测试逻辑”和“资源生命周期”死死地耦合在了一起。一旦中间某个断言抛了异常finally里的清理代码确实还会执行但你在每个测试函数里都要重复写这么一套十个人能写出十种不同的清理顺序。更隐蔽的问题是browser.close()之后Playwright 的浏览器子进程在某些操作系统上并不会立刻消失如果你再开了多个 context 没有关干净跑完一整个测试套件后进程列表里会挂着一堆 Chromium 残留。这个问题的解决思路其实应该由框架层统一处理而不是靠每个测试作者自觉。1.2 失败现场全靠自己抢救截图代码比测试代码还长等测试真的红了之后第二个痛点就来了你想留现场。要截图要录视频要抓 HAR要保存 DOM 快照Playwright 确实都支持但你在裸写 pytest 的情况下每个都需要自己手动在except里写对应代码。我见过最夸张的一个项目失败处理的辅助函数有三百多行维护成本比业务测试本身还高。1.3 配置散落各处换浏览器要靠改代码第三个痛点最伤团队协作浏览器类型、headless 模式、base_url、超时时间、跳过逻辑——这些东西如果没有统一的入口就会散落在各个 fixture、conftest.py、甚至 CI 脚本里。你想在本地用 headed 模式调试在 CI 用 headless不改代码基本做不到。想临时跑一遍 webkit得去改launch()的参数。这些正是 pytest-playwright 存在的理由它把“浏览器进程管理”“测试环境配置”“失败产物收集”这三件跟业务无关的事从你的测试代码里彻底剥离出去。所以看完这一章你应该意识到pytest-playwright 不是一个“翻译层”而是一个完整的测试执行基础设施。2. 插件塞给你的四个 fixture每一个背后都是一套设计决策pytest 的核心武器是 fixturepytest-playwright 的核心武器是内置的 fixture。很多初学者只知道无脑声明page其实插件一共给了你四个标准 fixtureplaywright、browser、browser_context、page。这四个东西作用域不同、生成逻辑不同、彼此之间的依赖关系也不同把它们搞清楚很多诡异问题就能迎刃而解。2.1 每个 fixture 的作用域为什么要这样设计我用一张表把这四个 fixture 的核心特性列出来这是我们项目组内部培训时必讲的一张表。Fixture作用域是否自动使用典型用途playwrightsession是提供 Playwright 入口对象负责全局启停browsersession是默认持久化浏览器实例可被 context 共用browser_contextfunction否每个测试独立上下文隔离登录态和 Cookiepagefunction否每个测试独立标签页绝大多数测试直接用这个playwright和browser是 session 级的这比较好理解启动浏览器是重操作每个测试都重新启动一次浏览器跑几百条用例时间直接爆炸。但browser_context和page却是 function 级的每个测试都新建、每个测试结束就销毁。这个设计的核心逻辑是隔离。浏览器进程可以共享但用户的登录态、localStorage、Cookie 绝对不能在测试之间串。你想想看你测试 A 往购物车里加了一件商品测试 B 如果复用同一个 context就会继承这个脏状态测试 B 的隔离性就废了。pytest-playwright 让 context 和 page 都按测试粒度重建本质上是在“性能”和“隔离性”之间选了一个非常合理的折中。2.2 page fixture 背后发生了什么当你写def test_search(page):时插件实际的执行顺序是这样的先检查playwrightfixture启动 Playwright 内部驱动再拿browserfixture按你命令行里指定的浏览器类型和参数启动真实浏览器接着browser_context创建全新的上下文最后page在 context 上新建标签页。测试执行完毕后清理顺序正好反过来page 关闭、context 关闭、驱动收尾。这意味着你根本不需要写任何 try/finally异常抛出时清理流程也会照常走完。可能有人会疑惑既然playwright和browser是 session 级怎么保证每个测试拿到的 context 是新的答案是这两个 fixture 只负责“进程级”共享而 context 的创建动作绑定在 function 级 fixture 上所以同一浏览器进程里可以不断产出新的隔离环境这就是它们分层的意义。2.3 自定义 fixture 时的一个推荐姿势实际项目里你很少会只用一个裸的page一般都要在测试前做登录、切账号、注入某个 token。这时候正确姿势不是自己去 launch而是基于插件的 fixture 再做一层封装pytest.fixture def admin_page(page): page.goto(/login) page.get_by_label(用户名).fill(admin) page.get_by_label(密码).fill(pass) page.get_by_role(button, name登录).click() yield page注意这里page参数的注入完全由插件完成你只负责“登录”这个业务动作。这个封装的好处是底层浏览器是复用 session 级的而登录状态只存在于当前测试的 context 中不会污染其他测试。这是生产项目中最常见也最合理的 fixture 叠加方式。3. 命令行里那些参数每敲一个都在改变插件的运行行为pytest-playwright 最讨喜的一点是它把大量运行行为做成了命令行参数让“调试环境”和“CI 环境”的切换从改代码变成了改命令。3.1 控制浏览器行为的一组核心参数举几个我很常用的例子--browserchromium或--browserfirefox --browserwebkit指定浏览器可以传多次从而实现多浏览器矩阵。--headed默认是无头模式跑调试时加上这个参数你就看得见浏览器界面了。--browser-channelchrome用本机的 Chrome 而不是 Playwright 自带的 Chromium。--slow-mo500每一步操作之间加 500ms 延迟非常适合演示和调试定位器失效。--deviceiPhone 13模拟移动端设备。--base-urlhttps://staging.example.com给页面访问设置根路径配合page.goto(/path)使用。这些参数最终都会被读取然后注入到browserfixture 的 launch 逻辑和 context 的创建逻辑里。核心逻辑是插件通过pytest_addoption注册这些参数在创建 fixture 时读取配置值再决定启动什么样的浏览器、往 context 里塞什么设备模拟属性。3.2 失败产物的自动收集比你想的更周到这一块是 pytest-playwright 相对于手动方案最有感知度的价值之一。它支持三种产物截图、视频、Trace。命令行参数分别是--screenshot、--video、--tracing每种都有on、off、retain-on-failure三种级别。retain-on-failure的意思是测试通过了就把产物丢掉失败了才保留。这个设计非常聪明既不会让成功用例白白占用磁盘又能保证失败时一定有现场。我强烈建议所有项目默认都开--videoretain-on-failure --tracingretain-on-failure --screenshotonly-on-failure。Trace 文件尤其重要它在trace.zip里记录了页面完整的操作时间线、网络请求、控制台日志排一个偶发失败用例的时候Trace 基本能还原案发现场。产物默认生成在test-results目录下每个失败用例会按测试名生成独立子目录。你还可以用--output自定义目录名。需要注意的是这些产物的收集逻辑同样是通过 fixture teardown 来实现的测试结束的瞬间插件去检查测试结果是 PASS 还是 FAIL再决定保留或删除产物。3.3 用 parametrize 和多浏览器跑出兼容性矩阵除了命令行手选浏览器插件和 pytest 的parametrize配合起来才是完全体。你可以在同一个测试类上跑三种浏览器pytest.mark.parametrize(browser_name, [chromium, firefox, webkit]) def test_checkout(browser_name, page): page.goto(/checkout) # ...看到这里你应该明白了pytest-playwright 做的本质上是把 Playwright 的能力和 pytest 的参数化体系焊接在一起。你不需要写任何代码去判断当前是哪个浏览器因为browser_name参数本身就是插件暴露的 fixture 参数浏览器已经提前按你的要求启动了。4. 插件内部到底接入了 pytest 的哪些机制才让它这么“聪明”很多人用过插件但不知道它为什么能“自动”做那么多事。其实原理并不神秘pytest 本身是一套高度可扩展的框架pytest-playwright 只是充分利用了这几个扩展点。4.1 选项注入与钩子函数pytest 允许插件通过pytest_addoption钩子往命令行里添加自定义参数。插件在启动阶段把这些参数全部注册好再通过pytest_configure做目录初始化。你在命令行看到的那些--browser、--headed、--video就是这么来的。后面创建 fixture 时插件再通过request.config.getoption(...)把配置值取出用来决定浏览器进程的启动方式。整套链路和 pytest 官方插件比如 pytest-html是同构的理解了这一层以后看任何 pytest 生态的插件都会很快上手。4.2 生命周期绑定从 setup 到 teardown 的完整闭环插件最核心的实现是几个带yield的 fixture。yield之前的代码负责创建资源yield之后的代码负责清理。这正好对应 pytest 的 setup/teardown 阶段。测试函数一旦开始执行page 已经可用无论测试结果是 PASS 还是 FAILteardown 都会执行。插件在 teardown 阶段会做以下几件事检查测试状态是否需要保留截图/视频/Trace产物关闭页面与上下文如果有 trace 被保留生成 trace.zip 并写入输出目录。我早年写自动化测试有一个执念总想自己处理“浏览器崩了怎么办”“页面超时怎么办”。用了插件之后我发现这些异常场景插件同样会兜住——浏览器崩溃导致测试失败时teardown 依然会尝试收集产物尽量留下可排查信息。4.3 和 MCP、AI Agent 类工具的边界你最好分清楚最近圈子里总有人把 pytest-playwright 和 MCP、AI Agent 放在一起聊我看有不少人已经搞混了。这里说个我的判断pytest-playwright 是纯测试编排层解决的是“测试怎么写、怎么跑、失败怎么留证据”而 MCP、Agent 类工具比如 Chrome DevTools MCP、Playwright MCP是在另一个层面把浏览器能力抽象成工具接口供大模型或外部程序去调用。虽然底层都依赖 Playwright 的自动化能力但定位完全不同。你在测试框架里关心的是断言、fixture、并发、报告你在 MCP 场景里关心的是如何让模型能够导航页面、点击元素、抽取信息。两者的关注点不重叠不要指望 pytest-playwright 去实现 Agent 的编排也不要指望 MCP 工具给你 pytest 的 fixture 体系。5. 我在实际项目里踩过的坑你大概率也会遇到工具再好生产环境才是试金石。这几年我把 pytest-playwright 用在了好几个中型项目上下面这几个坑不是文档里会写清楚的但杀伤力都很大。5.1 并行跑测试时session 级 browser 不是你想的那样安全既然是 session 级那么多人就会以为所有测试共享同一个浏览器实例是安全的。危险恰恰在这里browser实例确实被共享但每个测试都有自己的 context互不干扰。并行模式下如果你用了pytest-xdist每个 worker 进程其实是独立的 Python 进程所以每个 worker 会各自创建一个 session 级的浏览器实例这个没问题。真正容易踩坑的是你自己在 conftest.py 里定义了一个共享的可变对象比如全局登录态、全局 Cookie 池并期望多个 worker 之间同步这就会出大问题。请记住session 级共享只存在于同一个 worker 进程内部跨进程没有任何状态共享。5.2 Linux CI 上最常见的内存小水管问题在 Docker 或 Linux CI 容器里跑 Chromium经常出现页面突然白屏、链接全部点击无效、随机超时这类看起来“很玄学”的问题。顺着日志查半天最终极大概率是/dev/shm太小。Chromium 默认会把渲染进程的内存映射到共享内存上容器里/dev/shm默认只有 64MB跑复杂页面直接炸。解决办法有两个一是给容器启动加--shm-size1g二是在browserfixture 层设置 Chromium 的 launch 参数禁用共享内存。如果你用不用插件的裸 API这事得你自己处理用插件的话可以通过自定义 fixture 或pytest.ini里的配置来传递 launch 参数。这里我给一个通用的处理思路pytest.fixture(scopesession) def browser_context_args(browser_context_args): return { **browser_context_args, ignore_https_errors: True, }注意这个是覆盖 context 参数的但 launch 级的参数如args[--disable-dev-shm-usage]需要你额外处理。这也是一个文档里不太会强调的坑。5.3 失败重试和 Trace 产物的相互干扰给测试加失败重试是常规操作但和 pytest-playwright 的产物策略一起用就要小心了。默认情况下retain-on-failure只在最终失败时保存 Trace。如果你用pytest-rerunfailures重试了三次插件只会保留最后一次失败的产物前两次失败的原因就看不到了。这有一个很实用的处理办法给重试的用例单独开 Trace用--tracingon强制所有尝试都留档配合pytest-rerunfailures的--reruns参数能还原整个失败链条。不过代价是产物体积和耗时明显上升建议只在排查偶发问题时临时开启日常跑回归还是用retain-on-failure更划算。5.4 等待机制和 pytest 断言的错配很多新手从 Selenium 转过来喜欢写time.sleep(2)这种硬等待。Playwright 内置了一整套自动等待机制比如page.click会自动等待元素可点击get_by_text会自动等待元素出现。但这里有一个容易被忽略的边界Playwright 的自动等待只覆盖它自己的操作如果你拿到元素后直接用assert去断言它的一些状态比如判断某个 class 是否存在这一步 Playwright 不会帮你等。正确的做法是使用expect断言让插件在背后帮你做轮询等待from playwright.sync_api import expect expect(page.locator(.toast)).to_be_visible() expect(page).to_have_title(订单完成)expect的默认超时是 5 秒你可以通过--timeout参数统一调整。这一条非常影响测试稳定性是线上用例 flaky 的重要来源之一。看到这里已经有不少同学意识到过去以为自己写的用例不稳定其实是没搞清楚 Playwright 的自动等待只在操作层生效断言层需要你自己配合expect才行。5.5 浏览器进程清理不干净怎么办回到第一章那个问题浏览器子进程残留。插件虽然会自动关闭浏览器但有些场景下比如浏览器崩溃、机器突然休眠、CI 超时被强杀还是会留下进程。我在 Linux 下排查过不少次两个命令可以快速确认ps -ef | grep chrome | grep -v grep pkill -f chrome真正解决这个问题建议在 CI 的任务结束命令里加清理动作。这不是插件的 bug而是浏览器进程固有的生命周期模型。插件能管的是“正常流程”的启停管不了外部因素的强杀这点需要团队在基础设施层面兜底。最后再说一个我自己使用四年多最真实的体会pytest-playwright 厉害的地方不在于它的代码量有多大而在于它对测试生命周期做了极其克制的设计——该自动的自动浏览器启停、产物收集该显式的显式业务动作、断言逻辑。当你适应了这个节奏之后写测试的体验会非常顺滑上午写的用例下午就能稳稳跑在 CI 上不用再和浏览器进程、等待时间死磕。如果你现在还在手动管理浏览器生命周期真心建议花一个下午把这个插件的能力完整过一遍它替你省下的时间会远远超过你学习它花掉的时间。
