Testing Bindings

Test Hyperdrive the way Devflare expects it to run

Hyperdrive testing should start smaller and more cautiously than D1 testing: prove the binding exists, then add targeted integration where the real database path matters.

The codebase shows enough evidence to document Hyperdrive as supported, but not enough to oversell it as a drop-in local-first database harness identical to D1.

Best for: Binding presence checks and targeted PostgreSQL integration paths
Default harness: plus small binding or smoke checks
Escalate when: The app depends on real preview isolation or actual Postgres query behavior

Start with the default test loop

Start with one small assertion that the binding exists and exposes the connection information your code expects. That already tells you whether the config and runtime wiring are sane.

Then add focused integration tests against the actual database path instead of manufacturing a huge fake local contract that the repo itself does not clearly guarantee.

A conservative Hyperdrive smoke test

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

import { createTestContext } from 'devflare/test'

import { env } from 'devflare'

beforeAll(() => createTestContext())

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

test('Hyperdrive binding exposes connection info', () => {

expect(env.DB).toBeDefined()

expect(Boolean(env.DB?.connectionString)).toBe(true)

})

The helper surface to remember

Use small binding-presence checks first instead of overpromising local query semantics.
Keep one higher-level integration path for the real database behavior you actually care about.
If preview isolation matters, test the fallback or dedicated preview strategy explicitly.

When to move beyond the default harness

Do not present Hyperdrive as if Devflare already gives it the same local comfort story as D1.
If the worker truly depends on live query behavior, prefer an integration test against a real database path.
Preview-specific Hyperdrive expectations deserve a dedicated test because automatic cloning is not guaranteed.

Conservative is the honest test strategy

The goal is trustworthy docs, not pretending every binding has identical local ergonomics.

Hyperdrive internals

Hyperdrive uses the same normalize-and-resolve pattern as KV and D1, but preview lifecycle includes a fallback path instead of guaranteed preview cloning.

Hyperdrive example

This example keeps Hyperdrive focused on one thing: prove the binding exists and expose the connection information your app will need next.