local-dev-testing

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

• Typecheck with generated Env types.
• Run lint and unit tests.
• Validate migrations can apply to a fresh local database.
• Build frontend assets if the Worker serves a full-stack app.
• Run wrangler deploy --dry-run or equivalent config validation when available.
• Do not require production secrets for tests.