Capability 014: TypeScript Builds and Coverage

Status: Accepted

Context

The programmed tests and the scenarios measure the same code, the sources below src/, but run it in two places. The programmed tests run in Node, and their runner instruments the sources it loads. The scenarios run in a browser against the bundle of the build, which Node never sees. They count only if that bundle is instrumented and the counts are collected from the browser and merged with those of the programmed tests. A line counts as covered if a programmed test or a scenario reaches it. App.tsx, for example, is rendered by no programmed test, only by a scenario that opens the page. The server that delivers the bundle to the browser is no code of the project and does not count.

An instrumented bundle is larger and slower and must never reach a user. It therefore needs a directory of its own, apart from the production bundle. This capability defines the builds and how the TypeScript profile measures the figure of capability 011.

References

• Capability 011: Test Kinds and Coverage

Details

Builds:

Build	Output	Configuration	Used by
Production	dist/	Minified, no instrumentation	build, preview, bdd-test
Coverage	build/coverage/	As Production, plus instrumentation	coverage

The container image builds its production bundle on its own and is not affected.

Where the counts come from:

	Programmed tests	Scenarios
Where the code runs	Node, with a simulated DOM	A real browser
What runs	The modules a test imports	The whole bundle, as a user gets it
How it is counted	The test runner instruments each module as it loads it	The coverage build is instrumented and counts in the browser
What the counts refer to	The lines of the sources	The lines of the bundle, mapped back to the sources before merging

Coverage:

Aspect	Value
Metric	Lines
Counted	The programmed tests, and the scenarios against the coverage build, merged into one report
Excluded	src/main.tsx, the tests, and the generated scenario code

Functional Requirements

1. coverage runs the programmed tests and the scenarios against the coverage build and reports their counts together, as Details defines.
2. After each scenario, the counts of the browser are collected for the figure.
3. build, preview, bdd-test, and the container image use a bundle without instrumentation.
4. Before the counts are merged, both refer to the lines of the sources, as Details defines.

Non-Functional Requirements

None.

Technical Requirements

1. Vite builds, Vitest runs the programmed tests, Playwright with playwright-bdd runs the scenarios, and nyc maps and merges the counts. The testing and TypeScript guidelines prescribe Vitest and the scenario runner, and the TypeScript CI image provides the browser.

Error Handling

None.

Out of Scope

• What capability 011 defines for every language
• Coverage in browsers other than the one the scenarios use

Acceptance Criteria

1. TypeScript frontend: the programmed tests count in the format of Decision 1.
2. TypeScript frontend: coverage builds the coverage build into its directory of Details and runs the scenarios against it. build writes dist/ without instrumentation.
3. TypeScript frontend: the scenario code collects the browser's counts after each scenario.
4. Generated TypeScript frontend, a function reached only by a scenario: make coverage reports it as covered (manual test test/manual/generated_coverage.md).
5. Generated TypeScript frontend, a source file that the programmed tests cover completely: make coverage reports it as covered completely (manual test test/manual/generated_coverage.md).

Decisions

1. istanbul for Vitest and the bundle. Merging needs one format. The browser's counts of an instrumented bundle are istanbul's, so Vitest uses istanbul as well. Consequence: Vitest gives up the V8 provider, which needs no instrumentation.
2. A coverage build apart from the production bundle. An instrumented bundle must never be served to a user or shipped in the image. Consequence: coverage builds the frontend a second time.