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.tsunderpages/andcomponents/, 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--filterthat 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. Eachrendergets 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)andrenderComponent(name, { props, slot })give aScreen;screen.byRole,byText,byLabelfind things;press,hold,type,keyact;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, afunction, 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 asconstructoris 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>.duoto 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 onlyrenderComponentof 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, orDUOLITH_TEST_TIMEOUT_MS) has its session ended, so if it carries on, its nextrenderthrows instead of reaching the next test. A check that is still waiting when the body returns (a missingawait) 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, orDUOLITH_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.
- **
--jsonfollowsspec/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 asduolith build --jsonwould (diagnostic.schema.json), and any other problem{ ok: false, error }.
Alternatives considered
| Option | Why not |
|---|---|
| A DOM emulator (jsdom, happy-dom) instead of Chromium | Layout, focus, pointer events and the overlay layer differ from a browser; tests would pass that the app fails |
Expose Playwright's page and expect | Ties every app test to Playwright's names and timing rules; we could not change engine later |
Mock fetch | Couples tests to addresses and payload shapes; resources and actions are already named |
| Vitest or Jest as the runner | Another 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 teston every example that has tests (control-flow,data,components). - The CLI output contract gains
test.schema.jsonanddiagnostic.schema.json;spec/schemas/cli/commands.yamllists every command and its options, and a CLI test checks the binary accepts exactly those. @duolith/testingdepends on Playwright and stays private until the runtime's packages are published.