调试测试

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

设置 PWDEBUG 环境变量以在调试模式下运行你的 Playwright 测试。这将配置 Playwright 进行调试并打开检查器。设置 PWDEBUG=1 后，会配置其他有用的默认值：

¥Set the PWDEBUG environment variable to run your Playwright tests in debug mode. This configures Playwright for debugging and opens the inspector. Additional useful defaults are configured when PWDEBUG=1 is set:

• 浏览器以 head 模式启动

  ¥Browsers launch in headed mode

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

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

Bash

PWDEBUG=1 dotnet test

PowerShell

$env:PWDEBUG=1
dotnet test

Batch

set PWDEBUG=1
dotnet test

逐步完成你的测试

¥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.PauseAsync() 方法添加到测试中。这样你就不必单步执行测试的每个操作即可到达你想要调试的位置。

¥To speed up the debugging process you can add a Page.PauseAsync() 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.PauseAsync();

添加 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.PauseAsync() 方法暂停执行。

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

await page.PauseAsync();

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

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

Bash

PWDEBUG=console dotnet test

PowerShell

$env:PWDEBUG=console
dotnet test

Batch

set PWDEBUG=console
dotnet 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 dotnet run

PowerShell

$env:DEBUG="pw:api"
dotnet run

Batch

set DEBUG=pw:api
dotnet run

注意

对于 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 using var browser = await playwright.Chromium.LaunchAsync(new()
{
    Headless = false,
    SlowMo = 100
});