Testing Bindings

Test KV the way Devflare expects it to run

Workers KV is a global key-value store for low-latency reads and lightweight shared data.

Use the default test harness first. KV is one of the bindings Devflare supports best in local tests.

When you call , KV namespaces are wired into the same env contract your worker code uses. That lets you test reads and writes without inventing a fake abstraction first.

Best for: Worker tests that read and write real KV values through the local harness
Default harness: plus or
Escalate when: You need to verify provisioning, preview naming, or account-side behavior

Start with the default test loop

Start small: create the test context, write a value, read it back, and only then move outward to HTTP or queue-driven flows.

If the binding matters because a route uses it, test through that route. If the binding itself is the thing you are verifying, talk to directly.

Testing KV through the real Devflare env

import { afterAll, beforeAll, expect, test } from 'bun:test'

import { createTestContext, env } from 'devflare/test'

beforeAll(() => createTestContext())

afterAll(() => env.dispose())

test('stores and reads a cache value', async () => {

await env.CACHE.put('feature:search', 'on')

expect(await env.CACHE.get('feature:search')).toBe('on')

})

The helper surface to remember

Use or the specific KV binding directly when you want the shortest binding-focused assertion.
Use if the behavior only matters once a request has gone through your real handler.
Use only when the test truly should not boot the runtime-shaped harness.

When to move beyond the default harness

Local KV tests are excellent for behavior and shape, but they do not replace deploy-time checks for account provisioning or preview cleanup.
If a test is really about routing, auth, or caching headers, keep the assertion at the worker level instead of overfocusing on the namespace API.
Preview-specific namespace naming is worth one dedicated integration check when branch isolation matters.

A good default split

Test binding semantics locally and test lifecycle semantics in preview or deploy-oriented paths. Trying to make one test do both usually makes it worse at each job.

KV internals

KV goes through the full Devflare pipeline: normalize authoring, resolve names when needed, then compile to Wrangler output.

KV example

This example keeps KV simple: one binding, one fetch handler, one assertion.