# Unit Testing

> Complete or maximize unit test coverage for a specific TypeScript file in this repo. Use when: a test run is short of the 100% coverage threshold and you need to find and close the gap, or when deciding whether an uncovered branch is genuinely unreachable. For everyday test-writing conventions (AAA, mocking, placement, type safety), see .agents/rules/unit-testing.md instead — it loads automatically for any *.spec.ts file.

- Skill: `javierbrea/unit-testing` (Agent Skill)
- Install (CLI): `npx skillmds@latest add javierbrea/unit-testing`
- Raw SKILL.md: https://api.skillmd.com/api/skills/javierbrea/unit-testing/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: javierbrea (https://skillmd.com/u/javierbrea)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/javierbrea/unit-testing

---


# Unit Testing — closing coverage gaps

All packages enforce **100% coverage** (branches, functions, lines, statements) via `jest.config.js`'s `coverageThreshold.global`; any drop below fails the build. For AAA structure, mocking, placement, and type safety, follow `.agents/rules/unit-testing.md` — this skill only covers the coverage-completion workflow. For the general Nx-vs-direct command choice, see the root `AGENTS.md`.

## Completing coverage for a specific file

1. **Run the target test file with coverage** to get a baseline:
   ```bash
   cd packages/<package-name>
   pnpm test:unit <test-file>
   ```
2. **Find missing branches** by inspecting `packages/<package-name>/coverage/lcov.info` for `BRDA` entries with zero hits. Map uncovered branches to exact conditions in the source.
3. **Add tests** to hit uncovered branches. Re-run after each change. Repeat until resolved or justified.
4. **Prefer adding tests over suppressing coverage.**
5. If uncovered logic appears obsolete, **do not change production code** — present evidence and request user confirmation first.

## Handling unreachable or defensive branches

When a branch is genuinely unreachable at runtime and cannot be exercised through tests, mark it with an `istanbul ignore` comment that **justifies why**:

```typescript
/* istanbul ignore next -- Defensive guard: invalid parser state is impossible through public API */
```

Rules for `istanbul ignore`:

1. **Always include a justification** after the `--` separator.
2. **Prefer making code non-optional over ignoring it.** If a default is never exercised, remove it instead of adding an ignore comment.
3. **Only use for genuinely unreachable code.** If a branch can be triggered through a public API, write a test for it.
4. **Keep the ignore scope as narrow as possible.** Place on the specific line or branch, not on entire functions.