snapshot of https://github.com/zulip/zulip.git @ 48c69911c7dd4e03b20552eb3bd77ad8151c1357 (2026-09-15)

.claude/skills/debug-node-coverage/SKILL.md

@@ -0,0 +1,83 @@
+---
+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:
+
+```JavaScript
+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
+
+```bash
+./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/.