如何测试VS Code扩展?拆解TaskSync的Vitest + vscode mock + Playwright E2E测试策略
如何测试VS Code扩展?拆解TaskSync的Vitest + vscode mock + Playwright E2E测试策略
VS Code 扩展测试难在三点:vscode 模块在 Node 环境中不存在、webview 前端是不带框架的纯 JS、远程访问服务需要真实浏览器验证。开源项目 TaskSync(一个 AI 提示词队列扩展)用 Vitest 单元测试 + vscode API mock + Playwright E2E 三层策略,实现了 387+ 个测试、约 98% 的覆盖率。这篇文章带你逐层拆解它是怎么做到的,并总结出一套可复用的扩展测试套路。
一、VS Code 扩展测试的三大痛点
| 痛点 | 说明 |
|---|---|
vscode 模块缺失 |
该模块只由扩展宿主进程运行时注入,import * as vscode from "vscode" 在 Node 里直接报错 |
| 纯 JS 前端无法直接导入 | webview-ui 是不依赖框架的原生 JS,测试运行器无法 import 它 |
| 真实服务难以验证 | 远程访问功能是一个 HTTP + WebSocket 服务器,需要真实浏览器走一遍登录流程 |
TaskSync 的答案是一棵测试金字塔:底层用 Vitest 覆盖绝大多数逻辑,顶层用 Playwright 只测最关键的端到端路径。
二、第一层:Vitest 单元测试 + vscode mock
2.1 核心技巧:用 alias 把 vscode 指向本地 mock
整个策略的基石在 vitest.config.ts 里,只有几行配置:
alias: {
vscode: new URL("./src/__mocks__/vscode.ts", import.meta.url).pathname,
},
效果是:测试中任何 import * as vscode from "vscode" 都会被 Vitest 透明替换为本地 mock 文件,源码一行都不用改。这就是测试"依赖平台 API 的代码"的通用解法——alias 重定向。
2.2 Mock 原则:最小化,只 mock 真正用到的 API
Mock 文件 src/__mocks__/vscode.ts 只有 70 多行,刻意只覆盖被测代码实际调用的 API 面:
Uri.file/Uri.parse:返回带fsPath的简易对象workspace.getConfiguration:配置读写全部返回空操作workspace.workspaceFolders:一个真实可变数组(这是关键设计)window.showXxxMessage、commands.executeCommand:静默返回
其中 workspaceFolders 设计成可动态赋值的真实数组,意味着测试可以在每个用例里模拟"单根 / 多根工作区"等不同环境——mock 不是死数据,而是可控的测试夹具。
2.3 典型用例:工作区路径校验
看 gitService.test.ts,它测试远程文件路径是否合法(防路径穿越的安全逻辑):
(vscode.workspace as any).workspaceFolders = [
{ uri: { fsPath: "/workspace/root-a" } },
{ uri: { fsPath: "/workspace/root-b" } },
];
expect(isValidFilePath("/workspace/root-b/src/app.ts")).toBe(true);
测试手法很清晰:beforeEach 中布置 mock 状态,用例中断言行为,afterEach 中重置状态。同一文件还覆盖了 shell 元字符注入、空路径、Windows 反斜杠路径等边缘场景——这正是 AGENTS.md Testing 章节的要求:"对安全敏感代码、边缘情况、错误处理路径补充测试"。
2.4 纯函数测试:零依赖
最底层的工具函数连 mock 都不需要,例如 generateId.test.ts 验证 ID 的 前缀_时间戳_随机串 格式、50 次调用无重复、空前缀等边界。这类测试占比大、执行极快,是覆盖率的基石。
三、第二层:测试不带框架的 webview 前端
TaskSync 的 webview 前端(src/webview-ui/)是原生 JS,没有构建入口,Node 测试运行器无法直接导入。它用了一个巧妙的"注入式"手法,见 rendering.test.ts 与 adapter.test.ts:
- 用 Node 内置
vm模块或new Function加载 JS 文件的源码文本; - 把
document、localStorage、acquireVsCodeApi、计时器等全部依赖作为参数注入——其中 DOM 元素用FakeElement/FakeClassList假对象替代,副作用用vi.fn()记录; - 在隔离上下文中执行,断言"DOM 被怎样修改"。
没有 jsdom、没有无头浏览器,纯逻辑层面的 UI 代码照样能测——这个思路对任何"原生 JS 前端"项目都适用。
四、第三层:Playwright E2E 真实浏览器冒烟测试
4.1 E2E 测什么:远程访问服务
TaskSync 内置"远程访问"功能:在 VS Code 中启动服务器(默认端口 3580)后,可用浏览器/手机操作会话。E2E 用例 e2e/tests/remote-auth.spec.mjs 只聚焦一条最重要的链路——登录与鉴权:
- 页面渲染:访问
/,标题匹配TaskSync Remote,PIN 输入框与提交按钮可见; - API 鉴权:开启 PIN 模式时请求
/api/files应返回 401/429,关闭时应返回 200; - 登录流程:填入 PIN 提交后,15 秒内跳转到
/app.html且页头显示 TaskSync。
注意一个聪明设计:PIN 登录用例依赖环境变量 TASKSYNC_E2E_PIN,未设置时自动 test.skip() 而不是失败——同一份用例既能跑在本地(设置 PIN 后全量执行),也能跑在 CI(自动跳过),永不破坏流水线。
4.2 配置亮点
e2e/playwright.config.mjs 值得抄作业的配置:
baseURL默认http://127.0.0.1:3580,可用TASKSYNC_E2E_BASE_URL覆盖;- 仅配置 Chromium(Desktop Chrome)一个浏览器项目,E2E 不必全量矩阵;
- CI 环境自动重试 2 次,抵御网络抖动;
trace/screenshot/video均设为 retain-on-failure:平时零开销,失败时留下完整证据链,排障一眼定位。
4.3 运行方式
前提:在 VS Code 中启动 TaskSync 的远程服务器(命令面板执行 TaskSync: Start Remote Access (LAN)),然后:
npm run e2e:install # 首次:安装 Chromium
npm run e2e # 无头运行
npm run e2e:headed # 有头模式,实时观察浏览器
npm run e2e:ui # 交互式调试 UI
五、一键全量验证:npm run validate
所有测试串在一条命令里,见 package.json 的 scripts:
build → tsc --noEmit → vitest run → biome lint → 代码质量扫描
AGENTS.md 明确要求每次改动后运行 npm run validate——构建、类型、单测、Lint、重复代码检测一次跑完。日常开发用 npm run test(单次)或 npm run test:watch(监听)即可。
六、总结:5 个可复用的扩展测试技巧
- alias 重定向平台模块:
vscode这类运行时注入的 API,用测试框架的 alias 指向本地 mock,源码零改动; - Mock 最小化:只 stub 被测代码真实调用的 API 面,避免"假 API"误导维护者;
- Mock 状态可控:把
workspaceFolders做成可变数组,让每个用例自由布置工作区环境; - 注入式测试原生 JS 前端:
vm+ 假 DOM +vi.fn(),无需 jsdom 和无头浏览器; - E2E 只测关键链路:登录鉴权一条链足矣;用环境变量做条件跳过、失败时保留 trace/截图/录像。
从 30 个测试文件到一条 npm run validate 命令,TaskSync 证明:VS Code 扩展的测试完全可以做到快(单测秒级)、稳(CI 自动跳过不稳定的真实环境用例)、全(单测 ~98% 覆盖 + 浏览器端到端兜底)。
