As the lead for a Workers codebase, how do you decide what the team tests in the Workers Vitest plugin and what it checks only against a production build or remote resources?
answer
- fast local loop versus fidelity
- the runner forces Node.js compatibility
- same isolate, Vite resolution
- a production-build harness
- remote bindings must be opted out
basics
~20 sUse the plugin for handler logic and binding behaviour, since it is fast, local and credential-free. Cover what its runner changes, such as compatibility flags and module resolution, with a production-build check like createTestHarness(), and platform-only behaviour on a deployed preview.
solid answer
~50 sI'd make the plugin the default for logic and binding contracts: handlers, Durable Object state and alarms, D1 queries against the migrated schema, queue acknowledgement and retry decisions. It runs in `workerd`, needs no account and isolates storage per file, so it belongs in every CI run. Then I'd list what it cannot vouch for. Its runner turns Node.js compatibility on even when the Worker opts out, so a Worker calling `Buffer` passes tests and throws in production. The main Worker shares the test's isolate, Vite's module resolution and any global mocks. `exports` does not serve static assets. Fake timers do not reach the KV, R2 and cache simulators. Those risks get a smaller suite run against the production build with Wrangler's `createTestHarness()`, plus a smoke check on a deployed preview. In CI I'd also set `remoteBindings: false`, so no test reaches a real resource by accident.
code
javascript · 5 linesexport default {
async fetch() {
return new Response(Buffer.from("hi").toString("base64"));
},
};go deeper
Recall that plugin tests run locally in workerd, without an account, and that a passing suite is not the same as a working deployment.
Name concrete differences between the plugin's runner and production, such as forced Node.js compatibility, Vite module resolution and no static assets through exports.
Map each runner difference to a check that would catch it, such as a production-build harness, an auxiliary Worker or a preview smoke test, and keep credentials out of the default CI job.
Own the layering as policy: which suite gates merges, which gates rollouts, who keeps test and Wrangler configuration aligned, and how compatibility-date bumps are verified, weighing feedback speed against fidelity.
## The decision Every Workers team ends up with tests at more than one distance from production, and someone has to decide which behaviour is proven where. The Workers Vitest plugin is cheap and fast, so the temptation is to treat a green plugin suite as proof the Worker works. The lead's job is to know what the plugin's runner changes about the Worker, and to make sure each of those changes is covered by something closer to production, without paying production-level cost for everything. ## What the plugin is good at - **Handler logic** for `fetch`, `scheduled` and `queue`, called directly or through `exports.default.fetch()`. - **Binding contracts** against local simulators: KV reads and writes, R2 objects, D1 queries on the schema built from the real migrations, Durable Object state, alarms and eviction. - **Determinism**: fixed scheduled times, alarms fired on demand, storage isolated per test file. - **Cost**: no account, no API token, no network, seconds per run, so it can gate every pull request. - **Reach**: helpers such as `runInDurableObject()` inspect internal state that no request from outside could see. ## Where its runner differs from production | Difference | Effect | Where to cover it | |---|---|---| | The runner turns Node.js compatibility on, even overriding a `no_nodejs_compat_v2` opt-out | A Worker using `Buffer` or `process` passes tests and can fail once deployed | Production-build harness | | The main Worker shares the test's isolate and Vite's module resolution | Global mocks leak into the Worker; imports resolve differently from the deployed bundle | Auxiliary Worker or production-build harness | | `exports` does not expose static assets | Asset routing and fallbacks go untested | The `ASSETS` binding in unit tests, or a deployed preview | | Fake timers do not apply to the KV, R2 and cache simulators | Expiry cannot be tested by advancing time | Design for injected time, or a slower real-time test | | Local simulators are not the global service | Propagation delays, real limits and real request metadata never appear | Deployed preview or staging checks | | Remote bindings are enabled by default | A binding marked `remote: true` reaches the real resource from tests | Set `remoteBindings: false` in CI | The Node.js row is easy to underestimate. For compatibility dates from 2026-08-04, `nodejs_compat` is on by default, so the gap shows when a Worker opts out with `no_nodejs_compat` and `no_nodejs_compat_v2`, or keeps an older date without the flag. Under the plugin a `Buffer` call succeeds; under `wrangler dev` or in production the same Worker throws `ReferenceError: Buffer is not defined`. ## A layered policy 1. **Plugin suite on every change**: all handler and binding behaviour, required for merge. 2. **Production-build suite on every merge**: a smaller set run with Wrangler's `createTestHarness()` from a Node.js test runner. It runs the Worker's production build with its own compatibility settings, dispatches requests and scheduled events, and catches runner-only differences such as forced Node.js compatibility and shared global mocks. 3. **Deployed preview smoke check before rollout**: a handful of requests against an uploaded version, covering what only the platform shows. 4. **Remote-resource tests, rarely and deliberately**: nightly or pre-release, with a dedicated account and token, never in the default suite. ## Costs and ownership - Each layer up the list is slower and flakier, so the count of tests should shrink as fidelity grows. - Credentials belong only to the layers that need them; the default CI job should run with none. - Someone must own keeping the Vitest config in step with the Wrangler file: a binding added to one and not the other is a silent gap. - A compatibility-date bump should run layers 1 and 2, because the plugin alone cannot reveal a changed runtime default its runner overrides. ## Writing the policy down A policy that lives only in the lead's head erodes with every new contributor. A short testing section in the repository can state: - Which behaviour must have a plugin test before merge: every handler branch, every binding call that changes stored state, every alarm and queue retry rule. - Which changes also require the production-build suite: new dependencies, compatibility date or flag changes, new static assets or routing, and anything touching Node.js APIs. - That the default CI job runs with `remoteBindings: false` and no Cloudflare credentials. - Who reviews the Vitest config when the Wrangler file gains a binding. ## Signals the split is wrong - Production incidents that a plugin test "covered", which points to a runner difference nobody listed. - A production-build suite as large as the plugin suite, which means slow feedback for logic the plugin proves faster. - Tests that pass only with real credentials, which means remote access crept into the default suite.
- What does Wrangler's createTestHarness() exercise that the plugin does not?It runs the Worker's production build from its Wrangler file, or a Vite build, with the Worker's own compatibility settings, and drives it from a Node.js test runner with requests and scheduled events, across one or more Workers. It does not import the Worker's modules into the test's isolate, so runner-only differences such as forced Node.js compatibility or shared global mocks cannot hide a defect.
- Should a compatibility-date bump be gated by the plugin suite alone?No. The plugin's runner adds flags of its own, notably Node.js compatibility, so a date bump that changes a runtime default can pass there and still change production behaviour. Gate the bump on the production-build suite and a preview check as well, and record the decision with the team's compatibility-date policy.
- When is a test that reaches a real Cloudflare resource justified?When the behaviour exists only in the real service: global propagation, a real model or third-party binding, production limits. Keep such tests out of the default CI job, give them a dedicated account and a narrowly scoped token, run them nightly or before release, and keep `remoteBindings: false` everywhere else.
- A green Vitest plugin suite proves the Worker behaves the same in production.
- The plugin always runs the Worker with exactly the flags in the Wrangler file.
- Every test should hit real remote resources to be trustworthy.
- Vitest fake timers can expire a KV key inside a plugin test.
- exports.default.fetch() also covers the Worker's static assets.
Assumes @cloudflare/vitest-plugin 1.4.0 with Wrangler 4.149.0; nodejs_compat is on by default for compatibility dates from 2026-08-04, and createTestHarness() is Wrangler's current integration-test API.