用途:本技能用于 Sandbox SDK 项目的测试约定,帮助决定写单元测试还是端到端(E2E)测试,并了解测试文件位置、mock 模式与命令。TDD 方法论请使用 superpowers:test-driven-development 技能。
单元测试:适用于隔离逻辑、客户端行为、服务方法、工具函数。SDK 测试位于 packages/sandbox/tests/,通过 @cloudflare/vitest-pool-workers 在 Workers 运行时运行;容器测试位于 packages/sandbox-container/tests/,在 Bun 运行时运行。命令:npm test(全部单元测试)、npm test -w @cloudflare/sandbox(仅 SDK)、npm test -w @repo/sandbox-container(仅容器)。mock 方面:SDK 测试使用 mock 容器,无需 Docker;容器测试 mock 文件系统、进程等外部依赖;日志 mock 使用 @repo/shared 的 createNoOpLogger()。已知问题:SDK 单元测试退出时可能因 vitest-pool-workers 的 workerd 关闭而挂起,但测试结果仍正确,属表面问题。
E2E 测试:适用于完整请求流程、容器集成、真实 Docker 行为。位于 tests/e2e/,运行在真实 Cloudflare Workers 与 Docker 容器上。命令:npm run test:e2e(全部 E2E,vitest 加浏览器)、npm run test:e2e:vitest -- -- tests/e2e/process-lifecycle-workflow.test.ts(单个 vitest 文件)、npm run test:e2e:vitest -- -- tests/e2e/git-clone-workflow.test.ts -t 'test name'(单个用例)、npm run test:e2e:browser(仅 Playwright 浏览器测试)。注意过滤测试时用 test:e2e:vitest,test:e2e 包装器不支持参数透传。关键模式:所有测试共享一个容器以提升性能;用唯一 session 隔离测试;测试通过线程池并行;配置为根目录 vitest.e2e.config.ts。E2E 测试用 helpers 的 createTestSession() 获取唯一 session,再调用 session.sandbox.exec() 执行命令。
选择依据:客户端方法逻辑、服务业务逻辑、请求/响应处理用单元测试;完整命令执行流程、真实文件系统文件操作、进程生命周期(启动、停止、信号)、端口暴露与预览 URL、Git 操作用 E2E。
约定:单元与 E2E 文件命名均为 *.test.ts;结构为 describe('ComponentName') 内嵌 describe('methodName') 与 it('should do X when Y'),按 Arrange/Act/Assert 编写;断言使用 vitest 的 expect()。开发中建议顺序:npm run check 先查类型错误,npm test 验证单元测试,改动核心功能时再 npm run test:e2e。monorepo 构建系统自动处理依赖,E2E 始终针对最新构建代码运行,无需手动重建。