Duolith docs

0065. duolith test builds the project and runs *.test.ts files in Chromium with @duolith/testing

  • Status: Accepted (Mik, 17 Nov 2026)
  • Date: 2026-11-14
  • Decided by: toolchain work package (WP15), pending Mik's approval
  • Planning item: WP15 (toolchain), goal 1

Context

Apps had no way to test their screens. The kit and runtime had browser tests of their own, written straight against Playwright, but an app author should not need to know how a page is built, served or mounted to say "press Add and the todo is shown". Tests also need to stand in for the network: a resource that loads posts, an action that saves a like.

Decision

  • **duolith test [project] [--filter text] [--headed] [--json]** finds every *.test.ts under pages/ and components/, builds the project for the web into a temporary folder, runs the files one by one in Node with @duolith/testing, and removes the folder. No test files is an error, and so is a --filter that matches no test's name. It exits 1 when a test fails.
  • Tests run against the real build in Chromium, through Playwright. The build is served from memory at http://duolith.test; every other origin is refused, so a test never reaches the network by accident. Each render gets a fresh browser context: a phone window (390 by 844, two device pixels per CSS pixel), light colour scheme. Only Chromium for now; WebKit and Firefox are a flag away once there is a reason.
  • The API speaks the glossary, not Playwright. render(path) and renderComponent(name, { props, slot }) give a Screen; screen.byRole, byText, byLabel find things; press, hold, type, key act; screen.navigate, back; expect(found).toBeShown(), toHaveText, toHaveCount, toBeChecked, toBeDisabled, expect(screen).toHavePath, toHaveTitle. Every check waits up to five seconds before failing, as the runtime updates after a frame.
  • Mocks by key and by name. render(path, { resources: { posts: [...] }, actions: { like: fail("Offline") } }). A resource is mocked by the key it loads with; an action by the name the page declares it under (const like = action(...)). A mock is a value, fail(message, status), pending(), or a function of the input (an arrow, a function, or a method in shorthand; one whose source cannot be read back, such as a bound function, is refused with its name). In the page, mocks and recorded runs are kept in Maps, so a key such as constructor is only ever the test's. The test server swaps the runtime entry for a small shim that answers mocked keys and names and hands everything else to the real runtime; the build itself is unchanged.
  • A component renders in a harness page. For each component the CLI adds pages/duolith-test/components/<Name>.duo to the test build only, which places the component with the props and slot text the test gives. It imports the component under one generated name, so any file name works (fancy-label.duo). A harness page that does not compile is left out of the build, and only renderComponent of that component fails, saying why.
  • A page error fails the test ("The page threw: ..."), so an exception in a handler is never silent.
  • A test that misbehaves fails alone, and the run always ends. Each test has its own session, which follows its body through every await (AsyncLocalStorage); a test that times out (30 s, or DUOLITH_TEST_TIMEOUT_MS) has its session ended, so if it carries on, its next render throws instead of reaching the next test. A check that is still waiting when the body returns (a missing await) fails the test, and so does a rejection nothing handled while it ran. Loading a test file has the same time limit. The runner exits as soon as its report is written, so an open timer or socket cannot hold the run, and the CLI gives the whole run a deadline (20 minutes, or DUOLITH_TEST_DEADLINE_SECONDS), past which it stops Node's process group and still removes its scratch folder.
  • Discovery does not follow symbolic links, so it stays in the project and cannot loop.
  • **--json follows spec/schemas/cli/test.schema.json**: { ok, project, summary: { passed, failed, skipped, durationMs }, files: [{ file, tests: [{ name, outcome, durationMs, error? }] }] }; a build that fails gives its diagnostics as duolith build --json would (diagnostic.schema.json), and any other problem { ok: false, error }.

Alternatives considered

OptionWhy not
A DOM emulator (jsdom, happy-dom) instead of ChromiumLayout, focus, pointer events and the overlay layer differ from a browser; tests would pass that the app fails
Expose Playwright's page and expectTies every app test to Playwright's names and timing rules; we could not change engine later
Mock fetchCouples tests to addresses and payload shapes; resources and actions are already named
Vitest or Jest as the runnerAnother config and transform pipeline; node --test-style registration with our own reporter is a few dozen lines and keeps --json ours

Consequences

  • CI runs duolith test on every example that has tests (control-flow, data, components).
  • The CLI output contract gains test.schema.json and diagnostic.schema.json; spec/schemas/cli/commands.yaml lists every command and its options, and a CLI test checks the binary accepts exactly those.
  • @duolith/testing depends on Playwright and stays private until the runtime's packages are published.