Playwright VS Code 扩展入门：在编辑器内运行、调试与自动生成端到端测试

Playwright 官方 VS Code 扩展把 Playwright Test 的运行、调试与测试生成能力直接带入编辑器，让你无需切换到终端即可完成端到端测试的日常开发循环。本文基于官方文档 VS Code 入门指南 展开，覆盖从扩展安装、浏览器初始化，到测试运行、断点调试、Trace Viewer 分析，再到 CodeGen 录制生成测试的完整工作流，并结合仓库中的示例配置与源码结构补充每个功能背后的实现细节。读完本文，你可以在 VS Code 中独立完成一个 Playwright 测试项目的搭建，并掌握跨浏览器运行、实时调试与失败分析的实战方法。

前置条件与安装初始化

开始之前，确保环境中已具备：

• Node.js（推荐 LTS 版本）
• Visual Studio Code

安装扩展与 Playwright

整个初始化流程分为三步：

1. 安装扩展：在 VS Code 中打开扩展视图（Ctrl+Shift+X 或 Cmd+Shift+X），搜索 "Playwright"，安装微软官方发布的 Playwright 扩展。

   

2. 安装 Playwright：扩展装好之后，打开命令面板（Ctrl+Shift+P 或 Cmd+Shift+P），执行 Test: Install Playwright 命令，扩展会引导你在当前项目中完成依赖与浏览器安装。

   

3. 选择浏览器：按提示选择要安装的浏览器（Chromium、Firefox、WebKit），还可以选择附加一个 GitHub Actions 工作流，把测试接入 CI。这些选择最终都会落到 playwright.config.ts 中，之后可以随时修改。

   

生成的配置长什么样

初始化生成的 playwright.config.ts 决定了测试目录、超时、重试、报告器与项目（projects）列表。仓库内的示例配置 examples/todomvc/playwright.config.ts 给出了一个典型的完整形态，几个与 VS Code 体验直接相关的字段值得注意：

• testDir: './tests'：Test Explorer 会扫描该目录来发现测试；
• trace: 'on-first-retry'：首次重试失败时收集 trace，正是后文 Trace Viewer 调试能力的数据来源；
• retries: process.env.CI ? 2 : 0、workers: process.env.CI ? 1 : undefined：本地与 CI 行为区分；
• projects 数组：每个项目通常对应一个浏览器（如 chromium 配合 devices['Desktop Chrome']），VS Code 侧边栏中的多浏览器运行就是围绕这些项目工作的：

projects: [
  {
    name: 'chromium',
    use: { ...devices['Desktop Chrome'] },
  },
  // { name: 'firefox', use: { ...devices['Desktop Firefox'] } },
  // { name: 'webkit',  use: { ...devices['Desktop Safari'] } },
],

打开 Testing 侧边栏

点击 VS Code 活动栏中的 Testing 图标即可打开 Test Explorer。在这里既能看到已发现的测试，也能看到 Playwright 专属侧边栏，用于管理项目（projects）、工具与设置：

运行测试

单条与批量运行

• 运行单条测试：点击测试旁边的绿色 "play" 图标。测试通过时图标变为绿色对勾，失败时变为红色叉号，测试名旁会显示耗时；同时底部的 Test Results 面板会自动打开，汇总本次执行的通过/失败/跳过数量与总耗时。
• 运行全部测试：在文件级点击 play 图标可运行该文件内所有测试；点击 Test Explorer 顶部的 play 图标则运行整个项目的所有测试。

多浏览器（多项目）运行

在 Playwright 侧边栏中勾选要执行的项目（browsers）。从源码结构看，一个 project 就是一套独立的浏览器配置——可以指定具体浏览器、viewport、设备模拟或其他浏览器专属选项。勾选多个项目后，一次运行会把同一批测试分发到所有选中的项目上执行，用于验证应用在不同浏览器与配置下行为一致。

Show Browser：有头与无头模式

在侧边栏中开启 Show Browser，测试执行时会打开一个可见的浏览器窗口，便于观察实际操作过程；关闭该选项则以 headless 模式在后台运行。

调试测试

VS Code 扩展提供了断点调试、实时高亮、错误信息展示、AI 修复建议与 Trace Viewer 等一整套调试能力。

断点调试

在行号左侧的沟槽处点击即可设置断点，然后右键测试选择 Debug Test：测试会在断点处暂停，你可以检查变量值、逐语句步进。

实时调试（Live Debugging）

在 Show Browsers 开启的状态下，点击代码中的任意 locator，Playwright 会在浏览器中高亮对应的页面元素，方便快速验证定位器是否命中目标。

错误信息查看

测试失败时，扩展会在编辑器中直接展示详细的错误信息，包括期望值与接收值（expected vs. received）以及完整的调用日志（call log）。

AI 辅助修复

测试失败后，点击错误旁边的 sparkle 图标，可获得 Copilot 给出的 AI 修复建议。Copilot 会分析错误原因并建议相应的代码修改。

Trace Viewer：逐步执行回放

在 Playwright 侧边栏中开启 Show Trace Viewer 后，测试结束会自动打开 trace 详情页面，提供一次完整执行的回放时间线。结合上文配置中 trace: 'on-first-retry' 这类采集策略，trace 在以下场景尤为有用：

• 逐步分析：按精确时间戳浏览测试执行的每一步操作；
• DOM 检查：查看任意时间点的 DOM 快照，还原页面当时的真实结构；
• 网络监控：检查测试期间发生的所有网络请求与响应；
• 控制台日志：访问浏览器中的所有 console 消息与报错；
• 源码映射：从每一步操作直接跳转到执行该操作的源代码位置；
• 可视化调试：查看每步的截图，理解用户当时"看到"了什么。

对于排查 flaky test（不稳定测试）和理解复杂用户交互，Trace Viewer 是最有效的工具之一。

更多用法可参考 Trace Viewer 指南。

使用 CodeGen 生成测试

CodeGen 是 Playwright 的测试生成工具：你只需在浏览器里操作页面，它就能把交互过程自动转换为带有可靠 locator 与断言的测试代码，而不是从零手写。

• Record new：点击侧边栏中的 Record new，会打开一个浏览器窗口；你与页面交互的同时，Playwright 自动生成测试代码，还可以从录制工具栏直接生成断言；
• Record at cursor：把光标放在已有测试的某一行，点击 Record at cursor，录制的新操作会追加到该位置，适合增量补充用例；
• Pick locator：使用 Pick locator 工具点击浏览器中的任意元素，Playwright 会挑选最佳 locator 并复制到剪贴板，直接粘贴进代码即可。

从源码结构看，各语言测试代码的生成逻辑位于 packages/isomorphic/codegen 下，按语言拆分为 javascript.ts、python.ts、csharp.ts、java.ts 等模块，VS Code 侧边栏里的 Record 与 Pick locator 最终就是驱动这套生成器在工作。更多用法见 CodeGen 指南。

进阶功能

项目依赖（Project Dependencies）

利用 project dependencies 可以定义先于其他测试执行的 setup 测试。例如先运行一个登录测试，再把认证状态复用给多个后续测试，避免每条用例重复登录。在 VS Code 中，这些 setup 测试会出现在 Test Explorer 里，可以单独运行。

全局设置（Global Setup）

对于只需在所有测试开始前执行一次的任务（如初始化数据库数据），使用 Global Setup。Playwright 侧边栏支持手动触发 global setup 与 teardown。

多配置文件切换

当项目中存在多个 playwright.config.ts 时，可以用 Playwright 侧边栏中的齿轮图标在它们之间切换，便于在不同测试套件或环境之间快速切换工作。

快速参考

操作	VS Code 中的做法
安装 Playwright	命令面板 → Test: Install Playwright
运行测试	点击测试旁的 play 图标
调试测试	设置断点，右键测试 → Debug Test
显示实时浏览器	在 Playwright 侧边栏启用 Show Browsers
录制新测试	点击 Playwright 侧边栏的 Record new
拾取 locator	点击 Playwright 侧边栏的 Pick locator
查看测试 trace	在 Playwright 侧边栏启用 Show Trace Viewer

下一步

• 使用 web-first 断言、page fixture 与 locator 编写测试：Writing Tests
• 在 CI 中运行测试：CI 入门
• 深入了解 Trace Viewer：Trace Viewer 指南