secondsky/claude-skills / plugins/cloudflare-workers/skills/cloudflare-workers-testing
cloudflare-workers-testing
VerifiedComprehensive testing guide for Cloudflare Workers using Vitest and @cloudflare/vitest-pool-workers. Use for test setup, binding mocks (D1/KV/R2/DO), integration tests, or encountering test failures, mock errors, coverage issues.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 20.6 KB |
| references/binding-mocks.md | markdown | 12.1 KB |
| references/coverage-optimization.md | markdown | 7.4 KB |
| references/integration-testing.md | markdown | 8.9 KB |
| references/troubleshooting.md | markdown | 7.3 KB |
| references/vitest-setup.md | markdown | 6.8 KB |
| scripts/run-tests.sh | script | 4.2 KB |
| scripts/setup-vitest.sh | script | 5.0 KB |
| templates/basic-test.ts | script | 5.3 KB |
| templates/binding-mock-test.ts | script | 8.7 KB |
| templates/vitest-config.ts | script | 3.0 KB |
references/coverage-optimization.md
View on GitHub# Test Coverage Optimization for Cloudflare Workers
Complete guide for measuring, optimizing, and maintaining high test coverage.
## Coverage Configuration
### Basic Setup
Add to `vitest.config.ts`:
```typescript
import { defineWorkersConfig } from '@cloudflare/vitest-pool-workers/config';
export default defineWorkersConfig({
test: {
coverage: {
provider: 'v8', // Use V8 coverage (recommended for Workers)
reporter: ['text', 'json', 'html', 'lcov'],
include: ['src/**/*.ts'],
exclude: [
'src/**/*.test.ts',
'src/**/*.spec.ts',
'src/types/**',
'node_modules/**'
],
thresholds: {
lines: 80,
functions: 80,
branches: 75,
statements: 80
}
}
}
});
```
### Install Coverage Provider
```bash
bun add -D @vitest/coverage-v8
```
### Run Coverage
```bash
# Generate coverage report
bunx vitest run --coverage
# Watch mode with coverage
bunx vitest --coverage
```
## Coverage Reports
### Text Report (Terminal)
```bash
bunx vitest run --coverage --reporter=text
```
Output:
```
--------------------|---------|----------|---------|---------|-------------------
File | % Stmts | % Branch | % Funcs | % Lines | Uncovered Line #s
--------------------|---------|----------|---------|---------|-------------------
All files | 85.71 | 83.33 | 88.89 | 85.71 |
src | 90.00 | 87.50 | 100 | 90.00 |
index.ts | 90.00 | 87.50 | 100 | 90.00 | 42-45
src/utils | 80.00 | 75.00 | 75.00 | 80.00 |
validator.ts | 80.00 | 75.00 | 75.00 | 80.00 | 15-18,22
--------------------|---------|----------|---------|---------|-------------------
```
### HTML Report (Browser)
```bash
bunx vitest run --coverage --reporter=html
```
Open `coverage/index.html` in browser for interactive report.
### JSON Report (CI/CD)
```bash
bunx vitest run --coverage --reporter=json
```
Generates `coverage/coverage-final.json` for programmatic analysis.
### LCOV Report (Codecov)
```bash
bunx vitest run --coverage --reporter=lcov
```
Generates `coverage/lcov.info` for upload to Codecov, Coveralls, etc.
## Coverage Thresholds
### Enforce Minimum Coverage
```typescript
export default defineWorkersConfig({
test: {
coverage: {
thresholds: {
lines: 80, // At least 80% of lines covered
functions: 80, // At least 80% of functions covered
branches: 75, // At least 75% of branches covered
statements: 80 // At least 80% of statements covered
}
}
}
});
```
**Fails CI if thresholds not met**:
```bash
bunx vitest run --coverage
# ERROR: Coverage for lines (78%) does not meet global threshold (80%)
```
### Per-File Thresholds
```typescript
export default defineWorkersConfig({
test: {
coverage: {
perFile: true, // Apply thresholds per file
thresholds: {
lines: 90, // Each file must have 90%+ coverage
autoUpdate: true // Update thresholds automatically
}
}
}
});
```
## Identifying Untested Code
### View Uncovered Lines
```bash
bunx vitest run --coverage --reporter=text
```
Look for "Uncovered Line #s" column:
```
File | % Lines | Uncovered Line #s
--------------|---------|-------------------
validator.ts | 75.00 | 15-18,22,35-40
```
**Fix**: Add tests covering lines 15-18, 22, and 35-40.
### Interactive HTML Report
```bash
bunx vitest run --coverage --reporter=html
open coverage/index.html
```
**Highlights uncovered code in red** for easy identification.
## Improving Coverage
### 1. Test All Branches
**Before** (50% branch coverage):
```typescript
function validateEmail(email: string): boolean {
if (!email) return false; // Tested
return email.includes('@'); // Not tested
}
// Test
it('rejects empty email', () => {
expect(validateEmail('')).toBe(false); // ✅ Line 2 covered
});
```
**After** (100% branch coverage):
```typescript
// Add test for positive case
it('validates email format', () => {
expect(validateEmail('user@example.com')).toBe(true); // ✅ Line 3 covered
});
```
### 2. Test Error Paths
**Before** (60% coverage):
```typescript
async function createUser(data: any) {
try {
return await env.DB.prepare('INSERT INTO users ...').bind(data).run();
} catch (error) {
throw new Error('Database error'); // Not tested
}
}
```
**After** (100% coverage):
```typescript
it('handles database errors', async () => {
// Trigger error (e.g., duplicate key)
await expect(createUser({ email: 'duplicate@example.com' }))
.rejects
.toThrow('Database error'); // ✅ Catch block covered
});
```
### 3. Test Edge Cases
```typescript
function paginate(page: number, limit: number) {
if (page < 1) page = 1; // Edge case 1
if (limit < 1) limit = 10; // Edge case 2
if (limit > 100) limit = 100; // Edge case 3
return { offset: (page - 1) * limit, limit };
}
describe('paginate', () => {
it('handles negative page', () => {
expect(paginate(-1, 10)).toEqual({ offset: 0, limit: 10 });
});
it('handles negative limit', () => {
expect(paginate(1, -5)).toEqual({ offset: 0, limit: 10 });
});
it('caps limit at 100', () => {
expect(paginate(1, 200)).toEqual({ offset: 0, limit: 100 });
});
});
```
## Coverage in CI/CD
### GitHub Actions
```yaml
name: Test Coverage
on: [push, pull_request]
jobs:
coverage:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: oven-sh/setup-bun@v2
- run: bun install
- run: bun test --coverage
- name: Upload to Codecov
uses: codecov/codecov-action@v4
with:
files: ./coverage/lcov.info
fail_ci_if_error: true # Fail if upload fails
- name: Check thresholds
run: |
if ! bun test --coverage --run; then
echo "Coverage thresholds not met"
exit 1
fi
```
### Coverage Badge
Add to README.md:
```markdown
[](https://codecov.io/gh/user/repo)
```
## Best Practices
1. **Aim for 80%+ coverage**: Balance between quality and effort
2. **100% critical paths**: Auth, payments, data validation
3. **Test behavior, not implementation**: Don't test private functions
4. **Use coverage to find gaps**: Not as success metric
5. **Update tests with code changes**: Keep coverage high over time
6. **Review coverage in PRs**: Don't merge if coverage drops
## Common Anti-Patterns
### ❌ Testing for Coverage Numbers
```typescript
// ❌ BAD: Pointless test just for coverage
it('increases coverage', () => {
const x = 1 + 1;
expect(x).toBe(2);
});
```
### ❌ Testing Private Functions Directly
```typescript
// ❌ BAD: Testing implementation details
import { privateHelper } from '../src/utils';
it('tests private function', () => {
expect(privateHelper('test')).toBe('TEST');
});
```
**Instead**: Test via public API that calls the private function.
### ❌ Ignoring Untested Branches
```typescript
// ❌ BAD: Marking lines as untested without fixing
/* istanbul ignore next */
if (rare-condition) {
// Untested code
}
```
**Instead**: Write test for the condition or remove dead code.
## Tools and Resources
- **Codecov**: https://codecov.io/ (coverage tracking)
- **Coveralls**: https://coveralls.io/ (alternative)
- **Vitest Coverage**: https://vitest.dev/guide/coverage.html
- **V8 Coverage**: https://v8.dev/blog/javascript-code-coverage
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the work | Stars: 321k | Updated | Claude CodeCodex | Verified | Install |
| systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixes | Stars: 321k | Updated | Claude CodeCodex | Verified | Install |
| test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation code | Stars: 321k | Updated | Claude CodeCodex | Verified | Install |
| skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy. | Stars: 197k | Updated | Claude CodeCodex | Verified | Install |