| name | local-dev-testing |
| description | Develop and test Cloudflare Workers locally with wrangler dev, Miniflare-compatible bindings, fixtures, integration tests, remote validation, and CI checks. Use when building local development workflows for Workers, D1, Durable Objects, KV, R2, Queues, or Workflows.
|
| compatibility | Cloudflare Workers TypeScript projects using Wrangler; verify current Cloudflare APIs, limits, and pricing before production use. |
| metadata | {"source":"Architecting on Cloudflare plus official Cloudflare Developer Platform docs","generated":"2026-04-28"} |
Local Development and Testing
Use this skill when setting up local tests or deciding what must be tested remotely on Cloudflare.
Local development stance
- Use local development to test business logic, route behavior, type safety, binding wiring, and ordinary persistence flows.
- Treat local runtime behavior as a simulator, not perfect proof of production latency, cache propagation, cold starts, placement, or network behavior.
- Add remote smoke tests for features where geography, cache behavior, WebSockets, object placement, production database latency, or quotas matter.
Basic commands
npm create cloudflare@latest my-app
cd my-app
npm install
npx wrangler dev
npx wrangler types
npm test
Test shape
Use small units for pure functions, then Worker integration tests for handlers and bindings.
import { describe, expect, it } from "vitest";
import worker from "../src/index";
describe("health route", () => {
it("returns ok", async () => {
const env = { APP_ENV: "test" } as Env;
const request = new Request("https://example.com/health");
const response = await worker.fetch(request, env, {} as ExecutionContext);
expect(response.status).toBe(200);
await expect(response.json()).resolves.toMatchObject({ ok: true });
});
});
Fixture strategy
- Keep schema migrations and seed data in version control.
- Reset local D1/KV/R2 fixtures before tests that mutate state.
- Mock external APIs unless the test is explicitly an integration test.
- Use deterministic IDs and timestamps in tests.
Remote validation cases
Run at least one deployed smoke test when any of these are in scope:
- Durable Object routing, alarms, WebSockets, or hibernation.
- Queue consumer batching/retry behavior.
- Workflows retries/checkpointing.
- R2 signed uploads/downloads and public domain behavior.
- KV propagation expectations.
- D1 performance/latency assumptions.
- AI model availability or streaming.
CI checklist
