Local Dev Testing

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.