git:20260207.88c1f6e to git:20260714.4fd0952

+ ---

+ name: Testing

+ description: >

+ How to WRITE real, maintainable tests — assertions that fail when the code is broken,

+ stack-specific patterns for the three NXTG-Forge repos (vitest / node:test for

+ governance-mcp, cargo test for forge-orchestrator, vitest for forge-ui), and the ASIF

+ ship gates (test-count-never-decrease, no self-mocking). Use when asked to "add tests",

+ "write a test", "improve coverage", "fix flaky tests", "how do I test X", when turning a

+ hollow assertion into a real one, or when a change must not drop test quality. Backs the

+ crucible-detective agent — the construction counterpart to its fraud hunt.

+ when_to_use: >

+ add tests, write tests, improve coverage, fix a flaky test, mock vs real dependency,

+ test a governance-mcp tool / a Rust module / a React component, turn a hollow assertion

+ into a real one, run the NXTG-Forge test suites, pre-commit test gate, test-count-never-

+ decrease enforcement.

+ allowed-tools: Read, Grep, Glob, Bash

+ ---

+

+ # Testing — Writing Tests That Catch Real Bugs

+

+ A test that stays green while the code is broken is **worse than no test** — it

+ manufactures false confidence. This skill is the *construction* companion in the

+ crucible-detective trio:

+

+ - **core-testing** — principles (pyramid, AAA, behavior-over-implementation).

+ - **crucible-audit** — detection (the 8 fraud patterns + language matrix).

+ - **testing** (this) — construction: how to write a test that *does* fail on a real bug, in the actual NXTG-Forge stacks.

+

+ ## The one rule that makes a test real

+

+ Every test must **fail when you break the thing it names**. Before you commit a

+ test, prove it: change the production code to be wrong, re-run, confirm RED, revert.

+ An assertion that survives a deliberately broken implementation is theater.

+

+ ```js

+ // THEATER — passes even if computeHealth() returns garbage

+ expect(result).toBeDefined();

+ expect(result.score).toBeTruthy();

+

+ // REAL — pins the actual contract; breaks if the score math changes

+ expect(result.score).toBe(87);

+ expect(result.grade).toBe('B');

+ expect(result.dimensions).toHaveLength(5);

+ ```

+

+ The hollow tells to avoid, by stack (crucible-audit hunts these — don't write them):

+

+ | Stack | Never assert only | Assert instead |

+ |-------|-------------------|----------------|

+ | vitest / jest | `toBeDefined`, `toBeTruthy`, `not.toBeNull` | exact value, shape (`objectContaining`), length |

+ | node:test | `assert.ok(x)`, `assert(x !== null)` | `assert.strictEqual`, `assert.deepStrictEqual` |

+ | Rust | `assert!(x.is_some())`, `assert!(x.is_ok())` | `assert_eq!(x.unwrap(), expected)` |

+

+ ## Worked example — testing a governance-mcp tool

+

+ `servers/governance-mcp/` exports each tool as a plain function (`tools.mjs`) plus

+ `dispatchToolCall()`. Test the function directly, assert the real value:

+

+ ```js

+ // tests/health-score.test.mjs (vitest)

+ import { getHealth } from '../tools.mjs';

+

+ it('grades a clean project B and returns all 5 dimensions', async () => {

+ const h = await getHealth(fixtureRoot);

+ expect(h.score).toBeGreaterThanOrEqual(0);

+ expect(h.grade).toMatch(/^[A-F]$/);

+ expect(Object.keys(h.dimensions)).toHaveLength(5); // pins the contract

+ });

+ ```

+

+ Run it: `cd servers/governance-mcp && npx vitest run` (primary CI, 44/44).

+

+ ## NXTG-Forge stack cheat-sheet

+

+ | Repo | Runner(s) | Command |

+ |------|-----------|---------|

+ | forge-plugin `governance-mcp` | vitest (`tests/`) **and** node:test (`__tests__/`) | `npx vitest run` · `FORGE_TEST_MODE=1 node --test __tests__/health.test.mjs` |

+ | forge-orchestrator | cargo test (244 tests) | `cargo test` · `cargo test --test-threads=1` if locking conflicts |

+ | forge-ui | vitest | `npm test` · `npm run test:coverage` |

+

+ ## Mocking discipline

+

+ Mock the *boundary*, never the *thing under test*. Mock the network, the clock, the

+ filesystem when it's not what you're verifying — but if a test mocks the very function

+ whose behavior it claims to prove, it proves nothing (crucible Pattern 3: mock

+ proliferation). Prefer a real fixture directory / in-memory DB over a `vi.fn()` that

+ returns the answer you're asserting.

+

+ ```js

+ // WRONG — the mock IS the assertion; getHealth is never exercised

+ vi.mock('../tools.mjs', () => ({ getHealth: () => ({ score: 87 }) }));

+ expect((await getHealth()).score).toBe(87); // tautology

+

+ // RIGHT — run the real function against a controlled input

+ const h = await getHealth('/tmp/fixture-project');

+ ```

+

+ ## ASIF ship gates (enforced by crucible-detective + code-insurance-check)

+

+ 1. **Test count never decreases.** A PR that removes tests without a stated,

+ reviewed reason fails the gate. Deleting a failing test to go green = fraud.

+ 2. **No self-mocking** of the unit under test (above).

+ 3. **CRUCIBLE Gate 9 — live proof for high-blast providers.** A cross-machine

+ consumer (e.g. the CLX9 binary smoke) beats a mocked unit test. Mocked-green is

+ not shippable-green for anything another machine consumes.

+ 4. **New behavior ⇒ new test.** Every feature/fix commit that changes runtime

+ behavior lands with a test that would have caught the old bug.

+

+ ## Gotchas

+

+ - **`FORGE_TEST_MODE=1` is mandatory when importing `index.mjs`.** `index.mjs:167`

+ calls `await server.connect(transport)` at module load unless

+ `process.env.FORGE_TEST_MODE` is set — importing it in a test without the flag

+ **hangs on stdio**. vitest.config.mjs sets it via `env`; any `node --test` call

+ that touches `index.mjs` must prefix `FORGE_TEST_MODE=1` manually.

+ - **governance-mcp has two runners; they don't overlap.** `vitest.config.mjs`

+ `include: ['tests/**/*.test.mjs']` and explicitly EXCLUDES `__tests__/`, which

+ runs under node:test. Adding a test to the wrong dir means CI never runs it —

+ green board, zero coverage of your new code.

+ - **cargo file-locking tests are order-sensitive.** `task.rs` uses real file locks;

+ parallel test threads collide intermittently → flaky RED. Reproduce/fix flakes

+ with `cargo test --test-threads=1`, but keep the parallel run as CI truth.

+ - **Coverage is a map of what RAN, not what was verified.** 85% coverage with

+ `toBeDefined()` assertions proves nothing. Never quote a coverage % without the

+ assertion-quality read beside it (crucible Pattern 1 + 2).

+ - **Detection greps are Python-shaped.** If you copy crucible's `assert.*is not None`

+ greps to check your JS/Rust tests, they return 0 → false CLEAN. Translate to the

+ stack's hollow tells (table above) first. All three NXTG-Forge repos are non-Python.

+ - **`git add -A` in a release is banned here** (MEMORY): stage specific test files;

+ a stray `.claude/` or build artifact in a test commit breaks the release protocol.

+

+ ## Additional resources

+

+ - Fraud detection methodology + 8 patterns → [crucible-audit skill](../crucible-audit/SKILL.md)

+ - Principles (pyramid, AAA, coverage targets) → [core-testing skill](../core-testing/SKILL.md)

+ - Full NXTG-Forge strategy → [testing-strategy skill](../testing-strategy/SKILL.md)

+