Testing

The kit has 1121 unit tests, run with Vitest. They take about ten seconds and need no browser, no FFmpeg, no voice model and no network.

bun run test            # run everything once
bun run test:watch      # re-run on every save
bun run coverage        # with a coverage report (also written to coverage/index.html)
bun run check           # type-check, then the tests: what CI runs
bun run test:mutate     # break the code on purpose and confirm the tests notice
bun run test:clean      # install, check and render from exactly what git holds

What is tested

The tests live in tests/unit/, in the same folders as the source: one folder per layer.

Coverage is about 92% of statements. src/cli/ shows as 0% in the report because its tests start a real bun process, which the coverage tool cannot see into; it is covered by cli.test.ts and config.test.ts.

What is not tested here

These tests check what the kit asks for, not what the tools do with it:

• that Chromium paints an overlay where the stage placed it
• that FFmpeg produces a playable file from the command line it was given
• that Kokoro reads a line well
• how any of it looks or sounds

For those, render the example (bun run example) and look at the result. A person has to listen to it; nothing automatic can. The release checklist lists every level of real-use testing, from the example to a trial on a real product.

How the outside world is replaced

Two things are real on purpose: serve.test.ts starts the real server on a free local port, and cli.test.ts and config.test.ts start a real bun process. Both are fast and both would be easy to fake wrongly.

Mocking run

Every program the kit starts goes through one function, so one mock replaces them all:

const run = vi.fn<(cmd: string, args: string[]) => Promise<string>>()
vi.mock('../../../src/core/util.ts', async (original) => ({
  ...(await original<typeof import('../../../src/core/util.ts')>()),
  run,
}))
const { encode } = await import('../../../src/render/encode.ts')     // import after the mock

A test then makes run answer like the tool would, and asserts on the arguments:

it('applies one fixed gain that brings the mix to the target', async () => {
  fakeFfmpeg(-22, -6)                                    // measured loudness, peak
  await encode(input({ clips: [{ file: 'a.wav', at: 0 }] }))
  expect(filterOf(call(2))).toContain('volume=6.00dB,alimiter=limit=0.84:level=false')
})

Testing the stage

The stage's waits are real setTimeout calls, so stage tests use fake timers and a clock derived from them. Times are then exact:

it('logs a click sound for the moment the pointer arrives', async () => {
  const { stage } = make()
  await vi.advanceTimersByTimeAsync(1000)
  await settle(stage.click(fakeLocator()))
  expect(stage.events).toEqual([{ t: 1550, kind: 'click' }])      // 1000 + the 550 ms glide
})

Positions are asserted in layout pixels, which is where the zoom arithmetic lives: an element at window (1000, 500) sized 200x100 has its centre at (1100, 550), and at zoom 1.25 the pointer must land on (880, 440).

Tests that guard a past mistake

Some tests exist because of a specific bug. Each has a comment saying so.

Checking that the tests can fail

A test that cannot fail proves nothing. tests/mutate.py breaks the code in 50 places, one at a time, runs the suite, and reports whether a test caught each:

caught    3 failing   loudness gain has the wrong sign
caught   14 failing   overlays ignore the page zoom
caught    4 failing   any sound licence is accepted
caught    1 failing   files outside the folder are served
...
50 of 50 mutations caught

It restores each file before moving on. When you add a rule that matters, add a line to its list.

Adding a test

1. Put it in the file for the module you changed. Name it for the behaviour, in plain words: 'never places a sound before the start of the video'.
2. Keep the logic in a pure function where you can (planDissolve, lateHolds, captionChunks), and test that directly. Use the fakes only for what truly needs the page or a process.
3. Test the limits: exactly on the boundary, one over, empty input.
4. If the test guards a real mistake, say which in a comment.
5. Break the code once and watch the test fail.
6. bun run check.