OpenParable
Skip to content
← Back to skills

Analyzing Coverage

Testing & Quality
analyzing-coverage

Analyzing Coverage is an Agent Skill for testing & quality published in the TriliumNext/Trilium repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Use when measuring or chasing Vitest/v8 code coverage in the Trilium monorepo — "what's below 100%?", "which files need tests?", "what lines of X are uncovered?", "take <area> to 100%", or feeding coverage gaps to test-writing agents. Provides one reusable analyzer (coverage.mjs) for lcov.info / coverage-summary.json / coverage-final.json, the correct commands to produce that data on Windows, and the known footguns. Pairs with writing-unit-tests.

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/TriliumNext/Trilium/blob/HEAD/.claude/skills/analyzing-coverage/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/analyzing-coverage, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

Analyzing coverage in Trilium

There is one coverage analyzer — coverage.mjs in this skill folder. Don't write a new throwaway parser; every past session that did (cov-analyze.mjs, cov-parse.mjs, cov-lines.mjs, cov-gaps.cjs) reinvented the same two operations. Use this instead.

node .claude/skills/analyzing-coverage/coverage.mjs <coverage-file> [summary|gaps] [options]

It auto-detects the format, so point it at whatever Vitest produced:

  • lcov.info — the default lcov reporter, so it's almost always already on disk. Supports both modes.
  • coverage-summary.json — from --coverage.reporter=json-summary. summary only (no per-line detail).
  • coverage-final.json — from --coverage.reporter=json. Supports both modes.

Two modes

summary (default) — list files below a threshold, worst-first, plus aggregate totals over the matched set. This is the "where's the coverage debt?" view.

# trilium-core services below 100%, worst first (measured through the server suite):
node .claude/skills/analyzing-coverage/coverage.mjs \
    apps/server/test-output/vitest/coverage/lcov.info \
    --filter packages/trilium-core/src/services

Options: --threshold N (default 100), --metric lines|branches|functions|any (default any — flag a file if any metric is below), --top N, --json.

gaps — for the file(s) matched by --filter, print the exact uncovered line numbers (statements + functions) and uncovered branch lines, compressed to ranges. This is the "what does my new test have to exercise?" view — feed it straight into a test-writing agent's prompt.

node .claude/skills/analyzing-coverage/coverage.mjs \
    apps/server/test-output/vitest/coverage/lcov.info gaps \
    --filter becca/entities/bnote.ts
# ### packages/trilium-core/src/becca/entities/bnote.ts — lines 78% (...)
#   uncovered lines:        163, 240-257, 266-267, ...
#   uncovered branch lines: 245, 249, ...

--filter takes a path substring; repeat it or comma-separate to match any (--filter src/services,src/entities). --json on either mode emits machine-readable output for workflows.

Producing the coverage data

trilium-core has no runner of its own — its coverage is measured through the apps/server and apps/standalone suites (both set allowExternal: true + a core include glob; see writing-unit-tests). Pick the suite that exercises your file:

Target areaSuite to runlcov lands at
apps/client/src/**clientapps/client/test-output/vitest/coverage/lcov.info
apps/server/src/**, packages/trilium-core/src/**serverapps/server/test-output/vitest/coverage/lcov.info

Run the suite (or a scoped subset) with coverage, then analyze the lcov:

# Whole package (slow but complete):
pnpm --filter @triliumnext/client test --coverage
pnpm --filter server test --coverage

# Scoped to specific specs (fast iteration). On Windows/sandbox, pnpm exec can
# EPERM — call the hoisted binary in the REPO-ROOT node_modules directly:
cd apps/server
CI=true node ../../node_modules/vitest/vitest.mjs run \
    ../../packages/trilium-core/src/becca/entities/bnote.spec.ts \
    --reporter=dot --coverage --coverage.reporter=lcov \
    --coverage.reportsDirectory=./test-output/cov-bnote
node ../../.claude/skills/analyzing-coverage/coverage.mjs \
    ./test-output/cov-bnote/lcov.info gaps --filter bnote.ts

Footguns (learned the hard way)

  • Always pass --reporter=dot for scoped runs — the project's configured html/@vitest/ui reporter can crash at end-of-run and abort coverage.
  • The v8 text reporter crashes (PARSE_ERROR remapping unrelated core files) on single-spec --coverage runs. Use lcov/json/json-summary and analyze with this script — never rely on the terminal table for a scoped run.
  • The per-file table row renders blank when a single included file is exactly 100% (cosmetic v8 quirk). This script reads the raw data, so it shows the real number.
  • Multi-file client runs must cd apps/client first. Running multiple specs from the repo root with --root apps/client triggers a vitest "failed to find the runner" crash; a single spec with --root is fine.
  • Isolated vs full-suite gaps: when you run only your spec, lines covered by other specs in the full suite show as uncovered. That's expected — only your assigned lines need to disappear. Don't chase the rest.
  • --coverage.reportsDirectory is relative to --root, so it can double a path prefix — pass a simple relative dir like ./test-output/cov-<slug>.
  • For provably-dead defensive branches, mark with /* v8 ignore next N -- reason */ rather than writing a fake test (sanctioned by writing-unit-tests).

Writing the tests

This skill only measures. To actually raise coverage — fixtures, the real-DB vs mocked-becca decision, import paths, component rendering — use the writing-unit-tests skill. The typical loop: run suite with --coverage → coverage.mjs … summary to pick the worst file → coverage.mjs … gaps --filter <file> to get the line list → write tests → re-run scoped with --coverage → gaps again until your lines are gone.

For a large fan-out (e.g. "take all of becca to 100%"), a Workflow that gives one agent per file its gaps line-list as the assignment works well — see the pattern this skill's analyzer was extracted from.