跳到主要内容

测试调试

VS Code 调试器​

我们推荐使用 VS Code 扩展进行调试以获得更好的开发体验。通过 VS Code 扩展，你可以直接在 VS Code 中调试测试、查看错误信息、设置断点并逐步执行测试。

running test in debug mode

错误信息​

当测试失败时，VS Code 会直接在编辑器中显示错误信息，包括预期结果、实际结果以及完整的调用日志。

error messaging in vs code

实时调试​

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

live debugging in VS Code

你也可以在 VS Code 中编辑定位器，Playwright 会在浏览器窗口中实时显示这些更改。

live debugging in VS Code

选择定位器​

通过点击测试侧边栏中的 Pick locator 按钮，选择一个定位器并复制到测试文件中。然后在浏览器中点击你需要的元素，它就会显示在 VS Code 的 Pick locator 框中。按键盘上的 'enter' 键将定位器复制到剪贴板，然后粘贴到代码中的任意位置。如果想取消，可以按 'escape' 键。

Pick locators

Playwright 会分析你的页面并找出最佳的定位器，优先使用角色、文本和测试 ID 定位器。如果 Playwright 发现多个元素匹配定位器，它会优化定位器使其更健壮并唯一标识目标元素，因此你无需担心因定位器问题导致测试失败。

调试模式运行​

要设置断点，请在想要设置断点的行号旁边点击，直到出现红色圆点。通过右键点击测试行旁边的位置，选择在调试模式下运行测试。

setting debug test mode

浏览器窗口将打开，测试会在设置的断点处暂停运行。你可以逐步执行测试、暂停测试或通过 VS Code 菜单重新运行测试。

running test in debug mode

使用 Chrome DevTools 调试测试​

不使用 Debug Test，而是在 VS Code 中选择 Run Test。启用 Show Browser 后，浏览器会话会被复用，允许你打开 Chrome DevTools 来持续调试测试和网页应用。

在不同浏览器中调试​

默认情况下，调试会使用 Chromium 配置。您可以通过右键点击测试侧边栏中的调试图标，然后从下拉菜单中选择"选择默认配置"选项，来在不同的浏览器上调试测试。

在特定配置下调试

然后选择您想要用于调试测试的测试配置。每次在调试模式下运行测试时，都会使用您选择的配置。您可以通过右键点击测试所在行号，然后从菜单中选择"调试测试"来在调试模式下运行测试。

选择调试配置

要了解更多关于调试的信息，请参阅在 Visual Studio Code 中调试。

Playwright 检查器​

Playwright 检查器是一个 GUI 工具，可帮助您调试 Playwright 测试。它允许您逐步执行测试、实时编辑定位器、选择定位器以及查看可操作性日志。

Playwright 检查器

在调试模式下运行​

使用 --debug 标志运行测试以打开检查器。这会配置 Playwright 进行调试并打开检查器。当使用 --debug 时，还会配置一些有用的默认设置：

  • 浏览器以有头模式启动
  • 默认超时设置为 0（= 无超时）

在所有浏览器上调试所有测试​

要调试所有测试，请使用 --debug 标志运行测试命令。这将逐个运行测试，并为每个测试打开检查器和浏览器窗口。

npx playwright test --debug

在所有浏览器上调试单个测试​

要在特定行调试单个测试，运行测试命令后接测试文件名和要调试的测试行号，再加上 --debug 标志。这将在 playwright.config 中配置的每个浏览器上运行单个测试并打开检查器。

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

逐步执行测试​

您可以使用检查器顶部的工具栏来播放、暂停或逐步执行测试的每个操作。您可以看到测试代码中高亮显示的当前操作，以及浏览器窗口中匹配的元素高亮显示。

Playwright Inspector and browser

从特定断点运行测试​

为了加速调试过程，您可以在测试中添加 page.pause() 方法。这样您就不需要逐步执行测试的每个操作来达到想要调试的位置。

await page.pause();

添加 page.pause() 调用后，在调试模式下运行测试。点击检查器中的"继续"按钮将运行测试，并仅在 page.pause() 处停止。

test with page.pause

实时编辑定位器​

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

live editing locators

选择定位器​

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

Picking locators

Playwright 会检查您的页面并找出最佳定位器，优先使用 角色、文本和测试 ID 定位器。如果 Playwright 发现多个元素匹配定位器，它会优化定位器以确保其具有弹性并能唯一标识目标元素，因此您不必担心因定位器问题导致测试失败。

可操作性日志​

当 Playwright 在点击操作上暂停时，它已经执行了可以在日志中找到的 可操作性检查。这可以帮助您理解测试过程中发生了什么以及 Playwright 执行或尝试执行的操作。日志会告诉您元素是否可见、启用且稳定，定位器是否解析为元素，是否滚动到视图中等等。如果无法达到可操作性条件，它会将操作显示为待处理状态。

Actionability Logs

追踪查看器​

Playwright 追踪查看器 是一个 GUI 工具，可让你探索测试过程中记录的 Playwright 追踪记录。你可以通过左侧面板前后浏览每个操作，并直观地查看操作期间发生的情况。在屏幕中央，你可以看到该操作对应的 DOM 快照。右侧面板则显示操作详情，包括时间、参数、返回值和日志。你还可以查看控制台消息、网络请求和源代码。

要了解更多关于如何记录追踪和使用追踪查看器的信息，请参阅 追踪查看器 指南。

浏览器开发者工具​

当使用 PWDEBUG=console 在调试模式下运行时，开发者工具控制台中会提供一个 playwright 对象。开发者工具可以帮助您：

  • 检查 DOM 树并 查找元素选择器
  • 查看执行期间的 控制台日志（或学习如何 通过 API 读取日志）
  • 检查 网络活动 和其他开发者工具功能

这还会将 Playwright 的默认超时时间设置为 0（即无超时）。

Browser Developer Tools with Playwright object

要使用浏览器开发者工具调试测试，首先在测试中设置断点以暂停执行，使用 page.pause() 方法。

await page.pause();

在测试中设置断点后，您可以使用 PWDEBUG=console 运行测试。

PWDEBUG=console npx playwright test

当 Playwright 启动浏览器窗口后，您可以打开开发者工具。playwright 对象将在控制台面板中可用。

playwright.$(selector)​

使用实际的 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' });

定位器 ()
  - 元素: button
  - 元素集合: [button]

playwright.selector(element)​

为给定元素生成选择器。例如，在 Elements 面板中选择一个元素并传入 $0：

playwright.selector($0)

"div[id="glow-ingress-block"] >> text=/.*Hello.*/"

详细 API 日志​

Playwright 支持通过 DEBUG 环境变量启用详细日志记录。

DEBUG=pw:api npx playwright test
备注

对于 WebKit: 在执行过程中启动 WebKit Inspector 会阻止 Playwright 脚本继续执行，并会重置预先配置的用户代理和设备模拟设置。

有头模式​

Playwright 默认以无头模式运行浏览器。要改变这一行为，可以使用 headless: false 作为启动选项。

你还可以使用 slowMo 选项来减慢执行速度（每个操作延迟 N 毫秒），以便在调试时跟踪操作过程。

// Chromium, Firefox 或 WebKit
await chromium.launch({ headless: false, slowMo: 100 });