调试测试
Playwright Inspector
Playwright Inspector 是一个 GUI 工具,可帮助您调试 Playwright 测试。它允许您逐步执行测试、实时编辑定位符、选取定位符并查看操作可行性日志。

在调试模式下运行
设置 PWDEBUG
环境变量以在调试模式下运行 Playwright 测试。这会将 Playwright 配置为进行调试并打开 Inspector。当设置 PWDEBUG=1
时,还会配置其他有用的默认值
- 浏览器以有头模式启动
- 默认超时设置为 0(= 无超时)
配置源位置
要告诉 Playwright 在何处查找您正在调试的源代码,请通过 PLAYWRIGHT_JAVA_SRC
环境变量传递源目录列表。列表中的路径在 macOS 和 Linux 上应以 : 分隔,在 Windows 上应以 ; 分隔。
- Bash
- PowerShell
- Batch
# Source directories in the list are separated by : on macos and linux and by ; on win.
PWDEBUG=1 PLAYWRIGHT_JAVA_SRC=<java source dirs> mvn test
# Source directories in the list are separated by : on macos and linux and by ; on win.
$env:PLAYWRIGHT_JAVA_SRC="<java source dirs>"
$env:PWDEBUG=1
mvn test
# Source directories in the list are separated by : on macos and linux and by ; on win.
set PLAYWRIGHT_JAVA_SRC=<java source dirs>
set PWDEBUG=1
mvn test
逐步执行测试
您可以使用 Inspector 顶部的工具栏播放、暂停或逐步执行测试中的每个操作。您可以看到测试代码中当前操作的高亮显示,以及浏览器窗口中匹配元素的高亮显示。

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

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

选取定位符
在调试时,您可能需要选择一个更稳定的定位符。您可以通过单击选取定位符按钮并悬停在浏览器窗口中的任何元素上来做到这一点。当悬停在元素上时,您将在下方看到定位该元素所需的代码被高亮显示。单击浏览器中的元素会将定位符添加到字段中,然后您可以在此处对其进行调整或复制到您的代码中。

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

跟踪查看器
Playwright 跟踪查看器是一个 GUI 工具,可让您探索录制的 Playwright 测试跟踪记录。您可以在左侧逐个操作地前进或后退,并在视觉上看到操作期间发生的情况。在屏幕中间,您可以看到操作的 DOM 快照。在右侧,您可以看到操作详情,例如时间、参数、返回值和日志。您还可以探索控制台消息、网络请求和源代码。
要了解如何录制跟踪记录和使用跟踪查看器,请查阅跟踪查看器指南。
浏览器开发者工具
在 Debug Mode 中使用 PWDEBUG=console
运行时,开发者工具控制台中会有一个 playwright
对象可用。开发者工具可以帮助您:
- 检查 DOM 树并查找元素选择器
- 查看执行期间的控制台日志(或学习如何通过 API 读取日志)
- 检查网络活动和其他开发者工具功能
这也会将 Playwright 的默认超时设置为 0(= 无超时)。

要使用浏览器开发者工具调试测试,首先在测试中设置一个断点,使用 Page.pause() 方法暂停执行。
page.pause();
在测试中设置断点后,您可以使用 PWDEBUG=console
运行测试。
- Bash
- PowerShell
- Batch
# Source directories in the list are separated by : on macos and linux and by ; on win.
PWDEBUG=console PLAYWRIGHT_JAVA_SRC=<java source dirs> mvn test
# Source directories in the list are separated by : on macos and linux and by ; on win.
$env:PLAYWRIGHT_JAVA_SRC="<java source dirs>"
$env:PWDEBUG=console
mvn test
# Source directories in the list are separated by : on macos and linux and by ; on win.
set PLAYWRIGHT_JAVA_SRC=<java source dirs>
set PWDEBUG=console
mvn 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)
在元素面板中显示元素。
playwright.inspect('text=Log in')
playwright.locator(selector)
创建定位符并查询匹配的元素,例如:
playwright.locator('.auth-form', { hasText: 'Log in' });
Locator ()
- element: button
- elements: [button]
playwright.selector(element)
为给定元素生成选择器。例如,在元素面板中选择一个元素并传递 $0
playwright.selector($0)
"div[id="glow-ingress-block"] >> text=/.*Hello.*/"
详细 API 日志
Playwright 支持使用 DEBUG
环境变量进行详细日志记录。
- Bash
- PowerShell
- Batch
DEBUG=pw:api mvn test
$env:DEBUG="pw:api"
mvn test
set DEBUG=pw:api
mvn test
对于 WebKit:在执行期间启动 WebKit Inspector 会阻止 Playwright 脚本进一步执行,并且会重置预配置的用户代理和设备模拟设置。
有头模式
Playwright 默认在无头模式下运行浏览器。要更改此行为,请使用 headless: false
作为启动选项。
您还可以使用 setSlowMo 选项来减慢执行速度(每项操作减慢 N 毫秒),并在调试时跟随查看。
// Chromium, Firefox, or WebKit
chromium.launch(new BrowserType.LaunchOptions()
.setHeadless(false)
.setSlowMo(100));