调试测试

VS Code 调试器

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

错误消息

如果测试失败，VS Code 会在编辑器中显示错误消息，展示预期的结果、实际接收到的结果以及完整的调用日志。

实时调试

您可以在 VS Code 中实时调试测试。运行测试时，选中 “Show Browser” 选项后，点击 VS Code 中的任何定位器，它将在浏览器窗口中被高亮显示。如果有多个匹配项，Playwright 也会告知您。

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

选择定位器

通过点击测试侧边栏的 “Pick locator” 按钮，选择定位器并将其复制到您的测试文件中。然后在浏览器中点击所需的元素，定位器将显示在 VS Code 的 Pick locator 框中。按下键盘上的 “Enter” 将定位器复制到剪贴板，并可以粘贴到代码中；按 “Escape” 则取消操作。

Playwright 会分析页面并找出最佳的定位器，优先选择角色、文本和测试 ID 定位器。如果 Playwright 找到多个匹配的元素，它会优化定位器，确保能够唯一标识目标元素，从而避免因定位器问题导致的测试失败。

进入调试模式

要设置断点，在您想设置断点的行号旁点击，直到出现红点。在想要运行的测试旁点击右键，选择调试模式。

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

在不同浏览器中调试

默认情况下，调试使用 Chromium 配置。您可以右键点击测试侧边栏中的调试图标，从下拉菜单中选择 “Select Default Profile” 来选择不同的浏览器配置进行调试。

然后选择您希望用于调试测试的测试配置文件。每次在调试模式下运行测试时，都会使用您选择的配置文件。您可以通过右键点击测试的行号，并从菜单中选择 “Debug Test” 来以调试模式运行测试。

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

Playwright Inspector

Playwright Inspector 是一个图形界面工具，帮助你调试 Playwright 测试。它允许你逐步执行测试、实时编辑定位器、选择定位器并查看可操作性日志。

以调试模式运行

使用 --debug 标志运行你的测试以打开 Inspector。这将配置 Playwright 为调试模式并打开 Inspector。使用 --debug 时，会配置一些有用的默认设置：

浏览器以有头模式启动
默认超时设置为 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() 处暂停。

实时编辑定位器

在调试模式下运行时，你可以实时编辑定位器。在 "Pick Locator" 按钮旁边有一个字段，显示当前暂停的定位器。你可以直接在 "Pick Locator" 字段中编辑这个定位器，匹配的元素将在浏览器窗口中高亮显示。

选择定位器

在调试时，你可能需要选择一个更具韧性的定位器。你可以通过点击 “Pick Locator” 按钮并在浏览器窗口中悬停在任何元素上来完成此操作。当你将鼠标悬停在一个元素上时，下面会高亮显示需要定位该元素的代码。点击浏览器中的元素将把定位器添加到字段中，你可以对其进行调整或将其复制到代码中。

Playwright 会查看你的页面，并找出最佳的定位器，优先考虑角色、文本和测试 ID 定位器。如果 Playwright 找到多个匹配该定位器的元素，它会改进该定位器，使其更具韧性，唯一地标识目标元素，从而避免因定位器问题导致测试失败。

可操作性日志

在 Playwright 暂停点击操作时，它已经执行了可操作性检查，日志中可以找到这些检查。这有助于你了解测试中发生了什么，以及 Playwright 做了什么或尝试做什么。日志会告诉你元素是否可见、是否启用、是否稳定，定位器是否解析为元素、是否滚动到视图中，等等。如果无法访问元素，它将显示操作为挂起状态。

Trace Viewer

Playwright Trace Viewer 是一个 GUI 工具，帮助您查看 Playwright 测试的执行过程。您可以回放每个操作，看到执行时的 DOM 快照、时间、参数、返回值、日志等信息，并能查看控制台消息、网络请求和源代码。

要了解如何记录 trace 并使用 Trace Viewer，请参阅 Trace Viewer 指南。

浏览器开发者工具

当使用调试模式并设置 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 脚本的进一步执行，并会重置预配置的用户代理和设备模拟。

有头模式

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

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

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