Testing conventions and in-memory databases

Package exports (test code isolation)

src/index.ts

• Never re-export from

  ./test/

  or

  ./testing/

  in the main

  src/index.ts

• To expose test helpers, add a

  /testing

  subpath in

  package.json

  exports

  :

{
  "exports": {
    ".": "./src/index.ts",
    "./testing": "./src/testing/my-test-helpers.ts"
  }
}

• Consumers:

  import { Fake } from "@platform/my-package/testing"

• Biome

  noRestrictedImports

  blocks test paths in production source; tsdown fails the build if test code is resolved from prod entry points

Conventions

• Shared default environment: Node with globals enabled (

  packages/vitest-config/index.ts

  )
• Write tests, mostly e2e, some unit tests when logic is complex
• Unit tests: domain entities/use-cases/policies with fakes
• Contract tests: adapter compliance against domain ports
• Integration tests: infra-backed tests for Postgres/ClickHouse/Redis/BullMQ/object storage
• End-to-end tests: ingest boundary to query boundary across organization scoping
• Keep tests deterministic and isolated
• Prefer package-local runs during iteration; run full monorepo tests before PR

Database testing (in-memory)

vi.mock

vi.fn

• ClickHouse → chdb (

  chdb

  package): An in-process ClickHouse engine via

  @platform/testkit

  .
• Postgres → PGlite (

  @electric-sql/pglite

  ): An in-process Postgres via WASM via

  @platform/testkit

  .

Postgres test setup (

@platform/testkit

)

import { setupTestPostgres } from "@platform/testkit"
import { beforeAll, describe, it } from "vitest"

const pg = setupTestPostgres()

describe("MyRepository", () => {
  it("does something", async () => {
    // pg.postgresDb is a real Drizzle instance backed by PGlite in-memory
    // pg.db is the lower-level Drizzle/PGlite instance for direct queries
  })
})

setupTestPostgres()

• beforeAll: creates a PGlite instance, creates the

  latitude_app

  role, and runs all Drizzle migrations
• afterAll: closes the PGlite connection

ClickHouse test setup (

@platform/testkit

)

import { setupTestClickHouse } from "@platform/testkit"
import { beforeAll, describe, it } from "vitest"

const ch = setupTestClickHouse()

describe("MyRepository", () => {
  let repo: ReturnType<typeof createMyRepository>

  beforeAll(() => {
    repo = createMyRepository(ch.client)
  })

  it("does something", async () => {
    // ch.client is a real ClickHouseClient backed by chdb in-memory
  })
})

setupTestClickHouse()

• beforeAll: creates a chdb session and loads the schema from

  schema.sql

• beforeEach: truncates all tables for test isolation
• afterAll: destroys the session and cleans up temp files

pnpm --filter @platform/db-clickhouse ch:schema:dump

Why not

vi.mock

?

vi.fn()

argMax

GROUP BY