Code Coverage
Code coverage measures which lines, branches, and functions of the source code are exercised during
test execution. Blong uses V8's built-in coverage mechanism (via c8) to collect coverage data from
several packages across the monorepo and produce a single unified report.
How Coverage Is Collected
Blong collects coverage at two levels:
- Server-side (tap tests) — unit and integration tests that exercise the backend (handlers, orchestrators, adapters) directly through the JSON-RPC layer.
- Full-stack (Playwright tests) — browser tests that exercise both the server backend and the client-side React UI through a real browser.
Both mechanisms produce coverage data in V8's native coverage format, which is then aggregated by
c8 into a single lcov.info file and text report.
Server-Side Coverage (tap)
The server-side coverage pipeline works as follows:
Each package that contributes to coverage runs blong-dev test, which wraps tap with:
--allow-incomplete-coverage --coverage-report=none --timeout=180
The timeout is raised from tap's 30s default because an integration entry point loads both platforms
before its first test (measured at 13.5s of a ~26s file in realm/blong-access), which a cold CI
runner can push past 30s — reported as ✖ timeout! with no failing test. An explicit --timeout in
the invocation wins over it.
This tells tap to collect V8 coverage (which it does by default via @tapjs/processinfo) but skip
generating its own report. The raw V8 coverage JSON files land in .tap/coverage/ within each
package's directory.
Coverage Aggregation Script
The aggregation is orchestrated by core/blong-gogo/run-coverage.sh, invoked through the
ci-coverage Rush command. It:
- Stages a clean merge dir —
core/blong-gogo/.tap/coverage-mergeis wiped and rebuilt on every run, so stale coverage can never distort the aggregated report. - Merges raw V8 coverage JSON — copies every
*.jsonfrom each configured package's.tap/coverage/(tap + Playwright), prefixed by package name. - Chooses which packages contribute — the default set is
blong-gogo test blong-int-adapter blong-marine blong-suite. SetCOVERAGE_PACKAGES(space-separated names) to override, e.g.COVERAGE_PACKAGES="blong-gogo test blong-int-adapter". - Unifies on istanbul coverage maps —
c8converts the server V8 coverage to an istanbul map (--reporter json), which is merged with blong-browser's vitestcoverage/coverage-final.jsonbymergeCoverage.mjs. This matters becausec8cannot read istanbul maps (it would report vitest coverage as 0%); merging at the istanbul level keeps the real browser hits. - Renders
coverage/lcov.info+coverage/lcov-report/with istanbul from the repository root, so paths stay correct for the deployed report. - Guards the output — fails loudly when no coverage JSON is found, or when the report would
contain no
core/blong-gogocoverage (override withCOVERAGE_ALLOW_NO_GOGO=1), so a misleading browser-only report can never be produced silently.
The resulting coverage/lcov.info is consumed by GitHub Actions to post coverage summaries on pull
requests. c8 must run from the repository root so the lcov.info paths are correct.
Why Not --coverage-map
Passing --coverage-map with TypeScript paths causes tap to exit 1 with "No coverage generated"
because tsx compiles files in-memory and the V8 coverage data does not match the original .ts
file paths. The separate c8 step handles this correctly.
Rush Integration
The ci-coverage bulk command is defined in common/config/rush/command-line.json:
{
"commandKind": "bulk",
"name": "ci-coverage",
"summary": "Run code coverage reports",
"ignoreMissingScript": true,
...
}
Only @feasibleone/blong-gogo implements this script in its package.json:
"ci-coverage": "./run-coverage.sh"
In CI, rush ci-coverage runs after rush ci-test completes, so all test coverage data is
available before aggregation.
Full-Stack Coverage (Playwright)
Playwright tests collect coverage from both the server and browser simultaneously:
- Server-side: The
blong-dev playwright --coveragecommand setsNODE_V8_COVERAGEso the blong server process writes V8 coverage on exit. Coverage files are written to.playwright/coverage/v8/within the suite directory. - Browser-side: The
@feasibleone/blong-browser/playwrighttest object includes an automatic coverage fixture that uses Playwright'spage.coverage.startJSCoverage()API. Browser scripts served by Vite are mapped back to filesystem paths and written as V8 coverage JSON files. - Aggregation: After tests complete, both sets of coverage files are copied with a
pw-prefix intocore/blong-gogo/.tap/coverage/, where they are included in the unifiedc8 reportaggregation.
See the Playwright code coverage pattern for the full pattern reference including setup instructions, the URL-to-file mapping mechanism, and CI integration details.
Key Constraints
c8must run from the repository root so path mappings inlcov.infoare correct for subsequent GitHub Actions steps.- Use
-o <path>(not--reports-directory) for the output directory. - Coverage data must be on disk before
c8 reportruns — the tap-produced.tap/coverage/files must exist and be merged into a single temp directory.