调试测试

VS Code 调试器

¥VS Code debugger

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

¥We recommend using the VS Code Extension for debugging for a better developer experience. With the VS Code extension you can debug your tests right in VS Code, see error messages, set breakpoints and step through your tests.

错误信息

¥Error Messages

如果你的测试失败，VS Code 将在编辑器中直接向你显示错误消息，显示预期的内容、收到的内容以及完整的调用日志。

¥If your test fails VS Code will show you error messages right in the editor showing what was expected, what was received as well as a complete call log.

实时调试

¥Live Debugging

你可以在 VS Code 中实时调试测试。在选中 Show Browser 选项的情况下运行测试后，单击 VS Code 中的任何定位器，它将在浏览器窗口中高亮。Playwright 还会告诉你是否有多个匹配项。

¥You can debug your test live in VS Code. After running a test with the Show Browser option checked, click on any of the locators in VS Code and it will be highlighted in the Browser window. Playwright will also show you if there are multiple matches.

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

¥You can also edit the locators in VS Code and Playwright will show you the changes live in the browser window.

选择定位器

¥Picking a Locator

选择 locator 并通过单击测试侧栏中的“选择定位器”按钮将其复制到测试文件中。然后在浏览器中单击你需要的元素，它现在将显示在 VS Code 的“选择定位器”框中。按键盘上的 'enter' 将定位器复制到剪贴板中，然后粘贴到代码中的任意位置。或者如果你想取消，请按 'escape'。

¥Pick a locator and copy it into your test file by clicking the Pick locator button form the testing sidebar. Then in the browser click the element you require and it will now show up in the Pick locator box in VS Code. Press 'enter' on your keyboard to copy the locator into the clipboard and then paste anywhere in your code. Or press 'escape' if you want to cancel.

Playwright 将查看你的页面并找出最佳定位器，优先考虑 角色、文本和测试 ID 定位器。如果 Playwright 找到多个与定位器匹配的元素，它将改进定位器，使其具有弹性并唯一标识目标元素，因此你不必担心由于定位器而导致测试失败。

¥Playwright will look at your page and figure out the best locator, prioritizing role, text and test id locators. If Playwright finds multiple elements matching the locator, it will improve the locator to make it resilient and uniquely identify the target element, so you don't have to worry about failing tests due to locators.

在调试模式下运行

¥Run in Debug Mode

要设置断点，请单击要设置断点的行号旁边，直到出现红点。右键单击要运行的测试旁边的行，以调试模式运行测试。

¥To set a breakpoint click next to the line number where you want the breakpoint to be until a red dot appears. Run the tests in debug mode by right clicking on the line next to the test you want to run.

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

¥A browser window will open and the test will run and pause at where the breakpoint is set. You can step through the tests, pause the test and rerun the tests from the menu in VS Code.

在不同浏览器中调试

¥Debug in different Browsers

默认情况下，调试是使用 Chromium 配置文件完成的。你可以通过右键单击测试侧栏中的调试图标并单击下拉列表中的 '选择默认配置文件' 选项，在不同的浏览器上调试测试。

¥By default debugging is done using the Chromium profile. You can debug your tests on different browsers by right clicking on the debug icon in the testing sidebar and clicking on the 'Select Default Profile' option from the dropdown.

然后选择你想要用于调试测试的测试配置文件。每次在调试模式下运行测试时，它将使用你选择的配置文件。你可以通过右键单击测试所在的行号并从菜单中选择 '调试测试' 在调试模式下运行测试。

¥Then choose the test profile you would like to use for debugging your tests. Each time you run your test in debug mode it will use the profile you selected. You can run tests in debug mode by right clicking the line number where your test is and selecting 'Debug Test' from the menu.

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

¥To learn more about debugging, see Debugging in Visual Studio Code.

Playwright 检查器

¥Playwright Inspector

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

¥The Playwright Inspector is a GUI tool to help you debug your Playwright tests. It allows you to step through your tests, live edit locators, pick locators and see actionability logs.

在调试模式下运行

¥Run in debug mode

使用 --debug 标志运行测试以打开检查器。这将配置 Playwright 进行调试并打开检查器。使用 --debug 时会配置其他有用的默认值：

¥Run your tests with the --debug flag to open the inspector. This configures Playwright for debugging and opens the inspector. Additional useful defaults are configured when --debug is used:

• 浏览器以 head 模式启动

  ¥Browsers launch in headed mode

• 默认超时设置为 0（= 无超时）

  ¥Default timeout is set to 0 (= no timeout)

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

¥Debug all tests on all browsers

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

¥To debug all tests run the test command with the --debug flag. This will run tests one by one, and open the inspector and a browser window for each test.

npx playwright test --debug

在所有浏览器上调试一项测试

¥Debug one test on all browsers

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

¥To debug one test on a specific line run the test command followed by the name of the test file and the line number of the test you want to debug, followed by the --debug flag. This will run a single test in each browser configured in your playwright.config and open the inspector.

npx playwright test example.spec.ts:10 --debug

在特定浏览器上调试

¥Debug on a specific browser

在 Playwright 中，你可以在 playwright.config 中配置项目。配置完成后，你可以使用 --project 标志后跟 playwright.config 中配置的项目名称在特定浏览器或移动视口上调试测试。

¥In Playwright you can configure projects in your playwright.config. Once configured you can then debug your tests on a specific browser or mobile viewport using the --project flag followed by the name of the project configured in your playwright.config.

npx playwright test --project=chromium --debug
npx playwright test --project="Mobile Safari" --debug
npx playwright test --project="Microsoft Edge" --debug

在特定浏览器上调试一项测试

¥Debug one test on a specific browser

要在特定浏览器上运行一个测试，请添加测试文件的名称和要调试的测试的行号以及 --project 标志，后跟项目名称。

¥To run one test on a specific browser add the name of the test file and the line number of the test you want to debug as well as the --project flag followed by the name of the project.

npx playwright test example.spec.ts:10 --project=webkit --debug

逐步完成你的测试

¥Stepping through your tests

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

¥You can play, pause or step through each action of your test using the toolbar at the top of the Inspector. You can see the current action highlighted in the test code, and matching elements highlighted in the browser window.

从特定断点运行测试

¥Run a test from a specific breakpoint

为了加快调试过程，你可以将 page.pause() 方法添加到测试中。这样你就不必单步执行测试的每个操作即可到达你想要调试的位置。

¥To speed up the debugging process you can add a page.pause() method to your test. This way you won't have to step through each action of your test to get to the point where you want to debug.

await page.pause();

添加 page.pause() 调用后，在调试模式下运行测试。单击 Inspector 中的 "恢复" 按钮将运行测试，并且仅在 page.pause() 上停止。

¥Once you add a page.pause() call, run your tests in debug mode. Clicking the "Resume" button in the Inspector will run the test and only stop on the page.pause().

实时编辑定位器

¥Live editing locators

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

¥While running in debug mode you can live edit the locators. Next to the 'Pick Locator' button there is a field showing the locator that the test is paused on. You can edit this locator directly in the Pick Locator field, and matching elements will be highlighted in the browser window.

拣选定位器

¥Picking locators

在调试时，你可能需要选择更具弹性的定位器。你可以通过单击“选择定位器”按钮并将鼠标悬停在浏览器窗口中的任何元素上来完成此操作。将鼠标悬停在某个元素上时，你将看到下面高亮的定位该元素所需的代码。单击浏览器中的某个元素会将定位器添加到字段中，然后你可以在其中调整它或将其复制到代码中。

¥While debugging you might need to choose a more resilient locator. You can do this by clicking on the Pick Locator button and hovering over any element in the browser window. While hovering over an element you will see the code needed to locate this element highlighted below. Clicking an element in the browser will add the locator into the field where you can then either tweak it or copy it into your code.

Playwright 将查看你的页面并找出最佳定位器，优先考虑 角色、文本和测试 ID 定位器。如果 Playwright 找到多个与定位器匹配的元素，它将改进定位器，使其具有弹性并唯一标识目标元素，因此你不必担心由于定位器而导致测试失败。

¥Playwright will look at your page and figure out the best locator, prioritizing role, text and test id locators. If Playwright finds multiple elements matching the locator, it will improve the locator to make it resilient and uniquely identify the target element, so you don't have to worry about failing tests due to locators.

可操作性日志

¥Actionability logs

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

¥By the time Playwright has paused on a click action, it has already performed actionability checks that can be found in the log. This can help you understand what happened during your test and what Playwright did or tried to do. The log tells you if the element was visible, enabled and stable, if the locator resolved to an element, scrolled into view, and so much more. If actionability can't be reached, it will show the action as pending.

跟踪查看器

¥Trace Viewer

Playwright 跟踪查看器 是一个 GUI 工具，可让你探索记录的 Playwright 测试痕迹。你可以在左侧向后和向前浏览每个动作，并直观地看到该动作期间发生的情况。在屏幕中间，你可以看到该操作的 DOM 快照。右侧可以看到操作的详细信息，例如时间、参数、返回值和日志。你还可以探索控制台消息、网络请求和源代码。

¥Playwright Trace Viewer is a GUI tool that lets you explore recorded Playwright traces of your tests. You can go back and forward through each action on the left side, and visually see what was happening during the action. In the middle of the screen, you can see a DOM snapshot for the action. On the right side you can see action details, such as time, parameters, return value and log. You can also explore console messages, network requests and the source code.

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

¥To learn more about how to record traces and use the Trace Viewer, check out the Trace Viewer guide.

浏览器开发者工具

¥Browser Developer Tools

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

¥When running in Debug Mode with PWDEBUG=console, a playwright object is available in the Developer tools console. Developer tools can help you to:

• 检查 DOM 树并查找元素选择器

  ¥Inspect the DOM tree and find element selectors

• 在执行期间查看控制台日志（或了解如何 通过 API 读取日志）

  ¥See console logs during execution (or learn how to read logs via API)

• 检查网络活动和其他开发者工具功能

  ¥Check network activity and other developer tools features

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

¥This will also set the default timeouts of Playwright to 0 (= no timeout).

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

¥To debug your tests using the browser developer tools start by setting a breakpoint in your test to pause the execution using the page.pause() method.

await page.pause();

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

¥Once you have set a breakpoint in your test you can then run your test with PWDEBUG=console.

Bash

PWDEBUG=console npx playwright test

PowerShell

$env:PWDEBUG="console"
npx playwright test

Batch

set PWDEBUG=console
npx playwright test

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

¥Once Playwright launches the browser window you can open the developer tools. The playwright object will be available in the console panel.

playwright.$(selector)

使用实际的 Playwright 查询引擎查询 Playwright 选择器，例如：

¥Query the Playwright selector, using the actual Playwright query engine, for example:

playwright.$('.auth-form >> text=Log in');

<button>Log in</button>

playwright.$$(selector)

与 playwright.$ 相同，但返回所有匹配元素。

¥Same as playwright.$, but returns all matching elements.

playwright.$$('li >> text=John')

[<li>, <li>, <li>, <li>]

playwright.inspect(selector)

在“元素”面板中显示元素。

¥Reveal element in the Elements panel.

playwright.inspect('text=Log in')

playwright.locator(selector)

创建定位器并查询匹配元素，例如：

¥Create a locator and query matching elements, for example:

playwright.locator('.auth-form', { hasText: 'Log in' });

Locator ()
  - element: button
  - elements: [button]

playwright.selector(element)

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

¥Generates selector for the given element. For example, select an element in the Elements panel and pass $0:

playwright.selector($0)

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

详细 API 日志

¥Verbose API logs

Playwright 支持使用 DEBUG 环境变量进行详细日志记录。

¥Playwright supports verbose logging with the DEBUG environment variable.

Bash

DEBUG=pw:api npx playwright test

PowerShell

$env:DEBUG="pw:api"
npx playwright test

Batch

set DEBUG=pw:api
npx playwright test

注意

对于 WebKit：在执行期间启动 WebKit Inspector 将阻止 Playwright 脚本进一步执行，并将重置预配置的用户代理和设备模拟。

¥For WebKit: launching WebKit Inspector during the execution will prevent the Playwright script from executing any further and will reset pre-configured user agent and device emulation.

有头模式

¥Headed mode

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

¥Playwright runs browsers in headless mode by default. To change this behavior, use headless: false as a launch option.

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

¥You can also use the slowMo option to slow down execution (by N milliseconds per operation) and follow along while debugging.

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