# Local Dev Testing

> 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.

- Skill: `zllovesuki/local-dev-testing` (Agent Skill)
- Install (CLI): `npx skillmds@latest add zllovesuki/local-dev-testing`
- Raw SKILL.md: https://api.skillmd.com/api/skills/zllovesuki/local-dev-testing/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: zllovesuki (https://skillmd.com/u/zllovesuki)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/zllovesuki/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

```bash
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.

```ts
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.