npx skills add ...
npx skills add cloudflare/sandbox-sdk --skill testing
npx skills add cloudflare/sandbox-sdk --skill testing
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:
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:
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:
| 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:
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.
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');
});
});describe('ComponentName', () => {
describe('methodName', () => {
it('should do X when Y', async () => {
// Arrange
// Act
// Assert
});
});
});