testing

Sandbox SDK 中的测试

此技能介绍项目特定的测试约定。有关 TDD 方法，请使用 superpowers:test-driven-development 技能。

两套测试

单元测试

适用场景：测试独立逻辑、客户端行为、服务方法和工具。

位置：

• SDK：packages/sandbox/tests/
• 容器：packages/sandbox-container/tests/

运行时：

• SDK 测试通过 @cloudflare/vitest-pool-workers 在 Workers 运行时中运行
• 容器测试在 Bun 运行时中运行

命令：

npm test                              # All unit tests
npm test -w @cloudflare/sandbox       # SDK tests only
npm test -w @repo/sandbox-container   # Container tests only

模拟模式：

• SDK 测试使用模拟容器（无需 Docker）
• 容器测试模拟外部依赖项（文件系统、进程）
• 使用 @repo/shared 中的 createNoOpLogger() 模拟日志记录器

已知问题：由于 vitest-pool-workers 关闭 workerd 时的问题，SDK 单元测试在退出时可能会卡住。测试仍会正确通过或失败；卡住只是表面现象。

端到端测试

适用场景：测试完整请求流程、容器集成和真实 Docker 行为。

位置：tests/e2e/

运行时：真实的 Cloudflare Workers + Docker 容器

命令：

npm run test:e2e                                                           # All E2E tests (vitest + browser)
npm run test:e2e:vitest -- -- tests/e2e/process-lifecycle-workflow.test.ts # Single vitest file
npm run test:e2e:vitest -- -- tests/e2e/git-clone-workflow.test.ts -t 'test name'  # Single vitest test
npm run test:e2e:browser                                                   # Browser tests only (Playwright)

注意：筛选测试时使用 test:e2e:vitest。test:e2e 包装命令不支持传递参数。

主要模式：

• 为提升性能，所有测试共用一个容器
• 使用唯一会话隔离测试
• 测试通过线程池并行运行
• 配置：vitest.e2e.config.ts（根目录）

编写端到端测试：

import { createTestSession } from './helpers';

describe('Feature X', () => {
  let session: TestSession;

  beforeEach(async () => {
    session = await createTestSession(); // Gets unique session
  });

  it('should do something', async () => {
    const result = await session.sandbox.exec('echo hello');
    expect(result.stdout).toBe('hello\n');
  });
});

如何选择

场景	测试类型
客户端方法逻辑	单元测试
服务业务逻辑	单元测试
请求/响应处理	单元测试
完整命令执行流程	端到端测试
使用真实文件系统进行文件操作	端到端测试
进程生命周期（启动、停止、发送信号）	端到端测试
端口暴露和预览 URL	端到端测试
Git 操作	端到端测试

测试专用约定

文件命名：单元测试和端到端测试均使用 *.test.ts

测试结构：

describe('ComponentName', () => {
  describe('methodName', () => {
    it('should do X when Y', async () => {
      // Arrange
      // Act
      // Assert
    });
  });
});

断言：使用 vitest 的 expect()，编写清晰、具体的断言

开发期间运行测试

完成任何有意义的代码更改后：

1. npm run check - 优先检查类型错误
2. npm test - 确认单元测试通过
3. npm run test:e2e - 修改核心功能时运行

建立信心：单体仓库的构建系统会自动处理依赖项。端到端测试始终针对最新构建的代码运行，无需手动重新构建。