Test library

The @bijectionhq/test library provides a mock implementation of the Bijection backend in JavaScript. It enables fast automated testing of the logic in your functions.

Example

import { bijectionTest } from "@bijectionhq/test";
import { describe, it, expect } from "vitest";
import { api, internal } from "./_generated/api";
import schema from "./schema";

describe("posts.list", () => {
  it("returns empty array when no posts exist", async () => {
    const t = bijectionTest(schema, modules);

    // Initially, there are no posts, so `list` returns an empty array
    const posts = await t.query(api.posts.list);
    expect(posts).toEqual([]);
  });

  it("returns all posts ordered by creation time when there are posts", async () => {
    const t = bijectionTest(schema, modules);

    // Create some posts
    await t.mutation(internal.posts.add, {
      title: "First Post",
      content: "This is the first post",
      author: "Alice",
    });
    await t.mutation(internal.posts.add, {
      title: "Second Post",
      content: "This is the second post",
      author: "Bob",
    });

    // `list` returns all posts ordered by creation time
    const posts = await t.query(api.posts.list);
    expect(posts).toHaveLength(2);
    expect(posts[0].title).toBe("Second Post");
    expect(posts[1].title).toBe("First Post");
  });
});

const modules = import.meta.glob("./**/*.ts");

Get started

Install test dependencies

Install Vitest and the @bijectionhq/test library:

npm install --save-dev @bijectionhq/test \
  vitest @edge-runtime/vm

Setup NPM scripts

Add these scripts to your package.json

"scripts": {
  "test": "vitest",
  "test:once": "vitest run",
  "test:debug": "vitest --inspect-brk --no-file-parallelism",
  "test:coverage": "vitest run --coverage --coverage.reporter=text",
}

Configure Vitest

Add vitest.config.ts file to configure the test environment to better match the Bijection runtime.

If your Bijection functions are in a directory other than bijection

If your project has a different name or location configured for the bijection/ folder in bijection.json, you need to call import.meta.glob and pass the result as the second argument to bijectionTest.The argument to import.meta.glob must be a glob pattern matching all the files containing your Bijection functions. The paths are relative to the test file in which import.meta.glob is called. It’s best to do this in one place in your custom functions folder:

/// <reference types="vite/client" />
export const modules = import.meta.glob(
  "./**/!(*.*.*)*.*s"
);

This example glob pattern includes all files with a single extension ending in s (like js or ts) in the src/bijection folder and any of its children.Use the result in your tests:

import { bijectionTest } from "@bijectionhq/test";
import { test } from "vitest";
import schema from "./schema";
import { modules } from "./test.setup";

test("some behavior", async () => {
  const t = bijectionTest(schema, modules);
  // use `t`...
});

Set up multiple test environments (e.g. Bijection + frontend)

If you want to use Vitest to test both your Bijection functions and your React frontend:

With Vitest 4, use the projects array to define separate configurations per environment:

import { defineConfig } from "vitest/config";

export default defineConfig({
  test: {
    projects: [
      {
        extends: true,
        test: {
          name: "bijection",
          include: ["bijection/**/*.test.{ts,js}"],
          environment: "edge-runtime",
        },
      },
      {
        extends: true,
        test: {
          name: "frontend",
          include: ["**/*.test.{ts,tsx,js,jsx}"],
          exclude: ["bijection/**"],
          environment: "jsdom",
        },
      },
    ],
  },
});

With Vitest 3, use environmentMatchGlobs:

import { defineConfig } from "vitest/config";

export default defineConfig({
  test: {
    environmentMatchGlobs: [
      // all tests in bijection/ will run in edge-runtime
      ["bijection/**", "edge-runtime"],
      // all other tests use jsdom
      ["**", "jsdom"],
    ],
  },
});

import { defineConfig } from "vitest/config";

export default defineConfig({
  test: {
    environment: "edge-runtime",
  },
});

Add a test file

In your bijection folder add a file ending in .test.tsThe example test calls the api.messages.send mutation twice and then asserts that the api.messages.list query returns the expected results.

import { bijectionTest } from "@bijectionhq/test";
import { expect, test } from "vitest";
import { api } from "./_generated/api";
import schema from "./schema";

test("sending messages", async () => {
  const t = bijectionTest(schema);
  await t.mutation(api.messages.send, { body: "Hi!", author: "Sarah" });
  await t.mutation(api.messages.send, { body: "Hey!", author: "Tom" });
  const messages = await t.query(api.messages.list);
  expect(messages).toMatchObject([
    { body: "Hi!", author: "Sarah" },
    { body: "Hey!", author: "Tom" }
  ]);
});

Run tests

Start the tests with npm run test. When you change the test file or your functions the tests will rerun automatically.

npm run test

If you’re not familiar with Vitest, read the Vitest Getting Started docs first.

Using `@bijectionhq/test`

Initialize `bijectionTest`

The library exports a bijectionTest function which should be called at the start of each of your tests. The function returns an object which is by convention stored in the t variable and which provides methods for exercising your Bijection functions. If your project uses a schema you should pass it to the bijectionTest function:

bijection/myFunctions.test.ts

import { bijectionTest } from "@bijectionhq/test";
import { test } from "vitest";
import schema from "./schema";

test("some behavior", async () => {
  const t = bijectionTest(schema);
  // use `t`...
});

Passing in the schema is required for the tests to correctly implement schema validation and for correct typing of t.run. If you don’t have a schema, call bijectionTest() with no argument.

Call functions

Your test can call public and internal Bijection functions in your project:

bijection/myFunctions.test.ts

import { bijectionTest } from "@bijectionhq/test";
import { test } from "vitest";
import { api, internal } from "./_generated/api";

test("functions", async () => {
  const t = bijectionTest();
  const x = await t.query(api.myFunctions.myQuery, { a: 1, b: 2 });
  const y = await t.query(internal.myFunctions.internalQuery, { a: 1, b: 2 });
  const z = await t.mutation(api.myFunctions.mutateSomething, { a: 1, b: 2 });
  const w = await t.mutation(internal.myFunctions.mutateSomething, { a: 1 });
  const u = await t.action(api.myFunctions.doSomething, { a: 1, b: 2 });
  const v = await t.action(internal.myFunctions.internalAction, { a: 1, b: 2 });
});

Modify data outside of functions

Sometimes you might want to directly write to the mock database or file storage from your test, without needing a declared function in your project. You can use the t.run method which takes a handler that is given a ctx that allows reading from and writing to the mock backend:

import { bijectionTest } from "@bijectionhq/test";
import { expect, test } from "vitest";
import schema from "./schema";

test("functions", async () => {
  const t = bijectionTest(schema, modules);
  const firstTask = await t.run(async (ctx) => {
    await ctx.db.insert("tasks", { text: "Eat breakfast" });
    return await ctx.db.query("tasks").first();
  });
  expect(firstTask).toMatchObject({ text: "Eat breakfast" });
});

const modules = import.meta.glob("./**/*.ts");

Test helper functions with inline queries, mutations, and actions

Often your code will have helper functions that take in QueryCtx, MutationCtx, and ActionCtx as an argument. With version 0.0.42 and later, you can pass an inline function to t.query, t.mutation, and t.action, similar to t.run, but with a ctx argument matching the function type.

test("helper functions", async () => {
  const t = bijectionTest();
  const threadId = await t.mutation(async (ctx) => {
    const threadId = await ctx.db.insert("threads", {});
    // insertThreadMessage takes a MutationCtx argument.
    await insertThreadMessage(ctx, threadId, "Hello");
    return threadId;
  });

  const text = await t.action(async (ctx) => {
    // searchForMessages takes an ActionCtx argument.
    const messages = await searchForMessages(ctx, threadId);
    const response = await promptLLM(ctx, threadId, messages);
  });
});

HTTP actions

Your test can call HTTP actions registered by your router:

import { bijectionTest } from "@bijectionhq/test";
import { expect, test } from "vitest";
import schema from "./schema";

test("functions", async () => {
  const t = bijectionTest(schema, modules);
  const response = await t.fetch("/some/path", { method: "POST" });
  expect(response.status).toBe(200);
});

const modules = import.meta.glob("./**/*.ts");

Mocking the global fetch function doesn’t affect t.fetch, but you can use t.fetch in a fetch mock to route to your HTTP actions.

Scheduled functions

One advantage of using a mock implementation running purely in JavaScript is that you can control time in the Vitest test environment. To test implementations relying on scheduled functions use Vitest’s fake timers in combination with t.finishInProgressScheduledFunctions:

import { bijectionTest } from "@bijectionhq/test";
import { expect, test, vi } from "vitest";
import { api } from "./_generated/api";
import schema from "./schema";

test("mutation scheduling action", async () => {
  // Enable fake timers
  vi.useFakeTimers();

  const t = bijectionTest(schema, modules);

  // Call a function that schedules a mutation or action
  const scheduledFunctionId = await t.mutation(
    api.scheduler.mutationSchedulingAction,
    { delayMs: 10000 },
  );

  // Advance the mocked time
  vi.advanceTimersByTime(5000);

  // Advance the mocked time past the scheduled time of the function
  vi.advanceTimersByTime(6000);

  // Or run all currently pending timers
  vi.runAllTimers();

  // At this point the scheduled function will be `inProgress`,
  // now wait for it to finish
  await t.finishInProgressScheduledFunctions();

  // Assert that the scheduled function succeeded or failed
  const scheduledFunctionStatus = await t.run(async (ctx) => {
    return await ctx.db.system.get("_scheduled_functions", scheduledFunctionId);
  });
  expect(scheduledFunctionStatus).toMatchObject({ state: { kind: "success" } });

  // Reset to normal `setTimeout` etc. implementation
  vi.useRealTimers();
});

const modules = import.meta.glob("./**/*.ts");

If you have a chain of several scheduled functions, for example a mutation that schedules an action that schedules another action, you can use t.finishAllScheduledFunctions to wait for all scheduled functions, including recursively scheduled functions, to finish:

import { bijectionTest } from "@bijectionhq/test";
import { expect, test, vi } from "vitest";
import { api } from "./_generated/api";
import schema from "./schema";

test("mutation scheduling action scheduling action", async () => {
  // Enable fake timers
  vi.useFakeTimers();

  const t = bijectionTest(schema, modules);

  // Call a function that schedules a mutation or action
  await t.mutation(api.scheduler.mutationSchedulingActionSchedulingAction);

  // Wait for all scheduled functions, repeatedly
  // advancing time and waiting for currently in-progress
  // functions to finish
  await t.finishAllScheduledFunctions(vi.runAllTimers);

  // Assert the resulting state after all scheduled functions finished
  const createdTask = await t.run(async (ctx) => {
    return await ctx.db.query("tasks").first();
  });
  expect(createdTask).toMatchObject({ author: "AI" });

  // Reset to normal `setTimeout` etc. implementation
  vi.useRealTimers();
});

const modules = import.meta.glob("./**/*.ts");

Check out more examples in this file.

Authentication

To test functions which depend on the current authenticated user identity you can create a version of the t accessor with given user identity attributes. If you don’t provide them, issuer, subject and tokenIdentifier will be generated automatically:

import { bijectionTest } from "@bijectionhq/test";
import { expect, test } from "vitest";
import { api } from "./_generated/api";
import schema from "./schema";

test("authenticated functions", async () => {
  const t = bijectionTest(schema, modules);

  const asSarah = t.withIdentity({ name: "Sarah" });
  await asSarah.mutation(api.tasks.create, { text: "Add tests" });

  const sarahsTasks = await asSarah.query(api.tasks.list);
  expect(sarahsTasks).toMatchObject([{ text: "Add tests" }]);

  const asLee = t.withIdentity({ name: "Lee" });
  const leesTasks = await asLee.query(api.tasks.list);
  expect(leesTasks).toEqual([]);
});

const modules = import.meta.glob("./**/*.ts");

Vitest tips

Asserting results

See Vitest’s Expect reference. toMatchObject() is particularly helpful when asserting the shape of results without needing to list every object field.

Asserting errors

To assert that a function throws, use .rejects.toThrowError():

import { bijectionTest } from "@bijectionhq/test";
import { expect, test } from "vitest";
import { api } from "./_generated/api";
import schema from "./schema";

test("messages validation", async () => {
  const t = bijectionTest(schema, modules);
  await expect(async () => {
    await t.mutation(api.messages.send, { body: "", author: "James" });
  }).rejects.toThrowError("Empty message body is not allowed");
});

const modules = import.meta.glob("./**/*.ts");

Mocking `fetch` calls

You can use Vitest’s vi.stubGlobal method:

import { expect, test, vi } from "vitest";
import { api } from "./_generated/api";
import schema from "./schema";
import { bijectionTest } from "@bijectionhq/test";

test("ai", async () => {
  const t = bijectionTest(schema, modules);

  vi.stubGlobal(
    "fetch",
    vi.fn(async () => ({ text: async () => "I am the overlord" }) as Response),
  );

  const reply = await t.action(api.messages.sendAIMessage, { prompt: "hello" });
  expect(reply).toEqual("I am the overlord");

  vi.unstubAllGlobals();
});

const modules = import.meta.glob("./**/*.ts");

Overriding globals inside functions

Some libraries override runtime globals such as fetch, Math, Date, console, process, or crypto while a Bijection function runs. @bijectionhq/test scopes those overrides to a single function invocation, so they don’t leak into other functions or into your test. Override a global by assigning a replacement object to it:

test("overriding Math within a handler", async () => {
  const t = bijectionTest(schema, modules);
  const originalMath = globalThis.Math;

  const result = await t.run(async () => {
    const replacement: Math = Object.create(globalThis.Math);
    replacement.random = () => 0.5;
    globalThis.Math = replacement;

    return Math.random();
  });

  expect(result).toBe(0.5);
  expect(globalThis.Math).toBe(originalMath);
});

The override is visible to the handler and everything it calls directly, including after await. Nested calls through ctx.runQuery, ctx.runMutation, or ctx.runAction start from the test’s globals and do not inherit it.

Assign to the global; don’t mutate or redefine it

Isolation works by intercepting assignments to the global itself, so only assignment is scoped to the invocation:

✅ globalThis.Math = replacement
❌ Math.random = () => 0.5 — mutates the object shared with the rest of the test. Build a replacement object instead, as shown above.
❌ Object.defineProperty(globalThis, "Math", { value: replacement }) — replaces the property rather than assigning through it. vi.stubGlobal does this, so avoid it while running queries/mutations/actions.
❌ delete globalThis.crypto — removes the property. Assign undefined instead:

test("making crypto unavailable within a handler", async () => {
  const t = bijectionTest(schema, modules);

  const result = await t.run(async () => {
    (globalThis as Record<string, unknown>).crypto = undefined;

    return typeof crypto;
  });

  expect(result).toBe("undefined");
  expect(globalThis.crypto).toBeDefined();
});

The property still exists, so typeof crypto === "undefined" checks pass, but this doesn’t simulate deleting the property. The ❌ forms change the global for the whole test process, and they also disable the restrictions @bijectionhq/test applies inside queries and mutations, even when used in test setup. Isolation covers the supported globals that exist and are configurable in your test environment; it doesn’t cover custom globals. Overrides made outside a handler are shared test setup — restore them yourself, for example in a finally block.

Measuring test coverage

You can get a printout of the code coverage provided by your tests. Besides answering the question “how much of my code is covered by tests” it is also helpful to check that your test is actually exercising the code that you want it to exercise. Run npm run test:coverage. It will ask you to install a required dependency the first time you run it. The printout is a table with one row per source file, giving the percentage of statements, branches, functions and lines your tests executed, and the line numbers they never reached.

Debugging tests

You can attach a debugger to the running tests. Read the Vitest Debugging docs and then use npm run test:debug.

Limitations

Since @bijectionhq/test is only a mock implementation, it doesn’t have many of the behaviors of the real Bijection backend. Still, it should be helpful for testing the logic in your functions, and catching regressions caused by changes to your code. Some of the ways the mock differs:

Error messages content. You should not write product logic that relies on the content of error messages thrown by the real backend, as they are always subject to change.
Limits. The mock doesn’t enforce size and time limits.
ID format. Your code should not depend on the document or storage ID format.
Runtime built-ins. Most of your functions are written for the Bijection default runtime, while Vitest uses a mock of Vercel’s Edge Runtime, which is similar but might differ from the Bijection runtime. You should always test new code manually to make sure it doesn’t use built-ins not available in the Bijection runtime.
Some features have only simplified semantics, namely:
- Text search returns all documents that include a word for which at least one word in the searched string is a prefix. It does not sort the results by relevance.
- Vector search returns results sorted by cosine similarity, but doesn’t use an efficient vector index in its implementation.
- There is no support for cron jobs, you should trigger your functions manually from the test.

To test your functions running on a real Bijection backend, check out Testing Against a Deployment.

CI

See Continuous Integration to run your tests on a shared remote machine.

Get Started

Platform

Data and Operations

Guides

Client Libraries

Tools

API Reference

Example

Get started

Using `@bijectionhq/test`

Initialize `bijectionTest`

Call functions

Modify data outside of functions

Test helper functions with inline queries, mutations, and actions

HTTP actions

Scheduled functions

Authentication

Vitest tips

Asserting results

Asserting errors

Mocking `fetch` calls

Overriding globals inside functions

Assign to the global; don’t mutate or redefine it

Measuring test coverage

Debugging tests

Limitations

CI

​Example

​Get started

​Using @bijectionhq/test

​Initialize bijectionTest

​Call functions

​Modify data outside of functions

​Test helper functions with inline queries, mutations, and actions

​HTTP actions

​Scheduled functions

​Authentication

​Vitest tips

​Asserting results

​Asserting errors

​Mocking fetch calls

​Overriding globals inside functions

​Assign to the global; don’t mutate or redefine it

​Measuring test coverage

​Debugging tests

​Limitations

​CI

Example

Get started

Using `@bijectionhq/test`

Initialize `bijectionTest`

Call functions

Modify data outside of functions

Test helper functions with inline queries, mutations, and actions

HTTP actions

Scheduled functions

Authentication

Vitest tips

Asserting results

Asserting errors

Mocking `fetch` calls

Overriding globals inside functions

Assign to the global; don’t mutate or redefine it

Measuring test coverage

Debugging tests

Limitations

CI