// Use when writing or running tests for this project. Covers unit vs E2E test decisions, test file locations, mock patterns, and project-specific testing conventions. (project)
Use when you need to exercise a real, running Sandbox deployment via HTTP — for example to validate SDK changes against a live container, reproduce a user-reported issue, or experiment with the API (including FUSE bucket mounts) without spinning up `wrangler dev`. Documents the Sandbox bridge worker reachable via `SANDBOX_WORKER_URL` + `SANDBOX_API_KEY` when the host injects them.
Use when creating a changeset, preparing a release, or bumping versions. Covers which packages to reference, how to write user-facing changeset descriptions, the release automation flow, and the npm/Docker version sync requirement. (project)
Use when navigating the codebase for the first time, adding a new client method, adding a new container handler/service, or understanding how a request flows from Worker through the Sandbox DO into the container. Covers the three-layer architecture, client pattern, container runtime structure, and monorepo layout. (project)
Use when writing or reviewing TypeScript in this repo. Covers the no-`any` rule and where to put new types, the uppercase-acronym style guide, and the rules for code comments (no historical context). (project)
Use when working in the examples/ directory, running an example with wrangler dev, adding a new example, or answering questions about EXPOSE directives and the local Docker dev loop. (project)
Use when adding logs, debugging, or working with the Logger across the SDK and container runtime. Covers the constructor-injection pattern, child loggers, env-var configuration, and test mocking. (project)
| name | testing |
| description | Use when writing or running tests for this project. Covers unit vs E2E test decisions, test file locations, mock patterns, and project-specific testing conventions. (project) |
This skill covers project-specific testing conventions. For TDD methodology, use the superpowers:test-driven-development skill.
When to use: Testing isolated logic, client behavior, service methods, utilities.
Location:
packages/sandbox/tests/packages/sandbox-container/tests/Runtime:
@cloudflare/vitest-pool-workersCommands:
npm test # All unit tests
npm test -w @cloudflare/sandbox # SDK tests only
npm test -w @repo/sandbox-container # Container tests only
Mock patterns:
createNoOpLogger() from @repo/shared for logger mocksKnown issue: SDK unit tests may hang on exit due to vitest-pool-workers workerd shutdown. Tests still pass/fail correctly - the hang is cosmetic.
When to use: Testing full request flow, container integration, real Docker behavior.
Location: tests/e2e/
Runtime: Real Cloudflare Workers + Docker containers
Commands:
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)
Note: Use test:e2e:vitest when filtering tests. The test:e2e wrapper doesn't support argument passthrough.
Key patterns:
vitest.e2e.config.ts (root level)Writing E2E tests:
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');
});
});
| Scenario | Test Type |
|---|---|
| Client method logic | Unit |
| Service business logic | Unit |
| Request/response handling | Unit |
| Full command execution flow | E2E |
| File operations with real filesystem | E2E |
| Process lifecycle (start, stop, signal) | E2E |
| Port exposure and preview URLs | E2E |
| Git operations | E2E |
File naming: *.test.ts for both unit and E2E tests
Test structure:
describe('ComponentName', () => {
describe('methodName', () => {
it('should do X when Y', async () => {
// Arrange
// Act
// Assert
});
});
});
Assertions: Use vitest's expect() with clear, specific assertions
After making any meaningful code change:
npm run check - catch type errors firstnpm test - verify unit tests passnpm run test:e2e - if touching core functionalityBuild trust: The monorepo build system handles dependencies automatically. E2E tests always run against latest built code - no manual rebuild needed.