title: Testing description: Run tests and check code quality.#

hatk test#

Run your project's test suite.

hatk test                    # Run all tests
hatk test --unit             # Unit tests only
hatk test --integration      # Integration tests only
hatk test --browser          # Playwright browser tests

Without flags, all test types are run.

Writing unit tests#

Unit tests use createTestContext() from hatk/test to boot an in-memory hatk — lexicons, SQLite, feeds, and XRPC handlers — with no HTTP server, no PDS, and no indexer.

import { describe, test, expect, beforeAll, afterAll } from 'vitest'
import { createTestContext } from 'hatk/test'

let ctx: Awaited<ReturnType<typeof createTestContext>>

beforeAll(async () => {
  ctx = await createTestContext()
  await ctx.loadFixtures()
})

afterAll(async () => ctx?.close())

Test context API#

Testing a feed#

test('returns statuses in reverse chronological order', async () => {
  const feed = ctx.loadFeed('recent')
  const result = await feed.generate(ctx.feedContext({ limit: 10 }))
  expect(result.items).toHaveLength(6)
})

test('respects limit and cursor', async () => {
  const feed = ctx.loadFeed('recent')
  const page1 = await feed.generate(ctx.feedContext({ limit: 3 }))
  expect(page1.cursor).toBeDefined()

  const page2 = await feed.generate(ctx.feedContext({ limit: 3, cursor: page1.cursor }))
  expect(page2.items).toHaveLength(3)
})

Testing an XRPC handler#

test('returns profile for known user', async () => {
  const handler = ctx.loadXrpc('xyz.statusphere.getProfile')
  const result = await handler.handler({
    params: { actor: 'did:plc:alice' },
  })
  expect(result.handle).toBe('alice.test')
})

Fixtures#

Fixtures are YAML files in test/fixtures/ that populate the in-memory database before tests run. Each file is named after the table it populates.

Account fixtures#

Create a _repos.yaml to register test accounts with handles. This file is loaded first, before any collection fixtures:

# test/fixtures/_repos.yaml
- did: did:plc:alice
  handle: alice.test
- did: did:plc:bob
  handle: bob.test
- did: did:plc:carol
  handle: carol.test

If a DID appears in a collection fixture but not in _repos.yaml, it is auto-registered with a default handle (<did-suffix>.test).

Collection fixtures#

A file named after a collection inserts records into that collection. Only did is required — uri and cid are auto-generated if omitted:

# test/fixtures/xyz.statusphere.status.yaml
- did: did:plc:alice
  status: "\U0001F680"
  createdAt: $now(-5m)

- did: did:plc:bob
  status: "\U0001F9D1\u200D\U0001F4BB"
  createdAt: $now(-10m)

Use the rkey field when a record needs a specific record key (e.g., singleton records like profiles) or when other records reference it by URI:

# test/fixtures/app.bsky.actor.profile.yaml
- did: did:plc:alice
  rkey: self
  displayName: Alice

# test/fixtures/fm.teal.alpha.feed.play.yaml
- did: did:plc:alice
  rkey: '1'
  trackName: Blinding Lights

Without rkey, URIs are generated using the record's index (at://<did>/<collection>/0, at://<did>/<collection>/1, etc.).

Custom table fixtures#

A YAML file whose name doesn't match a known collection creates a custom table with VARCHAR columns derived from the first record's keys:

# test/fixtures/my_lookup_table.yaml
- key: foo
  value: bar
- key: baz
  value: qux

The $now helper#

Use $now in fixture values to generate timestamps relative to the current time:

This keeps fixtures time-relative so tests for "recent" feeds and time-based sorting always work.

Integration tests#

Integration tests use startTestServer() to boot a full HTTP server on a random port:

import { describe, test, expect, beforeAll, afterAll } from 'vitest'
import { startTestServer } from 'hatk/test'

let server: Awaited<ReturnType<typeof startTestServer>>

beforeAll(async () => {
  server = await startTestServer()
  await server.loadFixtures()
})

afterAll(async () => server?.close())

test('GET /xrpc/dev.hatk.getFeed returns items', async () => {
  const res = await server.fetch('/xrpc/dev.hatk.getFeed?feed=recent&limit=5')
  const data = await res.json()
  expect(data.items.length).toBeGreaterThan(0)
})

Test server API#

The test server extends the test context with: