Testing, preview environments, and gradual release
Protect Cloudflare releases with unit tests, workerd integration, isolated bindings, and evidence-backed rollback.
Edited and verified by Orange Book Editorial Team ·
Three layers, three claims
| Layer | Runs in | Proves |
|---|---|---|
| Pure unit test | A test environment such as Node | Validation, routing, and pure logic |
| Workers integration test | workerd / Vitest integration | Runtime APIs and binding behavior |
| Preview smoke test | The built preview Worker | Artifact, routes, headers, and resource wiring |
Cloudflare currently recommends its Vitest Workers integration for tests inside the Workers runtime. Pure Node tests are fast but cannot prove that an API absent or different in Workers will behave correctly.
Isolate environments
Bindings, variables, and secrets do not inherit automatically. Preview D1, R2, KV, and Vectorize should be separate resources, and test commands must not default to production data. Put resource names and migration versions in the release checklist.
Release sequence
Freeze a candidate
Lock dependencies, compatibility date, migrations, and generated types. CI begins with a clean install.
Run quality gates
Content audit, lint, types, unit/integration tests, production build, Wrangler dry-run bundle size, and workerd smoke must all pass.
Exercise critical paths in preview
Test allow/deny, found/not-found, empty data, and load boundaries. Retain Worker version and verification time.
Ramp and rollback
Start with limited traffic while watching errors, CPU, and latency. Rollback points to a known-good version; schema changes need a compatibility window.
Code rollback is not data rollback
If new code wrote data an old version cannot read, reverting the Worker can still fail. Prefer an expand/migrate/contract sequence with backward compatibility.
Primary sources
Did this page help you complete your goal?
Beta feedback is generated in this browser and is never uploaded automatically.
Logs, metrics, and evidence-led diagnosis
Connect symptoms to evidence with request IDs, Workers Logs, metrics, and structured errors.
Build Cloudflare applications with AI assistance
Give AI current context, constraints, and an acceptance contract before generating, reviewing, and verifying a normal Web application.