Testing Bindings

Test Vectorize the way Devflare expects it to run

Vectorize stores embeddings in Cloudflare-managed indexes for similarity search from Workers.

The right Vectorize tests are targeted remote checks: a small insert or query, a clear skip condition, and a real index behind the binding.

Avoid pretending a local fake embedding store proved the same thing. It may still be useful for UI or higher-level app tests, but it is not the binding test.

Best for: Remote similarity-search checks and index smoke tests
Default harness: in remote mode plus
Escalate when: The index contract is business-critical enough to need explicit CI or release gating

Start with the default test loop

Keep the test as small as possible: insert one vector or query one known embedding and verify the shape of the result.

If the index is missing, skip with a clear message. That teaches future maintainers more than a mysterious failure ever will.

A remote Vectorize smoke test

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

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

beforeAll(() => createTestContext())

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

const skipVectorize = await shouldSkip.vectorize

describe.skipIf(skipVectorize)('Vectorize binding', () => {

test('accepts one upsert and one query', async () => {

const vector = Array(32).fill(0.5)

await env.DOCUMENT_INDEX.upsert?.([

{ id: 'doc-1', values: vector, metadata: { kind: 'demo' } }

])

const result = await env.DOCUMENT_INDEX.query?.(vector, { topK: 1 })

expect(result).toBeDefined()

})

The helper surface to remember

Use so missing remote prerequisites are explicit instead of noisy.
Keep the vector size and index name close to the test so the contract remains visible.
If the surrounding app only needs a demo path locally, mock above the worker boundary instead of pretending the remote index was exercised.

When to move beyond the default harness

Running Vectorize tests everywhere is rarely necessary; put them where the signal is worth the cost.
A passing local mock tells you nothing about index existence or vector dimension compatibility.
If a preview environment owns its own index, add one lifecycle-aware check for that path specifically.

A tiny real query beats a giant fake suite

For remote vector search, one truthful remote smoke check is often worth more than a dozen intricate local fakes.

Vectorize internals

Vectorize compiles cleanly into Wrangler output and participates in preview resource lifecycle, but the runtime value of the binding mostly lives in remote infrastructure.

Vectorize example

A real Vectorize application path with config and runtime code kept side by side.