如何测试VS Code扩展?拆解TaskSync的Vitest + vscode mock + Playwright E2E测试策略

原创2026-11-13 11:09:111,832 阅读

如何测试VS Code扩展?拆解TaskSync的Vitest + vscode mock + Playwright E2E测试策略

VS Code 扩展测试难在三点:vscode 模块在 Node 环境中不存在、webview 前端是不带框架的纯 JS、远程访问服务需要真实浏览器验证。开源项目 TaskSync(一个 AI 提示词队列扩展)用 Vitest 单元测试 + vscode API mock + Playwright E2E 三层策略,实现了 387+ 个测试、约 98% 的覆盖率。这篇文章带你逐层拆解它是怎么做到的,并总结出一套可复用的扩展测试套路。

TaskSync VS Code扩展测试项目Logo

一、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:

  1. 用 Node 内置 vm 模块或 new Function 加载 JS 文件的源码文本;
  2. 把 document、localStorage、acquireVsCodeApi、计时器等全部依赖作为参数注入——其中 DOM 元素用 FakeElement / FakeClassList 假对象替代,副作用用 vi.fn() 记录;
  3. 在隔离上下文中执行,断言"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 个可复用的扩展测试技巧

  1. alias 重定向平台模块:vscode 这类运行时注入的 API,用测试框架的 alias 指向本地 mock,源码零改动;
  2. Mock 最小化:只 stub 被测代码真实调用的 API 面,避免"假 API"误导维护者;
  3. Mock 状态可控:把 workspaceFolders 做成可变数组,让每个用例自由布置工作区环境;
  4. 注入式测试原生 JS 前端:vm + 假 DOM + vi.fn(),无需 jsdom 和无头浏览器;
  5. E2E 只测关键链路:登录鉴权一条链足矣;用环境变量做条件跳过、失败时保留 trace/截图/录像。

从 30 个测试文件到一条 npm run validate 命令,TaskSync 证明:VS Code 扩展的测试完全可以做到快(单测秒级)、稳(CI 自动跳过不稳定的真实环境用例)、全(单测 ~98% 覆盖 + 浏览器端到端兜底)。

登录后查看全文
TaskSync