如何配置VSCode实现Playwright端到端自动化测试的调试环境？

本文共计821个文字，预计阅读时间需要4分钟。

Playwright官方插件本身不带调试器，需要手动配置`launch.json`才能在VS Code中按F5单步调试测试文件。

为什么直接点“运行”不进断点？

VS Code 的 Playwright Test for VSCode 插件默认只支持“运行测试”和“查看报告”，debug 功能是独立路径：它不走插件内置的 test runner，而是靠 Node.js 调试器启动 playwright CLI 进程。没配 launch.json，F5 就只是启动普通 Node 进程，根本不会加载 Playwright 的上下文。

• 常见错误现象：F5 后终端报错 Cannot find module '@playwright/test' 或直接卡住无反应
• 根本原因：VS Code 没指定用哪个可执行文件启动、没传 test 子命令、也没告诉它跑哪个浏览器项目
• 关键依赖：必须确保项目已安装 @playwright/test（不是只装 playwright），且 node_modules/.bin/playwright 存在

怎么写有效的 launch.json 配置？

在项目根目录下创建 .vscode/launch.json，内容必须匹配你本地的 Playwright CLI 路径和项目结构：

{ "version": "0.2.0", "configurations": [ { "name": "Debug Playwright Test", "type": "node", "request": "launch", "program": "${workspaceFolder}/node_modules/.bin/playwright", "args": ["test", "--project=chromium", "--headed", "${fileBasename}"], "console": "integratedTerminal", "internalConsoleOptions": "neverOpen", "skipFiles": ["<node_internals>/**"] } ] }

• ${fileBasename} 是关键：它让调试器自动取当前打开的 .spec.ts 文件名，避免每次手动改参数
• --project=chromium 要和 playwright.config.ts 里定义的 project 名一致（比如你配了 firefox，这里就得写 --project=firefox）
• 如果项目用了 TypeScript，务必确认 ts-node 已安装且 playwright.config.ts 能被正确解析；否则换用 playwright.config.js 更稳
• Windows 用户若用 Git Bash，program 路径要改成 "${workspaceFolder}/node_modules/.bin/playwright.cmd"

断点能停住，但变量看不到？

Playwright 测试运行在 worker 进程里，VS Code 默认不 attach 到子进程，所以即使断点命中，page、browser 等对象在调试面板里显示为 undefined 或 [Object]。

• 解决办法：在 launch.json 的 args 里加 --debug（Playwright v1.40+ 支持），例如：["test", "--debug", "--project=chromium", "${fileBasename}"]
• 或者改用 playwright test --debug 命令手动启动，再用 VS Code 的 “Attach to Process” 功能连上那个 node 进程（进程名含 playwright-test）
• 别依赖 hover 查 DOM 元素：Playwright 的 Locator 是惰性对象，hover 只能看到封装结构，真要看实际 DOM 必须用 await page.screenshot() 或开 trace

最易忽略的一点：launch.json 配好后，必须用“运行 → 启动调试”或快捷键 F5，而不是点测试文件旁的绿色 ▶ 按钮——后者走的是插件自己的 runner，永远不触发断点。