Unit testing

Zeno uses Vitest for unit testing, with native TypeScript support. The @zeno-lib/test package provides shared configs and Testing Library re-exports, so every package tests the same way. Install it alongside vitest and vite.

What you getCopy Anchor Link

Adding @zeno-lib/test (with vitest and vite) gives you shared configs, Testing Library re-exports and a Row Level Security test harness. Import Vitest runtime helpers (describe, test, expect, vi, …) directly from vitest:

InstallationCopy Anchor Link

In the package you want to test, follow these steps.

1. Install the packagesCopy Anchor Link

Install @zeno-lib/test together with its peer dependencies vitest and vite:

npm install --save-dev @zeno-lib/test vitest vite

2. Add the test scriptsCopy Anchor Link

The vitest CLI comes from the vitest package you installed:

{
  "scripts": {
    "test": "vitest --run",
    "test:watch": "vitest watch"
  }
}

3. Create a Vitest configCopy Anchor Link

Create a vitest.config.ts at the root of your package and re-export one config. Pick the preset that matches your package (see Choosing a config for the differences).

For plain TypeScript packages, use defaultConfig:

export { defaultConfig as default } from "@zeno-lib/test/configs"

For React packages, use reactConfig instead so component tests run in a DOM environment:

export { reactConfig as default } from "@zeno-lib/test/configs"

4. Write your first testCopy Anchor Link

Create a *.test.ts file (or *.test.tsx for React) under src/, test/, or tests/:

import { describe, expect, test } from "vitest"

describe("Example", () => {
  test("works", () => {
    expect(true).toBe(true)
  })
})

5. Run itCopy Anchor Link

pnpm test

Choosing a configCopy Anchor Link

The package ships two presets. Pick the one that matches your package.

defaultConfigCopy Anchor Link

Use it for plain TypeScript packages that need no DOM. It:

• Resolves your tsconfig path aliases (vite-tsconfig-paths).
• Loads environment variables from .env.test automatically.
• Discovers tests matching {src,test,tests}/**/*.test.ts.
• Enables type testing for {src,test,tests}/**/*.test-d.ts files.

reactConfigCopy Anchor Link

Extends defaultConfig with what React component tests need:

• Runs tests in a jsdom environment so the DOM is available.
• Enables the React plugin with the automatic JSX runtime, so you don't need import React.
• Widens test discovery to {src,test,tests}/**/*.test.{ts,tsx}, so it also picks up .tsx tests.

Extending the configCopy Anchor Link

To override shared defaults, merge a preset with package-specific options:

import { defineConfig, mergeConfig, reactConfig } from "@zeno-lib/test/configs"

export default mergeConfig(
  reactConfig,
  defineConfig({
    test: {
      // package-specific overrides
    },
  }),
)

Writing testsCopy Anchor Link

Import the helpers you need from vitest, since there are no globals:

import { describe, expect, test } from "vitest"

describe("Calculator", () => {
  test("adds two numbers", () => {
    expect(1 + 2).toBe(3)
  })

  test("handles edge cases", () => {
    expect(0 + 0).toBe(0)
    expect(-1 + 1).toBe(0)
  })
})

File location and namingCopy Anchor Link

Tests live alongside your source in src/ and must end in .test.ts or .test.tsx for Vitest to find them:

src/
├── calculator.ts
├── calculator.test.ts      # unit test
├── button.tsx
└── button.test.tsx         # React component test

Testing React componentsCopy Anchor Link

Use @zeno-lib/test/testing-library for rendering and querying, and @zeno-lib/test/user-event to simulate interactions. Both require the reactConfig preset.

@zeno-lib/test/testing-library is React Testing Library and @zeno-lib/test/user-event is User Event, re-exported without changes. See their documentation for the complete API.

These libraries let you test components the way a user uses them, rather than reaching into implementation details:

• React Testing Library mounts a component into the jsdom DOM and exposes queries (getByRole, getByText, …) that find elements by their accessible role and visible text. Assert on what's on screen, not on internal state or props, and a refactor that leaves the output unchanged doesn't break the test.
• User Event dispatches realistic interaction sequences (a click fires pointerdown, mousedown, focus, click, …), the same events a real user triggers. That catches bugs a single synthetic event would miss.

import { describe, expect, test, vi } from "vitest"
import { render, screen } from "@zeno-lib/test/testing-library"
import userEvent from "@zeno-lib/test/user-event"
import { Button } from "@zeno-lib/ui/button"

describe("Button", () => {
  test("renders with text", () => {
    render(<Button>Click me</Button>)
    expect(screen.getByRole("button")).toHaveTextContent("Click me")
  })

  test("calls onClick when pressed", async () => {
    const user = userEvent.setup()
    const onClick = vi.fn()

    render(<Button onClick={onClick}>Click me</Button>)
    await user.click(screen.getByRole("button"))

    expect(onClick).toHaveBeenCalledOnce()
  })
})

MockingCopy Anchor Link

Import vi and other helpers from vitest. Vitest's mock hoister only recognizes vi from the "vitest" specifier, so always import it from vitest for vi.fn(), vi.mock(), vi.hoisted(), and the rest. See the Mocking guide for the full range of techniques.

import { describe, expect, test, vi } from "vitest"

const mockFetch = vi.fn()

describe("API", () => {
  test("fetches data", async () => {
    mockFetch.mockResolvedValue({ data: "test" })
    const result = await mockFetch()
    expect(result.data).toBe("test")
  })
})

import { describe, expect, test, vi } from "vitest"

vi.mock("./api", () => ({
  fetchData: vi.fn(),
}))

import { fetchData } from "./api"

describe("API client", () => {
  test("calls fetchData", async () => {
    vi.mocked(fetchData).mockResolvedValue({ data: "test" })
    const result = await fetchData()
    expect(result.data).toBe("test")
  })
})

Testing Row Level SecurityCopy Anchor Link

@zeno-lib/test/supabase runs a suite as real Supabase users: it creates them through the Auth admin API, signs them in on one publishable-key client, and gives you a database handle bound to that client. It needs @supabase/supabase-js and a running local Supabase. You pass the database client through createDb, typically createAuthClient from @zeno-lib/db.

import { createClient } from "@supabase/supabase-js"
import { createAuthClient } from "@zeno-lib/db"
import { createRlsTestHarness, idsSeen, signInAs } from "@zeno-lib/test/supabase"
import { afterAll, expect, it } from "vitest"

const harness = createRlsTestHarness({
  admin: createClient(url, secretKey),
  client: createClient(url, publishableKey),
  createDb: (client) => createAuthClient(client, { relations }),
  // Your domain's setup for each new user, e.g. role rows.
  onCreateUser: async (user, options: { roles?: string[] } | undefined, { admin }) => {
    for (const role of options?.roles ?? []) {
      const { error } = await admin.from("users_roles").insert({ role, user_id: user.id })
      if (error) throw error
    }
  },
})

afterAll(() => harness.cleanUp())

it("anon sees nothing", async () => {
  await signInAs(harness, null)
  expect(await idsSeen(() => harness.db.select().from(deals))).toEqual(new Set())
})

it("admins see every deal", async () => {
  await signInAs(harness, { roles: ["ADMIN"] })
  expect(await idsSeen(() => harness.db.select().from(deals))).toEqual(new Set([1, 2]))
})

• The harness builds harness.db once, and the handle follows whoever is signed in, so you can capture it anywhere.
• signInAs always signs in a fresh user, because an access-token hook usually writes claims such as roles into the token at sign-in.
• Assert the exact set idsSeen returns. An empty set is also what a broken claims setup looks like.
• cleanUp() deletes every user the harness created, then signs out and closes db. It retries transient Auth errors and skips users that are already gone. Delete rows that reference those users first.

Type testingCopy Anchor Link

Both presets also type-check files ending in .test-d.ts. Use expectTypeOf to assert on types without running any runtime code. See Vitest's Testing Types guide for the full API:

import { expectTypeOf, test } from "vitest"

test("greet returns a string", () => {
  expectTypeOf(greet("world")).toBeString()
})

Environment variablesCopy Anchor Link

Tests run with NODE_ENV=test. Both configs load .env.test automatically, so put test-specific variables in a .env.test file in your package and read them from process.env during the run.

CommandsCopy Anchor Link

# Run tests once
pnpm test

# Watch mode
pnpm test:watch

# Run a single test file
pnpm test src/example.test.ts

In a monorepo, scope the run to one package with Turborepo's --filter:

pnpm turbo run test --filter <package-name>