Frontend Testing

A browser run costs seconds and a deployment; a unit test costs milliseconds and nothing else. Proving pure logic through the browser makes the suite slow without making it stronger, while proving navigation with unit tests proves nothing about the running page. Logic tests take pure logic, browser specifications take navigation and integration, and the route contract covers every address, so each risk is proved at the cheapest boundary that represents it.

Reviewed forWhich pure logic lacks a logic test, which navigation or integration lacks a browser specification, and which address lacks the route contract? Look in the test files beside the modules and under the tests roots.

Marked guidance: a reviewer answers this question.

The annotation, built by the proves helper the generated records file exports, names the lowest record the test verifies exactly as a backend test mark does, and a wrong identifier fails the consumer's type check against the generated union, and litespec model check reports it as mark-unknown where no type check ran. A title tag claims proof without anything reading it, so the written annotation is the link the builder counts.

The browser specification at apps/web/tests/expenses/list-expenses.spec.ts in the Claimwick example carries proves("scenario/list-expenses.listing-own-expenses-succeeds").

Checked bylitespec model check reports mark-unknown (level S) for a proves annotation naming no record a test may prove, or naming a journey.

Marked checkable: the tool named here checks it.

A test proves a scenario when it drives the use case through the page a person uses, so proof follows exercised behavior rather than a claim. Matching the page.goto target against the screen address templates is the deterministic reach the reader computes; a test that only clicks through navigation names no screen it proved on.

The evidence specification opens /expenses, the address of screen/claimwick-app.expense-list, which offers use-case/spending.list-expenses.

Checked bylitespec model check reports proves-unreached (level S) for a browser test whose page.goto targets match no screen offering the claimed scenario's use case.

Marked checkable: the tool named here checks it.

Reaching the screen shows the page opened; the assertion shows the ending the result promises. Holding the refusal code or the success text in the same test ties the proof to the named result, and a money-moving use case that a test only reads leaves completion unshown, so the test submits it.

The browser specification for scenario/list-expenses.listing-own-expenses-succeeds opens the expense list on screen/claimwick-app.expense-list and asserts the expenses table, the listed ending the success result result/list-expenses.listed promises.

Checked bylitespec model check reports proves-unreached (level S) for a browser test reaching the screen whose assertions in the same test hold neither the refusal code nor the success result's declared text or code.

Marked checkable: the tool named here checks it.

A refusal the test leaves unreached renders where no reader looks: it appears in a log, or nowhere at all. Reaching it and asserting it by its result's code proves two things at once: the page renders the refusal, and the code the page shows is the code the result declares. The scenario records the situation that reaches it, so the test documents how the refusal is provoked.

The refusal alert carries the code, so the assertion names it.

Reviewed forWhich declared refusals do no evidence specifications reach and assert by result code? Look in the evidence specifications.

Marked guidance: a reviewer answers this question.

An API test proves a business outcome faster and more steadily than a browser test, and a browser test is the only proof that a page offers the use case and renders its result. When both assert one scenario, marking both makes the slower test a second witness nobody needs and doubles the work when the scenario changes. The scenario whose risk is the outcome is proved at the API, and the one whose risk is what a person sees is proved in the browser.

scenario/list-expenses.listing-own-expenses-succeeds is proved by the browser specification at apps/web/tests/expenses/list-expenses.spec.ts, the cheapest boundary that shows what a person sees on the expense list. A scenario whose risk is a business outcome alone is proved at the API boundary instead.

Checked bylitespec model check reports proves-duplicate (level A) for a scenario with proves marks on more than one test.

Marked checkable: the tool named here checks it.

A journey is not a proof target: it is achieved through use cases, so a journey test proves the scenarios it drives, and journey coverage is computed from them. The journey annotation tells a reader which walk the test rehearses without claiming that the walk itself is proven.

The submit-and-reimburse walk carries journey: journey/submit-and-reimburse and proves the scenarios it drives and asserts on each screen it reaches.

Reviewed forWhich browser tests that walk several screens carry a journey annotation naming the journey and a proves mark for each scenario they drive and assert? Look in the browser tests and their annotations.

Marked guidance: a reviewer answers this question.

An assertion on internal state passes while the rendered page stays broken, because nothing ties the variable to what the reader sees. Asserting observable behavior in each state the test's situation reaches, from loading and empty through error, forbidden, not-found, pending, validation, and success, ties the test to the reader's view. The scenario states which states its situation reaches, so a logic test asserts only states its level reaches. The project records each state as a term with labels per language.

Reviewed forWhich tests assert internal state instead of observable behavior in the states their situation reaches? Look in the test assertions.

Marked guidance: a reviewer answers this question.

A mock is a claim about code the test no longer exercises. Mocking the generated contract types, an implementation-private function, or a library the stack names replaces the project's own contract or someone else's internals with the test author's guess of how they behave. The generated client boundary stays replaceable because it is an owned contract: the project wrote it, so the project can stand in for it.

Reviewed forWhich mocks replace generated contract types, private functions, or stack-named libraries? Look in the test doubles.

Marked guidance: a reviewer answers this question.

A mocked client replaces the generated code with a guess of what it returns, so the test proves the mock rather than the component. A network mock generated from the published contract answers the same HTTP request the browser would send, so the generated client stays in the path it takes in production and the component is tested through the client the page actually uses.

The workspace keeps one mock-generation command that regenerates them.

Reviewed forWhich component or logic tests needing HTTP answer without contract-generated network mocks, or with the generated client out of the path? Look in the component tests and the mock generation.

Marked guidance: a reviewer answers this question.

A test that depends on execution order or on leftover data fails for reasons unrelated to the change under review, and passes only when the suite runs in one order. Creating its own data, its own authentication context, and its own expected state makes each test runnable alone and in any order. A test spends no seeded record; it creates the record it needs.

Reviewed forWhich browser tests depend on another test's data, authentication context, or expected state? Look in the browser specifications.

Marked guidance: a reviewer answers this question.

The module mirror is the claim that makes a specification findable from a folder path: translate three names, land on the code. Without a check, the backend adds or renames a use case and the frontend tree silently stops matching, so the translation lands nowhere. A test asserting the mirror on every build, and naming no refused folder, keeps the translation true. The same test can also assert no import between use case folders or between modules, which no lint rule checks.

The structure check resolves each folder name against the backend's module tree.

Reviewed forWhich module folders does the structure test fail to resolve to backend use-case folders, and which refused folders does it name? Look in the structure test.

Marked guidance: a reviewer answers this question.

The command line is the interface every runner shares: the developer, the drill, and the integration job all invoke the same command. A check that runs only inside an editor plugin or a proxy runner leaves the next investigator with no way to repeat it. Addressable per route and per file, the suite also runs just the check under review instead of the whole suite.

Reviewed forWhich browser suites run outside the command line, or without per-route and per-file addressing? Look in the suite runner and the CI invocation.

Marked guidance: a reviewer answers this question.