调试测试
VS Code 调试器
我们建议使用 VS Code 扩展进行调试,以获得更好的开发体验。使用 VS Code 扩展,您可以直接在 VS Code 中调试测试,查看错误消息,设置断点并单步调试测试。

错误消息
如果您的测试失败,VS Code 将直接在编辑器中显示错误消息,其中包含预期值、实际接收值以及完整的调用日志。

实时调试
您可以在 VS Code 中实时调试测试。勾选 Show Browser
选项运行测试后,单击 VS Code 中的任何定位器,它将在浏览器窗口中高亮显示。Playwright 还会显示是否存在多个匹配项。

您还可以在 VS Code 中编辑定位器,Playwright 将在浏览器窗口中实时显示更改。

选择定位器
从测试侧边栏单击选择定位器按钮,选择一个定位器并将其复制到您的测试文件中。然后在浏览器中单击您需要的元素,它现在将显示在 VS Code 的选择定位器框中。按键盘上的 'enter' 键将定位器复制到剪贴板,然后将其粘贴到代码中的任意位置。如果要取消,请按 'escape' 键。

Playwright 将查看您的页面并找出最佳定位器,优先考虑角色、文本和测试 ID 定位器。如果 Playwright 找到与定位器匹配的多个元素,它将改进定位器,使其更具弹性并唯一标识目标元素,因此您无需担心因定位器问题导致的测试失败。
在调试模式下运行
要设置断点,请在您想要设置断点的行号旁边单击,直到出现一个红点。通过右键单击您想要运行的测试旁边的行来在调试模式下运行测试。

将打开一个浏览器窗口,测试将运行并在设置的断点处暂停。您可以在 VS Code 的菜单中单步执行测试、暂停测试和重新运行测试。

使用 Chrome DevTools 调试测试
在 VS Code 中,请选择 Run Test
而不是 Debug Test
。启用 Show Browser
后,浏览器会话将被重用,允许您打开 Chrome DevTools 以持续调试您的测试和 Web 应用程序。
在不同浏览器中调试
默认情况下,调试使用 Chromium Profile。您可以通过右键单击测试侧边栏中的调试图标,然后从下拉菜单中单击“Select Default Profile”选项,在不同的浏览器中调试您的测试。

然后选择您想要用于调试测试的测试 Profile。每次在调试模式下运行测试时,都将使用您选择的 Profile。您可以通过右键单击测试所在的行号并从菜单中选择“Debug Test”来在调试模式下运行测试。

要了解更多关于调试的信息,请参阅 在 Visual Studio Code 中调试。
Playwright Inspector
Playwright Inspector 是一个 GUI 工具,可帮助您调试 Playwright 测试。它允许您单步执行测试、实时编辑定位器、选择定位器并查看操作能力日志。

在调试模式下运行
使用 --debug
标志运行测试以打开 Inspector。这将配置 Playwright 以进行调试并打开 Inspector。使用 --debug
时还会配置其他有用的默认值
- 浏览器在 headed 模式下启动
- 默认超时设置为 0(= 无超时)
在所有浏览器中调试所有测试
要调试所有测试,请使用 --debug
标志运行测试命令。这将逐个运行测试,并为每个测试打开 Inspector 和一个浏览器窗口。
npx playwright test --debug
在所有浏览器中调试一个测试
要在特定行调试一个测试,请运行测试命令,后跟测试文件名和要调试的测试的行号,然后是 --debug
标志。这将在您的 playwright.config
中配置的每个浏览器中运行单个测试并打开 Inspector。
npx playwright test example.spec.ts:10 --debug
在特定浏览器中调试
在 Playwright 中,您可以在 playwright.config
中配置项目。配置后,您可以使用 --project
标志,后跟在 playwright.config
中配置的项目名称,在特定浏览器或移动视口上调试您的测试。
npx playwright test --project=chromium --debug
npx playwright test --project="Mobile Safari" --debug
npx playwright test --project="Microsoft Edge" --debug
在特定浏览器中调试一个测试
要在特定浏览器中运行一个测试,请添加测试文件名和要调试的测试的行号,以及 --project
标志,后跟项目名称。
npx playwright test example.spec.ts:10 --project=webkit --debug
单步执行测试
您可以使用 Inspector 顶部的工具栏播放、暂停或单步执行测试的每个操作。您可以看到当前操作在测试代码中高亮显示,以及匹配的元素在浏览器窗口中高亮显示。

从特定断点运行测试
为了加快调试过程,您可以在测试中添加 page.pause() 方法。这样,您就不必单步执行测试的每个操作即可到达您想要调试的点。
await page.pause();
添加 page.pause()
调用后,在调试模式下运行测试。单击 Inspector 中的“Resume”按钮将运行测试,并且只在 page.pause()
处停止。

实时编辑定位器
在调试模式下运行时,您可以实时编辑定位器。在“选择定位器”按钮旁边有一个字段,显示测试暂停时使用的定位器。您可以直接在选择定位器字段中编辑此定位器,匹配的元素将在浏览器窗口中高亮显示。

选择定位器
在调试时,您可能需要选择一个更具弹性的定位器。您可以通过单击选择定位器按钮并悬停在浏览器窗口中的任何元素上来实现此目的。悬停在元素上时,您将在下方看到高亮显示用于定位该元素的所需代码。单击浏览器中的元素会将定位器添加到字段中,然后您可以调整它或将其复制到代码中。

Playwright 将查看您的页面并找出最佳定位器,优先考虑角色、文本和测试 ID 定位器。如果 Playwright 找到与定位器匹配的多个元素,它将改进定位器,使其更具弹性并唯一标识目标元素,因此您无需担心因定位器问题导致的测试失败。
操作能力日志
当 Playwright 暂停在一个点击操作上时,它已经执行了可以在日志中找到的操作能力检查。这可以帮助您理解测试期间发生了什么以及 Playwright 执行或尝试执行了什么。日志会告诉您元素是否可见、是否启用、是否稳定、定位器是否解析到元素、是否滚动到视图中等等。如果无法达到操作能力,它将把该操作显示为待处理 (pending)。

追踪查看器
Playwright 追踪查看器是一个 GUI 工具,允许您浏览录制的 Playwright 测试追踪。您可以在左侧通过每个操作来回切换,并直观地查看操作期间发生的情况。屏幕中间,您可以看到该操作的 DOM 快照。右侧,您可以查看操作详情,例如时间、参数、返回值和日志。您还可以查看控制台消息、网络请求和源代码。
要了解有关如何记录追踪以及使用追踪查看器的更多信息,请查看追踪查看器指南。
浏览器开发者工具
当在 Debug Mode 下使用 PWDEBUG=console
运行时,开发者工具控制台中将提供一个 playwright
对象。开发者工具可以帮助您
- 检查 DOM 树并查找元素选择器
- 执行期间查看控制台日志(或学习如何通过 API 读取日志)
- 检查网络活动和其他开发者工具功能
这还会将 Playwright 的默认超时设置为 0(= 无超时)。

要使用浏览器开发者工具调试测试,首先在测试中设置一个断点,使用 page.pause() 方法暂停执行。
await page.pause();
在测试中设置断点后,您就可以使用 PWDEBUG=console
运行测试了。
- Bash
- PowerShell
- Batch
PWDEBUG=console npx playwright test
$env:PWDEBUG="console"
npx playwright test
set PWDEBUG=console
npx playwright test
Playwright 启动浏览器窗口后,您可以打开开发者工具。playwright
对象将在控制台面板中可用。
playwright.$(selector)
使用实际的 Playwright 查询引擎查询 Playwright 选择器,例如
playwright.$('.auth-form >> text=Log in');
<button>Log in</button>
playwright.$$(selector)
与 playwright.$
相同,但返回所有匹配的元素。
playwright.$$('li >> text=John')
[<li>, <li>, <li>, <li>]
playwright.inspect(selector)
在 Elements 面板中显示元素。
playwright.inspect('text=Log in')
playwright.locator(selector)
创建一个定位器并查询匹配的元素,例如
playwright.locator('.auth-form', { hasText: 'Log in' });
Locator ()
- element: button
- elements: [button]
playwright.selector(element)
为给定元素生成选择器。例如,在 Elements 面板中选择一个元素并传递 $0
playwright.selector($0)
"div[id="glow-ingress-block"] >> text=/.*Hello.*/"
详细 API 日志
Playwright 支持使用 DEBUG
环境变量进行详细日志记录。
- Bash
- PowerShell
- Batch
DEBUG=pw:api npx playwright test
$env:DEBUG="pw:api"
npx playwright test
set DEBUG=pw:api
npx playwright test
对于 WebKit:在执行期间启动 WebKit Inspector 将阻止 Playwright 脚本进一步执行,并会重置预先配置的用户代理和设备模拟。
Headed 模式
Playwright 默认在 headless 模式下运行浏览器。要改变此行为,请使用 headless: false
作为启动选项。
您还可以使用 slowMo 选项来减慢执行速度(每操作 N 毫秒),以便在调试时跟随查看。
// Chromium, Firefox, or WebKit
await chromium.launch({ headless: false, slowMo: 100 });