debug-node-coverage - SKILL.md Agent Skill

name: debug-node-coverage description: "Debug node test coverage failures. Use when ./tools/test-js-with-node --coverage reports lines missing coverage."

Debugging Node Test Coverage Failures

When ./tools/test-js-with-node --coverage fails with lines missing coverage, follow this process.

Understanding the error

The error looks like:

ERROR: web/src/filter.ts no longer has complete node test coverage
  Lines missing coverage: 90, 225, 1780

This means the listed lines in the source file were never executed by any test. Zulip enforces 100% line coverage for all files not listed in EXEMPT_FILES in tools/test-js-with-node.

Step 1: Read the uncovered lines

Read the source file at the reported line numbers. Classify each uncovered line:

Testable code: A branch or path that can be reached with the right test input. Fix by adding tests.
Defensive/unreachable assertion: Code like assert(false, ...) that exists only as a safety net. These are automatically excluded by COVERAGE_EXCLUDE_LINES in tools/test-js-with-node.
Code that is unreachable or otherwise not worth testing: Mark with // istanbul ignore next comments. Use sparingly.

Step 2: Find the test file

Tests for web/src/foo.ts live in web/tests/foo.test.cjs. Read the test file to understand existing patterns before adding new tests.

The common predicate test pattern:

const predicate = get_predicate([["operator", operand]]);
assert.ok(predicate({...message that should match...}));
assert.ok(!predicate({...message that should not match...}));

Step 3: Add tests for testable code

Add tests near related existing tests. Follow the existing style exactly. Tests should exercise the behavior, not the implementation detail — name and locate tests based on what they verify, not which internal code path they hit.

Step 4: Handle unreachable assertions

Use // istanbul ignore next where appropriate, being sure that you think the codebase is better without test coverage for this case.

Step 5: Verify

./tools/test-js-with-node --coverage

This runs all JS tests in serial mode with istanbul/nyc instrumentation and checks that non-exempt files have 100% line coverage.

For faster iteration, you can run an individual test and analyze the coverage output files to see whether it covered a target line.

Key files

tools/test-js-with-node — Test runner, coverage enforcement, EXEMPT_FILES list, COVERAGE_EXCLUDE_LINES patterns
tools/coveragerc — Python equivalent (for reference on pattern style)
web/tests/*.test.cjs — All JS test files
var/node-coverage/ — Generated coverage reports (HTML viewable at http://zulipdev.com:9991/node-coverage/index.html), but you can also access in var/node-coverage/.