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 |
scripts/setup-vitest.sh
View on GitHub#!/bin/bash
# setup-vitest.sh - Automated Vitest setup for Cloudflare Workers
#
# This script automates the installation and configuration of Vitest
# with @cloudflare/vitest-pool-workers for Workers testing.
#
# Usage:
# ./setup-vitest.sh
#
# Features:
# - Detects package manager (bun/npm/pnpm)
# - Installs required dependencies
# - Creates vitest.config.ts
# - Creates test/ directory with example test
# - Updates package.json scripts
#
# Requirements:
# - wrangler.jsonc must exist in project root
# - Node.js 20+ installed
set -e # Exit on error
echo "π Setting up Vitest for Cloudflare Workers..."
# Detect package manager
if command -v bun &> /dev/null; then
PKG_MANAGER="bun"
INSTALL_CMD="bun add -D"
RUN_CMD="bun"
elif command -v pnpm &> /dev/null; then
PKG_MANAGER="pnpm"
INSTALL_CMD="pnpm add -D"
RUN_CMD="pnpm"
elif command -v npm &> /dev/null; then
PKG_MANAGER="npm"
INSTALL_CMD="npm install --save-dev"
RUN_CMD="npx"
else
echo "β No package manager found (bun/npm/pnpm required)"
exit 1
fi
echo "π¦ Using package manager: $PKG_MANAGER"
# Check Node.js version
NODE_VERSION=$(node --version | cut -d'v' -f2 | cut -d'.' -f1)
if [ "$NODE_VERSION" -lt 20 ]; then
echo "β Node.js 20+ required (current: v$NODE_VERSION)"
echo " Install via: nvm install 20 && nvm use 20"
exit 1
fi
echo "β
Node.js version: v$NODE_VERSION"
# Check for wrangler config
if [ ! -f "wrangler.jsonc" ] && [ ! -f "wrangler.toml" ]; then
echo "β No wrangler.jsonc or wrangler.toml found"
echo " Create wrangler config first"
exit 1
fi
WRANGLER_CONFIG="wrangler.jsonc"
if [ ! -f "wrangler.jsonc" ]; then
WRANGLER_CONFIG="wrangler.toml"
fi
echo "β
Found $WRANGLER_CONFIG"
# Install dependencies
echo ""
echo "π¦ Installing dependencies..."
$INSTALL_CMD vitest@^2.1.8 @cloudflare/vitest-pool-workers@^0.7.2 @vitest/coverage-v8@^2.1.8
echo "β
Dependencies installed"
# Create vitest.config.ts
if [ -f "vitest.config.ts" ]; then
echo "β οΈ vitest.config.ts already exists, skipping..."
else
echo ""
echo "π Creating vitest.config.ts..."
cat > vitest.config.ts << 'EOF'
import { defineWorkersConfig } from '@cloudflare/vitest-pool-workers/config';
export default defineWorkersConfig({
test: {
poolOptions: {
workers: {
wrangler: { configPath: './wrangler.jsonc' },
miniflare: {
compatibilityDate: '2025-01-27',
compatibilityFlags: ['nodejs_compat']
}
}
},
coverage: {
provider: 'v8',
reporter: ['text', 'json', 'html'],
include: ['src/**/*.ts'],
exclude: ['src/**/*.test.ts', 'src/**/*.spec.ts'],
thresholds: {
lines: 80,
functions: 80,
branches: 75,
statements: 80
}
}
}
});
EOF
# Update wrangler path if using .toml.
# D-005: take a backup first and use portable in-place editing (BSD vs GNU sed).
if [ "$WRANGLER_CONFIG" = "wrangler.toml" ]; then
cp vitest.config.ts vitest.config.ts.bak
if sed --version >/dev/null 2>&1; then
sed -i 's/wrangler.jsonc/wrangler.toml/g' vitest.config.ts # GNU
else
sed -i '' 's/wrangler.jsonc/wrangler.toml/g' vitest.config.ts # BSD (macOS)
fi
fi
echo "β
Created vitest.config.ts"
fi
# Create test/ directory
if [ ! -d "test" ]; then
echo ""
echo "π Creating test/ directory..."
mkdir -p test
# Create example test
cat > test/index.test.ts << 'EOF'
import { describe, it, expect } from 'vitest';
import { env, createExecutionContext, waitOnExecutionContext } from 'cloudflare:test';
import worker from '../src/index';
describe('Worker', () => {
it('responds with 200', async () => {
const request = new Request('http://example.com/');
const ctx = createExecutionContext();
const response = await worker.fetch(request, env, ctx);
await waitOnExecutionContext(ctx);
expect(response.status).toBe(200);
});
});
EOF
echo "β
Created test/index.test.ts"
fi
# Update package.json scripts
if [ -f "package.json" ]; then
echo ""
echo "π Updating package.json scripts..."
# Check if jq is installed
if command -v jq &> /dev/null; then
# Use jq for safer JSON manipulation
TMP_FILE=$(mktemp)
jq '.scripts.test = "vitest run" | .scripts["test:watch"] = "vitest" | .scripts["test:coverage"] = "vitest run --coverage"' package.json > "$TMP_FILE"
mv "$TMP_FILE" package.json
echo "β
Updated package.json scripts"
else
echo "β οΈ jq not installed, skipping package.json update"
echo " Add manually:"
echo ' "test": "vitest run",'
echo ' "test:watch": "vitest",'
echo ' "test:coverage": "vitest run --coverage"'
fi
fi
# Success message
echo ""
echo "β¨ Vitest setup complete!"
echo ""
echo "Next steps:"
echo " 1. Run tests: $RUN_CMD test"
echo " 2. Watch mode: $RUN_CMD test:watch"
echo " 3. Coverage report: $RUN_CMD test:coverage"
echo ""
echo "Example test created at: test/index.test.ts"
echo "Configuration file: vitest.config.ts"
echo ""
echo "π Documentation: https://developers.cloudflare.com/workers/testing/"
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 |