1. 项目概述为什么选择 Playwright 作为你的首个自动化测试工具如果你正在寻找一个能让你快速上手、功能强大且对现代Web应用支持极佳的自动化测试工具那么 Playwright 几乎是不二之选。我接触过 Selenium、Puppeteer 等一众工具最终在团队项目中全面转向 Playwright核心原因就一个它能让你把精力集中在测试逻辑本身而不是浪费在解决环境兼容性、等待元素加载、处理复杂交互这些“脏活累活”上。微软开源的这个框架设计之初就考虑到了现代Web开发的痛点比如单页应用SPA的异步加载、Shadow DOM、网络请求拦截等它都提供了优雅的原生支持。所谓“1小时搞定”并非夸张。对于有一定编程基础比如熟悉 Python 或 JavaScript 语法的开发者或测试工程师来说用一小时完成从零环境搭建到写出第一个能稳定运行的测试脚本是完全可行的。这个过程的重点不在于“速成”而在于体验 Playwright 的“顺畅感”——你会发现以往在别的工具里需要写一堆等待和重试代码才能实现的场景在 Playwright 里可能只需要一行。接下来我会带你走一遍这个极速入门流程过程中我会穿插我实际踩过的坑和总结的最佳实践确保你不仅“搭起来”更能“用得好”。2. 环境搭建一步到位的安装与配置策略环境搭建是万事开头难的那一步但 Playwright 把这步做得异常简单。它的设计哲学是“开箱即用”无论是 Python、Node.js 还是 .NET 环境都提供了近乎一键式的安装方案。2.1 核心环境准备语言与包管理器的选择Playwright 支持多种语言绑定最主流的是Python和Node.js。我的建议是如果你来自测试或运维背景Python 的语法简洁生态丰富是绝佳选择如果你是前端或全栈开发对 JavaScript/TypeScript 更熟悉那么直接选择 Node.js 版本。两者在功能上完全对等选择你更顺手的即可。以Python环境为例我强烈推荐使用pip进行安装并搭配虚拟环境。这是避免未来项目依赖冲突的黄金法则。# 1. 创建并进入项目目录 mkdir playwright-quickstart cd playwright-quickstart # 2. 创建 Python 虚拟环境以 venv 为例 python -m venv venv # 3. 激活虚拟环境 # Windows: venv\Scripts\activate # macOS/Linux: source venv/bin/activate # 4. 使用 pip 安装 Playwright pip install playwright注意如果你在 Windows 上使用 PowerShell执行脚本可能会遇到权限错误。这时需要以管理员身份运行 PowerShell并执行Set-ExecutionPolicy RemoteSigned来修改执行策略仅限个人开发环境。或者更安全的方法是直接在 VS Code 的终端里操作。对于Node.js环境使用 npm 或 yarn 同样简单# 初始化项目如果还没有 package.json npm init -y # 安装 Playwright npm init playwrightlatest # 或者使用 yarn yarn create playwright执行npm init playwrightlatest这个命令非常友好它会启动一个交互式命令行向导询问你是否需要安装浏览器、创建示例测试文件和配置文件对于新手来说可以一键完成所有初始化工作。2.2 浏览器安装解决 “playwright install” 慢的痛点安装 Playwright 库之后最关键的一步是安装它需要驱动的浏览器Chromium, Firefox, WebKit。Playwright 自带了一个命令行工具来管理这些浏览器。# 安装所有支持的浏览器Chromium, Firefox, WebKit playwright install这里就是很多人遇到的第一个“坑”playwright install可能会非常慢甚至因网络问题失败。这是因为 Playwright 需要从官方渠道下载数百MB的浏览器二进制文件。我的实战经验是使用镜像源推荐给国内用户Playwright 允许通过环境变量指定下载镜像。阿里云提供了不错的镜像。# Linux/macOS export PLAYWRIGHT_DOWNLOAD_HOSThttps://npmmirror.com/mirrors/playwright playwright install # Windows (PowerShell) $env:PLAYWRIGHT_DOWNLOAD_HOSThttps://npmmirror.com/mirrors/playwright playwright install设置镜像后下载速度通常会有质的飞跃。仅安装所需浏览器如果你确定只测试 Chrome/Edge 内核的浏览器可以只安装 Chromium节省时间和磁盘空间。playwright install chromium离线安装在公司内网等无法连接外网的环境可以先在一台能联网的机器上执行安装然后将~/.cache/ms-playwright目录Linux/macOS或%USERPROFILE%\AppData\Local\ms-playwright目录Windows整体拷贝到目标机器对应的位置。Playwright 运行时会自动识别这些已下载的浏览器。安装成功后你可以通过一个简单命令验证playwright --version这会输出 Playwright 命令行工具和核心库的版本号。2.3 IDE 配置让编写和调试更高效工欲善其事必先利其器。一个好的 IDE 能极大提升编写 Playwright 脚本的效率。VS Code Playwright 插件这是目前最强大的组合。在 VS Code 扩展商店搜索 “Playwright Test for VSCode” 并安装。这个插件提供了测试侧边栏可视化地运行和调试单个测试、整个文件或所有测试。代码追踪Trace Viewer当测试失败时可以生成一个可视化的追踪文件精确回放测试步骤查看每个时刻的页面快照、控制台日志和网络请求这是排查问题的神器。智能提示自动补全 API显示参数说明。PyCharm / IntelliJ IDEA对于 Python 用户这些 IDE 对 Playwright 也有很好的支持可以配置运行配置来执行测试。在 VS Code 中我习惯为 Playwright 测试创建一个单独的启动配置在.vscode/launch.json中方便调试。但通常直接用插件提供的“运行”和“调试”按钮就足够了。3. 首个测试脚本解剖从 “Hello World” 到理解核心概念环境就绪现在我们来创建第一个有实际意义的测试脚本。我们不写简单的打开页面而是写一个能自动在百度搜索“Playwright”并验证结果的脚本。这个过程会涉及 Playwright 最核心的几个概念。3.1 脚本结构同步与异步模式的选择Playwright 的 API 支持同步和异步两种编程风格。Python 版本两者都支持而 Node.js 版本主要推荐使用异步async/await。对于新手我建议从同步模式开始逻辑更直观。等熟悉基本操作后再转向异步模式以处理更复杂的并发场景。下面是一个 Python 同步模式的完整示例脚本first_test.pyfrom playwright.sync_api import sync_playwright def run(playwright): # 1. 启动浏览器。这里选择 ChromiumheadlessFalse 表示打开可视化界面 browser playwright.chromium.launch(headlessFalse, slow_mo1000) # slow_mo 让动作慢一点方便观察 # 2. 创建一个新的浏览器上下文Context相当于一个独立的会话可以隔离 cookies、缓存等 context browser.new_context() # 3. 在上下文中打开一个新页面Page page context.new_page() try: # 4. 导航到百度首页 page.goto(https://www.baidu.com) print(f页面标题: {page.title()}) # 5. 定位搜索输入框并输入关键词 “Playwright” # Playwright 提供了多种定位器Locator这里使用最常用的 CSS 选择器 search_box page.locator(input#kw) # 定位 id 为 ‘kw’ 的 input 元素 search_box.fill(Playwright) # fill 方法用于填充输入框 # 6. 定位搜索按钮并点击 search_button page.locator(input#su) search_button.click() # 7. 等待页面导航完成搜索结果加载 page.wait_for_load_state(networkidle) # 等待网络基本空闲 # 8. 验证搜索结果检查页面标题或结果中是否包含预期关键词 # 这里使用更可靠的等待等待第一个搜索结果链接出现 first_result page.locator(div.result h3 a).first first_result.wait_for(statevisible) # 获取链接文本并验证 result_text first_result.text_content() print(f第一个结果: {result_text}) assert playwright in result_text.lower(), f搜索结果未包含 playwright, 实际为: {result_text} print(测试通过) except Exception as e: print(f测试失败: {e}) # 可以在失败时截图这是非常实用的调试手段 page.screenshot(pathtest_failure.png) raise e finally: # 9. 无论如何最后都要关闭浏览器 browser.close() # 使用 sync_playwright 上下文管理器来启动和停止 Playwright with sync_playwright() as playwright: run(playwright)3.2 核心概念深度解析这个脚本虽小却包含了 Playwright 最精髓的部分Browser, Context, Page这是 Playwright 的三层架构理解它们对编写健壮的测试至关重要。Browser对应一个浏览器实例如 Chrome。启动成本较高。Context浏览器上下文。这是一个独立的会话层像是一个隐身窗口。每个 Context 拥有独立的 cookies、localStorage、权限设置等。你可以创建多个 Context 来模拟多个用户同时登录且彼此隔离互不干扰。这是实现并行测试和状态隔离的关键。Page一个 Context 中可以包含多个标签页Page。Page 是我们与网页内容交互的主要对象。实操心得对于大多数单用户流程的测试用一个 Browser一个 Context一个 Page 就够了。但当需要测试多用户场景或避免 cookie 污染时务必使用不同的 Context。定位器Locatorpage.locator(selector)是 Playwright 的核心交互方式。它返回一个Locator对象代表一个或一组页面元素。Locator 是惰性的只有在真正需要操作如click()、fill()或断言时它才会去页面上查找元素。更重要的是Locator 内置了自动等待和重试机制。当执行locator.click()时Playwright 会等待该元素出现在 DOM 中。等待该元素可见非隐藏非0尺寸。等待该元素可交互未被禁用未被其他元素遮挡。如果等待超时默认30秒才抛出错误。 这彻底解决了传统自动化测试中令人头疼的“元素未找到”或“元素不可点击”的时序问题。等待策略除了 Locator 自带的智能等待我们还可以使用显式等待。page.wait_for_load_state(state)等待页面达到某种加载状态。“networkidle”表示网络空闲大约500ms内没有新请求非常适合等待 SPA 应用动态加载完成。locator.wait_for(state)等待定位器对应的元素达到特定状态如“visible”、“hidden”、“attached”等。注意事项尽量避免使用time.sleep(seconds)这种固定等待。它不可靠且低效。始终优先使用 Playwright 提供的基于条件的等待。断言脚本中使用了 Python 内置的assert进行验证。在实际项目中更推荐使用 Playwright 自带的断言库如expect(locator).to_have_text(...)或 pytest 等测试框架的断言它们能提供更丰富的匹配器和更清晰的错误信息。4. 脚本增强与调试技巧让测试更稳定、更易维护第一个脚本能跑通只是开始。要让它在不同环境、不同时间点都能稳定运行并易于调试和维护还需要一些技巧。4.1 处理动态元素与复杂选择器现代网页元素 ID 和类名经常是动态生成的。依赖#kw、#su这样的 ID 可能在未来失效。更健壮的选择器策略是使用语义化属性如># 假设搜索按钮有># 定位包含特定文本的 div 下的第一个 a 标签 link page.locator(xpath//div[contains(text(),最新消息)]//a[1])Playwright CodeGen 工具这是快速生成选择器的神器。运行playwright codegen [url]它会打开一个浏览器和一个录制窗口。你在浏览器里的所有操作都会被自动转换成 Playwright 代码并给出推荐的选择器。这是学习定位器写法的绝佳方式。4.2 配置与复用使用playwright.config.ts/js或pytest.ini对于正式项目不应该把浏览器类型、超时时间、基础URL等配置硬编码在脚本里。Playwright 支持配置文件。对于 Node.js/TypeScript 项目运行npm init playwrightlatest时会自动生成playwright.config.ts。对于 Python 项目可以结合 pytest 使用。一个简化的 Python pytest 配置示例conftest.pyimport pytest from playwright.sync_api import Page, BrowserContext pytest.fixture(scopesession) def browser_context_args(browser_context_args): # 为所有浏览器上下文设置默认视口大小和忽略 HTTPS 错误 return { **browser_context_args, viewport: {width: 1920, height: 1080}, ignore_https_errors: True } pytest.fixture def base_url(pytestconfig): # 从命令行参数或 pytest.ini 读取基础 URL return pytestconfig.getoption(--base-url) or https://www.baidu.com然后在测试中你可以通过 fixture 来使用page和base_urldef test_search(page, base_url): page.goto(base_url) # ... 测试逻辑这样通过命令行pytest --base-urlhttps://www.example.com就能轻松切换测试环境。4.3 高级交互与网络拦截Playwright 的强大远不止点击和输入。文件上传下载# 文件上传无需触发文件选择对话框 page.locator(input[typefile]).set_input_files(/path/to/file.pdf) # 监听下载事件 with page.expect_download() as download_info: page.locator(a#download-link).click() download download_info.value # 保存下载文件 download.save_as(/path/to/save.pdf)网络请求拦截与模拟这是做集成测试或 mock 后端 API 的利器。# 拦截所有请求并修改或记录 def handle_route(route): if api/user in route.request.url: # 模拟 API 响应 route.fulfill(json{name: Mock User}) else: route.continue_() page.route(**/*, handle_route)执行 JavaScript# 在页面上下文中执行 JS获取或操作页面数据 dimensions page.evaluate(() { return { width: document.documentElement.clientWidth, height: document.documentElement.clientHeight }; }) print(dimensions)5. 常见问题排查与实战心得即使按照最佳实践编写脚本在实际运行中仍可能遇到问题。以下是几个最常见的问题及我的排查思路。5.1 元素定位失败超时与竞态条件问题Timeout 30000ms exceeded.这是最常见的错误意味着 Playwright 在30秒内没找到或没等到元素达到预期状态。排查步骤手动验证选择器在浏览器开发者工具的控制台里用document.querySelector(你的选择器)或$$(你的选择器)验证你的选择器在当前页面是否有效。页面结构可能已经变了。检查元素状态元素可能被隐藏display: none、被覆盖z-index、或者存在于iframe中。使用locator.wait_for(stateattached)先确保元素在 DOM 里再用statevisible确保可见。等待页面稳定在操作前确保页面加载完成。对于单页应用page.wait_for_load_state(networkidle)比load更有效。有时甚至需要等待某个特定元素出现作为“页面已就绪”的信号。使用page.pause()进行交互式调试在脚本中插入page.pause()运行时会打开 Playwright Inspector你可以单步执行实时查看页面状态和可用的定位器建议。启用慢动作和录制启动浏览器时设置headlessFalse, slow_mo1000并打开录制videos/目录在配置中设置video: ‘on’。慢动作让你看清每一步视频记录了失败时的完整过程。5.2 测试在 CI/CD 环境中失败问题脚本在本地运行良好但在 Jenkins、GitHub Actions 等无头headlessCI 环境中失败。解决方案确保浏览器已安装CI 环境通常是全新的容器。必须在构建步骤中显式运行playwright install或playwright install --with-deps后者会同时安装系统依赖。处理 Headless 模式差异有些网页在无头模式下行为可能不同。首先尝试在 CI 配置中也设置headless: false如果环境支持 GUI。如果不支持可以尝试headless: ‘new’Chromium 的新无头模式更接近真实浏览器。还可以通过args: [‘--window-size1920,1080’]等参数来模拟真实视口。使用官方 Docker 镜像Playwright 提供了预装所有依赖的 Docker 镜像如mcr.microsoft.com/playwright/python。在 CI 中使用这些镜像是最省事、最稳定的方式。检查资源与权限CI 环境的 CPU/内存可能有限网络也可能不稳定。适当增加全局超时时间timeout和动作超时时间action_timeout。5.3 性能优化与稳定性提升复用 Browser Context创建 Browser 实例开销最大Context 次之Page 最轻。对于一组相关的测试尽量复用同一个 Browser 和 Context只新建 Page。可以使用pytest的session作用域的 fixture 来实现。并行执行Playwright Test 运行器Node.js和pytest-xdistPython支持并行运行测试。确保每个测试 worker 使用独立的 Browser Context 或 Page 以实现隔离。清理状态每个测试结束后清理 Context 中的 cookies、localStorage或直接关闭 Page以确保测试之间的独立性。context.clear_cookies()和context.clear_permissions()很有用。合理使用断言断言失败会立即终止测试。对于一组相关的验证可以考虑使用“软断言”收集所有验证错误后再统一报告避免因一个非关键断言失败而错过后续的错误信息。5.4 我的独家避坑清单不要依赖page.$()和page.$$()这是旧版 API返回的是ElementHandle它不具备Locator的自动等待和重试能力。在新代码中一律使用page.locator()。谨慎处理弹窗和新窗口对于window.open或链接的target_blank使用page.wait_for_event(popup)来捕获新页面对象而不是尝试从page.context.pages列表中去猜。处理 Shadow DOMPlaywright 定位器能穿透 Shadow DOM。直接用locator(div::shadow-root input)这样的语法可能不工作。正确做法是先定位到 Shadow Host然后用.shadow_root属性Python或.locator()链式调用进入 Shadow DOM。shadow_host page.locator(my-custom-element) inner_input shadow_host.locator(input)截图和追踪是你的朋友在测试的关键步骤如登录后或失败时pytest的pytest.hookimpl钩子自动截图或保存追踪文件context.tracing.start()和stop()。这些是事后分析问题的黄金资料。阅读官方文档Playwright 的官方文档playwright.dev写得极其出色API 文档详尽示例丰富。遇到问题时第一选择应该是去文档搜索相关 API而不是盲目搜索。
Playwright自动化测试1小时极速入门：从环境搭建到首个脚本实战
发布时间：2026/7/5 17:07:08
1. 项目概述为什么选择 Playwright 作为你的首个自动化测试工具如果你正在寻找一个能让你快速上手、功能强大且对现代Web应用支持极佳的自动化测试工具那么 Playwright 几乎是不二之选。我接触过 Selenium、Puppeteer 等一众工具最终在团队项目中全面转向 Playwright核心原因就一个它能让你把精力集中在测试逻辑本身而不是浪费在解决环境兼容性、等待元素加载、处理复杂交互这些“脏活累活”上。微软开源的这个框架设计之初就考虑到了现代Web开发的痛点比如单页应用SPA的异步加载、Shadow DOM、网络请求拦截等它都提供了优雅的原生支持。所谓“1小时搞定”并非夸张。对于有一定编程基础比如熟悉 Python 或 JavaScript 语法的开发者或测试工程师来说用一小时完成从零环境搭建到写出第一个能稳定运行的测试脚本是完全可行的。这个过程的重点不在于“速成”而在于体验 Playwright 的“顺畅感”——你会发现以往在别的工具里需要写一堆等待和重试代码才能实现的场景在 Playwright 里可能只需要一行。接下来我会带你走一遍这个极速入门流程过程中我会穿插我实际踩过的坑和总结的最佳实践确保你不仅“搭起来”更能“用得好”。2. 环境搭建一步到位的安装与配置策略环境搭建是万事开头难的那一步但 Playwright 把这步做得异常简单。它的设计哲学是“开箱即用”无论是 Python、Node.js 还是 .NET 环境都提供了近乎一键式的安装方案。2.1 核心环境准备语言与包管理器的选择Playwright 支持多种语言绑定最主流的是Python和Node.js。我的建议是如果你来自测试或运维背景Python 的语法简洁生态丰富是绝佳选择如果你是前端或全栈开发对 JavaScript/TypeScript 更熟悉那么直接选择 Node.js 版本。两者在功能上完全对等选择你更顺手的即可。以Python环境为例我强烈推荐使用pip进行安装并搭配虚拟环境。这是避免未来项目依赖冲突的黄金法则。# 1. 创建并进入项目目录 mkdir playwright-quickstart cd playwright-quickstart # 2. 创建 Python 虚拟环境以 venv 为例 python -m venv venv # 3. 激活虚拟环境 # Windows: venv\Scripts\activate # macOS/Linux: source venv/bin/activate # 4. 使用 pip 安装 Playwright pip install playwright注意如果你在 Windows 上使用 PowerShell执行脚本可能会遇到权限错误。这时需要以管理员身份运行 PowerShell并执行Set-ExecutionPolicy RemoteSigned来修改执行策略仅限个人开发环境。或者更安全的方法是直接在 VS Code 的终端里操作。对于Node.js环境使用 npm 或 yarn 同样简单# 初始化项目如果还没有 package.json npm init -y # 安装 Playwright npm init playwrightlatest # 或者使用 yarn yarn create playwright执行npm init playwrightlatest这个命令非常友好它会启动一个交互式命令行向导询问你是否需要安装浏览器、创建示例测试文件和配置文件对于新手来说可以一键完成所有初始化工作。2.2 浏览器安装解决 “playwright install” 慢的痛点安装 Playwright 库之后最关键的一步是安装它需要驱动的浏览器Chromium, Firefox, WebKit。Playwright 自带了一个命令行工具来管理这些浏览器。# 安装所有支持的浏览器Chromium, Firefox, WebKit playwright install这里就是很多人遇到的第一个“坑”playwright install可能会非常慢甚至因网络问题失败。这是因为 Playwright 需要从官方渠道下载数百MB的浏览器二进制文件。我的实战经验是使用镜像源推荐给国内用户Playwright 允许通过环境变量指定下载镜像。阿里云提供了不错的镜像。# Linux/macOS export PLAYWRIGHT_DOWNLOAD_HOSThttps://npmmirror.com/mirrors/playwright playwright install # Windows (PowerShell) $env:PLAYWRIGHT_DOWNLOAD_HOSThttps://npmmirror.com/mirrors/playwright playwright install设置镜像后下载速度通常会有质的飞跃。仅安装所需浏览器如果你确定只测试 Chrome/Edge 内核的浏览器可以只安装 Chromium节省时间和磁盘空间。playwright install chromium离线安装在公司内网等无法连接外网的环境可以先在一台能联网的机器上执行安装然后将~/.cache/ms-playwright目录Linux/macOS或%USERPROFILE%\AppData\Local\ms-playwright目录Windows整体拷贝到目标机器对应的位置。Playwright 运行时会自动识别这些已下载的浏览器。安装成功后你可以通过一个简单命令验证playwright --version这会输出 Playwright 命令行工具和核心库的版本号。2.3 IDE 配置让编写和调试更高效工欲善其事必先利其器。一个好的 IDE 能极大提升编写 Playwright 脚本的效率。VS Code Playwright 插件这是目前最强大的组合。在 VS Code 扩展商店搜索 “Playwright Test for VSCode” 并安装。这个插件提供了测试侧边栏可视化地运行和调试单个测试、整个文件或所有测试。代码追踪Trace Viewer当测试失败时可以生成一个可视化的追踪文件精确回放测试步骤查看每个时刻的页面快照、控制台日志和网络请求这是排查问题的神器。智能提示自动补全 API显示参数说明。PyCharm / IntelliJ IDEA对于 Python 用户这些 IDE 对 Playwright 也有很好的支持可以配置运行配置来执行测试。在 VS Code 中我习惯为 Playwright 测试创建一个单独的启动配置在.vscode/launch.json中方便调试。但通常直接用插件提供的“运行”和“调试”按钮就足够了。3. 首个测试脚本解剖从 “Hello World” 到理解核心概念环境就绪现在我们来创建第一个有实际意义的测试脚本。我们不写简单的打开页面而是写一个能自动在百度搜索“Playwright”并验证结果的脚本。这个过程会涉及 Playwright 最核心的几个概念。3.1 脚本结构同步与异步模式的选择Playwright 的 API 支持同步和异步两种编程风格。Python 版本两者都支持而 Node.js 版本主要推荐使用异步async/await。对于新手我建议从同步模式开始逻辑更直观。等熟悉基本操作后再转向异步模式以处理更复杂的并发场景。下面是一个 Python 同步模式的完整示例脚本first_test.pyfrom playwright.sync_api import sync_playwright def run(playwright): # 1. 启动浏览器。这里选择 ChromiumheadlessFalse 表示打开可视化界面 browser playwright.chromium.launch(headlessFalse, slow_mo1000) # slow_mo 让动作慢一点方便观察 # 2. 创建一个新的浏览器上下文Context相当于一个独立的会话可以隔离 cookies、缓存等 context browser.new_context() # 3. 在上下文中打开一个新页面Page page context.new_page() try: # 4. 导航到百度首页 page.goto(https://www.baidu.com) print(f页面标题: {page.title()}) # 5. 定位搜索输入框并输入关键词 “Playwright” # Playwright 提供了多种定位器Locator这里使用最常用的 CSS 选择器 search_box page.locator(input#kw) # 定位 id 为 ‘kw’ 的 input 元素 search_box.fill(Playwright) # fill 方法用于填充输入框 # 6. 定位搜索按钮并点击 search_button page.locator(input#su) search_button.click() # 7. 等待页面导航完成搜索结果加载 page.wait_for_load_state(networkidle) # 等待网络基本空闲 # 8. 验证搜索结果检查页面标题或结果中是否包含预期关键词 # 这里使用更可靠的等待等待第一个搜索结果链接出现 first_result page.locator(div.result h3 a).first first_result.wait_for(statevisible) # 获取链接文本并验证 result_text first_result.text_content() print(f第一个结果: {result_text}) assert playwright in result_text.lower(), f搜索结果未包含 playwright, 实际为: {result_text} print(测试通过) except Exception as e: print(f测试失败: {e}) # 可以在失败时截图这是非常实用的调试手段 page.screenshot(pathtest_failure.png) raise e finally: # 9. 无论如何最后都要关闭浏览器 browser.close() # 使用 sync_playwright 上下文管理器来启动和停止 Playwright with sync_playwright() as playwright: run(playwright)3.2 核心概念深度解析这个脚本虽小却包含了 Playwright 最精髓的部分Browser, Context, Page这是 Playwright 的三层架构理解它们对编写健壮的测试至关重要。Browser对应一个浏览器实例如 Chrome。启动成本较高。Context浏览器上下文。这是一个独立的会话层像是一个隐身窗口。每个 Context 拥有独立的 cookies、localStorage、权限设置等。你可以创建多个 Context 来模拟多个用户同时登录且彼此隔离互不干扰。这是实现并行测试和状态隔离的关键。Page一个 Context 中可以包含多个标签页Page。Page 是我们与网页内容交互的主要对象。实操心得对于大多数单用户流程的测试用一个 Browser一个 Context一个 Page 就够了。但当需要测试多用户场景或避免 cookie 污染时务必使用不同的 Context。定位器Locatorpage.locator(selector)是 Playwright 的核心交互方式。它返回一个Locator对象代表一个或一组页面元素。Locator 是惰性的只有在真正需要操作如click()、fill()或断言时它才会去页面上查找元素。更重要的是Locator 内置了自动等待和重试机制。当执行locator.click()时Playwright 会等待该元素出现在 DOM 中。等待该元素可见非隐藏非0尺寸。等待该元素可交互未被禁用未被其他元素遮挡。如果等待超时默认30秒才抛出错误。 这彻底解决了传统自动化测试中令人头疼的“元素未找到”或“元素不可点击”的时序问题。等待策略除了 Locator 自带的智能等待我们还可以使用显式等待。page.wait_for_load_state(state)等待页面达到某种加载状态。“networkidle”表示网络空闲大约500ms内没有新请求非常适合等待 SPA 应用动态加载完成。locator.wait_for(state)等待定位器对应的元素达到特定状态如“visible”、“hidden”、“attached”等。注意事项尽量避免使用time.sleep(seconds)这种固定等待。它不可靠且低效。始终优先使用 Playwright 提供的基于条件的等待。断言脚本中使用了 Python 内置的assert进行验证。在实际项目中更推荐使用 Playwright 自带的断言库如expect(locator).to_have_text(...)或 pytest 等测试框架的断言它们能提供更丰富的匹配器和更清晰的错误信息。4. 脚本增强与调试技巧让测试更稳定、更易维护第一个脚本能跑通只是开始。要让它在不同环境、不同时间点都能稳定运行并易于调试和维护还需要一些技巧。4.1 处理动态元素与复杂选择器现代网页元素 ID 和类名经常是动态生成的。依赖#kw、#su这样的 ID 可能在未来失效。更健壮的选择器策略是使用语义化属性如># 假设搜索按钮有># 定位包含特定文本的 div 下的第一个 a 标签 link page.locator(xpath//div[contains(text(),最新消息)]//a[1])Playwright CodeGen 工具这是快速生成选择器的神器。运行playwright codegen [url]它会打开一个浏览器和一个录制窗口。你在浏览器里的所有操作都会被自动转换成 Playwright 代码并给出推荐的选择器。这是学习定位器写法的绝佳方式。4.2 配置与复用使用playwright.config.ts/js或pytest.ini对于正式项目不应该把浏览器类型、超时时间、基础URL等配置硬编码在脚本里。Playwright 支持配置文件。对于 Node.js/TypeScript 项目运行npm init playwrightlatest时会自动生成playwright.config.ts。对于 Python 项目可以结合 pytest 使用。一个简化的 Python pytest 配置示例conftest.pyimport pytest from playwright.sync_api import Page, BrowserContext pytest.fixture(scopesession) def browser_context_args(browser_context_args): # 为所有浏览器上下文设置默认视口大小和忽略 HTTPS 错误 return { **browser_context_args, viewport: {width: 1920, height: 1080}, ignore_https_errors: True } pytest.fixture def base_url(pytestconfig): # 从命令行参数或 pytest.ini 读取基础 URL return pytestconfig.getoption(--base-url) or https://www.baidu.com然后在测试中你可以通过 fixture 来使用page和base_urldef test_search(page, base_url): page.goto(base_url) # ... 测试逻辑这样通过命令行pytest --base-urlhttps://www.example.com就能轻松切换测试环境。4.3 高级交互与网络拦截Playwright 的强大远不止点击和输入。文件上传下载# 文件上传无需触发文件选择对话框 page.locator(input[typefile]).set_input_files(/path/to/file.pdf) # 监听下载事件 with page.expect_download() as download_info: page.locator(a#download-link).click() download download_info.value # 保存下载文件 download.save_as(/path/to/save.pdf)网络请求拦截与模拟这是做集成测试或 mock 后端 API 的利器。# 拦截所有请求并修改或记录 def handle_route(route): if api/user in route.request.url: # 模拟 API 响应 route.fulfill(json{name: Mock User}) else: route.continue_() page.route(**/*, handle_route)执行 JavaScript# 在页面上下文中执行 JS获取或操作页面数据 dimensions page.evaluate(() { return { width: document.documentElement.clientWidth, height: document.documentElement.clientHeight }; }) print(dimensions)5. 常见问题排查与实战心得即使按照最佳实践编写脚本在实际运行中仍可能遇到问题。以下是几个最常见的问题及我的排查思路。5.1 元素定位失败超时与竞态条件问题Timeout 30000ms exceeded.这是最常见的错误意味着 Playwright 在30秒内没找到或没等到元素达到预期状态。排查步骤手动验证选择器在浏览器开发者工具的控制台里用document.querySelector(你的选择器)或$$(你的选择器)验证你的选择器在当前页面是否有效。页面结构可能已经变了。检查元素状态元素可能被隐藏display: none、被覆盖z-index、或者存在于iframe中。使用locator.wait_for(stateattached)先确保元素在 DOM 里再用statevisible确保可见。等待页面稳定在操作前确保页面加载完成。对于单页应用page.wait_for_load_state(networkidle)比load更有效。有时甚至需要等待某个特定元素出现作为“页面已就绪”的信号。使用page.pause()进行交互式调试在脚本中插入page.pause()运行时会打开 Playwright Inspector你可以单步执行实时查看页面状态和可用的定位器建议。启用慢动作和录制启动浏览器时设置headlessFalse, slow_mo1000并打开录制videos/目录在配置中设置video: ‘on’。慢动作让你看清每一步视频记录了失败时的完整过程。5.2 测试在 CI/CD 环境中失败问题脚本在本地运行良好但在 Jenkins、GitHub Actions 等无头headlessCI 环境中失败。解决方案确保浏览器已安装CI 环境通常是全新的容器。必须在构建步骤中显式运行playwright install或playwright install --with-deps后者会同时安装系统依赖。处理 Headless 模式差异有些网页在无头模式下行为可能不同。首先尝试在 CI 配置中也设置headless: false如果环境支持 GUI。如果不支持可以尝试headless: ‘new’Chromium 的新无头模式更接近真实浏览器。还可以通过args: [‘--window-size1920,1080’]等参数来模拟真实视口。使用官方 Docker 镜像Playwright 提供了预装所有依赖的 Docker 镜像如mcr.microsoft.com/playwright/python。在 CI 中使用这些镜像是最省事、最稳定的方式。检查资源与权限CI 环境的 CPU/内存可能有限网络也可能不稳定。适当增加全局超时时间timeout和动作超时时间action_timeout。5.3 性能优化与稳定性提升复用 Browser Context创建 Browser 实例开销最大Context 次之Page 最轻。对于一组相关的测试尽量复用同一个 Browser 和 Context只新建 Page。可以使用pytest的session作用域的 fixture 来实现。并行执行Playwright Test 运行器Node.js和pytest-xdistPython支持并行运行测试。确保每个测试 worker 使用独立的 Browser Context 或 Page 以实现隔离。清理状态每个测试结束后清理 Context 中的 cookies、localStorage或直接关闭 Page以确保测试之间的独立性。context.clear_cookies()和context.clear_permissions()很有用。合理使用断言断言失败会立即终止测试。对于一组相关的验证可以考虑使用“软断言”收集所有验证错误后再统一报告避免因一个非关键断言失败而错过后续的错误信息。5.4 我的独家避坑清单不要依赖page.$()和page.$$()这是旧版 API返回的是ElementHandle它不具备Locator的自动等待和重试能力。在新代码中一律使用page.locator()。谨慎处理弹窗和新窗口对于window.open或链接的target_blank使用page.wait_for_event(popup)来捕获新页面对象而不是尝试从page.context.pages列表中去猜。处理 Shadow DOMPlaywright 定位器能穿透 Shadow DOM。直接用locator(div::shadow-root input)这样的语法可能不工作。正确做法是先定位到 Shadow Host然后用.shadow_root属性Python或.locator()链式调用进入 Shadow DOM。shadow_host page.locator(my-custom-element) inner_input shadow_host.locator(input)截图和追踪是你的朋友在测试的关键步骤如登录后或失败时pytest的pytest.hookimpl钩子自动截图或保存追踪文件context.tracing.start()和stop()。这些是事后分析问题的黄金资料。阅读官方文档Playwright 的官方文档playwright.dev写得极其出色API 文档详尽示例丰富。遇到问题时第一选择应该是去文档搜索相关 API而不是盲目搜索。
