在 Snowpack 项目中使用 @snowpack/web-test-runner-plugin 进行免打包测试

• 前端
• 开发工具
• 前端构建

@snowpack/web-test-runner-plugin是 Snowpack 官方提供的 @web/test-runner 为主线，结合仓库内模板与源码，说明如何安装配置该插件、理解其内部工作机制，以及如何让它与snowpack.config.mjs正确协作。

为什么需要它：复用 Snowpack 管线，而不是第二套构建

Snowpack 官方在 docs/guides/testing.md 中明确将 @web/test-runner 推荐为 Snowpack 项目的测试运行器，并解释了理由：WTR 运行的是与你的项目完全相同的 Snowpack 构建管线，因此不需要为测试维护第二套构建配置。这既能提升测试对生产代码的置信度，也能省去成百上千个额外的构建依赖。

插件在此处的角色是"接线员"：它自动连接当前目录下的 Snowpack 项目、加载项目配置，然后复用你已经配置好的 Snowpack 构建管线来构建每个测试文件。你不需要在snowpack.config.mjs中为测试单独声明任何东西，测试文件的加载、导入重写、依赖安装全部由既有管线完成。

官方文档同时提醒（见 docs/guides/web-test-runner.md）：不要把该插件加进snowpack.config.mjs的plugins数组——它只应该出现在web-test-runner.config.js中。

安装与最小配置

1. 安装依赖

基础测试依赖为 @web/test-runner、本插件与断言库 chai：

npm install --save-dev @web/test-runner @snowpack/web-test-runner-plugin chai

若使用 React、Vue、Svelte 或 Preact，再按框架追加对应的 Testing Library（例如@testing-library/react）；若使用 TypeScript，则追加@types/mocha与@types/chai。

从 plugins/web-test-runner-plugin/package.json 可以看到插件声明了对等依赖：@web/test-runner >= 0.10.0 < 1.0.0、snowpack ^3.8.0，版本不满足时请先升级。

2. 创建配置文件

在项目根目录创建web-test-runner.config.js，内容如下（官方指南建议先设置NODE_ENV = 'test'，其作用见下文"test 模式"一节）：

process.env.NODE_ENV = 'test'; module.exports = { plugins: [require('@snowpack/web-test-runner-plugin')()], };

这是该插件公开的全部配置入口：Options一节明确写道 "None!"（没有选项）。如果你需要调整 Snowpack 行为，应直接修改项目的snowpack.config.mjs；如需为测试指定文件匹配规则，可配置 docs/reference/configuration.md 中的testOptions.files（默认值为["__tests__/**/*", "**/*.@(spec|test).*"]，仅当NODE_ENV为test时才将这些文件纳入站点构建并扫描可安装依赖）。仓库中的模板项目均采用了上述同一份配置，例如 create-snowpack-app/app-template-react/web-test-runner.config.js 与 create-snowpack-app/app-template-preact/web-test-runner.config.js。

3. 添加 test 脚本

在package.json的scripts中添加 test 脚本，例如：

"scripts": { "start": "snowpack dev", "build": "snowpack build", "test": "web-test-runner \"src/**/*.test.jsx\"" }

• 按需将.jsx换成你的测试文件类型；
• 匹配多种类型时用花括号加逗号："web-test-runner \"src/**/*.test.{jsx,js,ts}\""；
• wtr可作为web-test-runner的简写。

实际模板 create-snowpack-app/app-template-react/package.json 中即使用了"test": "web-test-runner \"src/**/*.test.jsx\""，配套测试样例可参考 create-snowpack-app/app-template-react/src/App.test.jsx（基于@testing-library/react渲染组件，并用 chai 的expect断言）。

插件内部工作机制（源码解读）

插件主体位于 plugins/web-test-runner-plugin/plugin.js，核心逻辑围绕 WTR 生命周期钩子展开：

serverStart：以 test 模式启动 Snowpack

async serverStart({fileWatcher}) { config = await snowpack.loadConfiguration({ mode: 'test', packageOptions: {external: ['/__web-dev-server__web-socket.js']}, devOptions: {open: 'none', output: 'stream', hmr: false}, }); fileWatcher.add(Object.keys(config.mount)); server = await snowpack.startServer({config, lockfile: null}); }

关键点：

• mode: 'test'：Snowpack 配置中mode的合法取值为['test', 'development', 'production']（见 snowpack/src/config.ts）。在test模式下，testOptions.files指定的测试文件不会被排除，而是作为普通源码被扫描、构建，从而支持运行"构建在 Snowpack 之上"的测试（docs/reference/configuration.md）。
• packageOptions.external将 WTR 自身使用的虚拟 socket 文件排除出依赖安装流程，避免它被当作 npm 包处理。
• devOptions关闭浏览器自动打开（open: 'none'）、以stream方式输出日志、并禁用 HMR——测试运行期不需要热更新。
• fileWatcher.add(Object.keys(config.mount))：把配置中所有 mount 目录注册进 WTR 的文件监听器，使源码变更能触发测试重新运行。
• 配置加载走snowpack.loadConfiguration（实现在 snowpack/src/config.ts），随后snowpack.startServer启动开发服务器（snowpack/src/commands/dev.ts）。由于是测试场景，lockfile显式传null，并在日志中提示"npm packages should be installed/prepared ahead of time"——即依赖应在测试前通过常规安装流程准备就绪。

serve：让 WTR 请求走 Snowpack 的加载管线

async serve({request}) { if (isTestRunnerFile(request.url)) return; const result = await server.loadUrl(reqPath, {isSSR: false}); return {body: result.contents, type: result.contentType}; }

isTestRunnerFile用于识别以/__web-dev-server或/__web-test-runner开头的虚拟文件（WTR 内部资源），这类请求不交给 Snowpack，直接放行；其余请求则调用 Snowpack 开发服务器的loadUrl加载并转换文件，把内容与 Content-Type 回传给 WTR。这正是"复用已配置的构建管线"的落点：测试文件与源码走同一条转换路径。

transformImport：把测试文件中的导入重写为 Snowpack 产出的 URL

transformImport({source}) { if (!isTestFilePath(source) || isTestRunnerFile(source)) return; const reqPath = source.substring(0, source.indexOf('?') === -1 ? undefined : source.indexOf('?')); const sourcePath = path.join(config.root || process.cwd(), reqPath); return snowpack.getUrlForFile(sourcePath, config); }

• 仅对测试文件（isTestFilePath判定）中的导入做重写，WTR 虚拟文件除外；
• 先剥离查询字符串（?之后的部分），再基于config.root（默认当前工作目录）拼出磁盘绝对路径；
• 最后调用snowpack.getUrlForFile（对外导出见 snowpack/src/index.ts）把源码路径转换为 Snowpack 生成的 URL，例如把./App.jsx映射到构建产物路径。无法解析的导入会原样保留，交由 WTR 或浏览器处理。

serverStop：优雅关闭

async serverStop() { return server.shutdown(); }

测试会话结束时调用 Snowpack 服务器的shutdown()，释放端口与进程资源。

使用限制与注意事项

• 插件没有配置选项。如果你需要为测试定制 Snowpack 行为，请直接编辑项目根目录的snowpack.config.mjs（例如通过testOptions调整测试文件匹配），无需也不能在插件调用处传参。
• 依赖需预先安装：插件启动时不会替你安装 npm 包，测试前请确保依赖已按常规方式安装就绪。
• 不要把它加入 snowpack.config.mjs 的 plugins：该插件仅在web-test-runner.config.js中注册（官方指南的明确提示，见 docs/guides/web-test-runner.md）。
• 前置版本要求：需满足 peerDependencies 的版本范围（@web/test-runner >= 0.10.0 < 1.0.0、snowpack ^3.8.0）。

小结

@snowpack/web-test-runner-plugin用约六十行代码把 WTR 与 Snowpack 无缝衔接：以test模式加载现有配置、启动开发服务器、接管文件加载与导入重写、并在退出时干净地关闭。对开发者而言，这意味着"写测试 = 写源码"，同一套构建管线、同一份snowpack.config.mjs，无需为测试搭建第二套工具链。官方推荐的 React/Preact/Svelte 等模板（见 create-snowpack-app 下各app-template-*项目的web-test-runner.config.js）都已内置该方案，可作为直接可用的参照起点。

• 前端
• 开发工具
• 前端构建