Unit Test Manager

Unit Test Manager

Overview

Authors and maintains unit tests: one unit, one process, no I/O. The decision that matters most is not how to write a new test — it is whether this change should produce a new test, edit an existing one, or leave the suite alone.

Is This the Right Skill?

Solitary and sociable tests are both unit tests. Replacing collaborators with doubles is a style choice; touching a real out-of-process dependency is what makes a test an integration test.

House Rules

Workflow

1. Discover the project's conventions before writing anything. Test root and layout, file and function naming, the runner command, the assertion library, and the existing helpers, builders, factories, and custom matchers. Reuse them. Never fabricate a parallel helper that duplicates one the codebase already has. Per-ecosystem conventions: references/framework-conventions.md
2. Find what already covers this behavior. Search by behavior, not by filename — the coverage may live in a differently named file.
3. Decide add / update / leave using the upsert matrix below.
4. Write the test, following references/unit-test-rules.md.
5. Observe it fail. For a bug fix, write the test first and watch it fail against the unfixed code. For code that already works, break the production line the test claims to cover, confirm the test fails for that reason, then restore. A test never observed failing is not yet a test.
6. Run the unit-level command and read the actual output. Report what you ran and what it printed. When dispatched by necturalabs:test-manager, run only that command — never the full suite, which collides with the other specialists running concurrently.
7. Triage anything else the run surfaced under House Rule 6, classifying each defect against ../test-manager/references/test-taxonomy.md — flaky, skipped, assertion-free, unfailable, tautological, copy-asserting, library-testing, change-detector, duplicated, obsolete, mislabeled, excessive setup.

When dispatched by necturalabs:test-manager

• Run only your level's command, never the full suite.
• Do not edit shared fixtures, factories, conftest.py, or any helper file outside your assigned paths — another specialist may be editing it right now. Report the change you need instead.
• Do not run the code review. Report back; the orchestrator runs it once over everything.

The Upsert Decision

Google's rule: strive for unchanging tests. After a test is written, it should not need to change as the system is refactored, extended, or fixed.

digraph upsert {
    "Behavior in scope" [shape=doublecircle];
    "Is the observable behavior different?" [shape=diamond];
    "Existing test covers it?" [shape=diamond];
    "Add a new test" [shape=box];
    "Leave existing tests alone" [shape=box];
    "Update the existing test" [shape=box];

    "Behavior in scope" -> "Is the observable behavior different?";
    "Is the observable behavior different?" -> "Update the existing test" [label="yes, requirement changed"];
    "Is the observable behavior different?" -> "Existing test covers it?" [label="no"];
    "Existing test covers it?" -> "Leave existing tests alone" [label="yes"];
    "Existing test covers it?" -> "Add a new test" [label="no"];
}

That matrix governs what a test asserts about product behavior. Repairing a test that is itself defective — no assertion, tautological, asserting copy, asserting a generated query, unfailable, flaky — is a different axis, and is always allowed regardless of what the product did. If the test is currently failing, establish why before repairing it: a defective test can still be failing for a real product reason, and repairing it green hides that. Confirm the product behavior is correct first, then repair, then observe the repaired test fail against the broken behavior. Name the defect from the catalogue (../test-manager/references/test-taxonomy.md) before you touch the test.

Deleting a test is legitimate in four cases: the behavior it covers no longer exists, it duplicates another test at the same level, it is itself defective with no salvageable assertion, or the behavior is now covered at a cheaper level and that replacement was written and observed failing first. Say which case applies. "It was failing" and "it was slow" are never reasons to delete a test.

What Belongs in a Unit Test

Full rules with sources: references/unit-test-rules.md

Rationalizations — All Rejected

Captured from agents writing unit tests without this skill.

Red Flags — Stop

• An expected value copied from the output of a library, formatter, or serializer
• An assertion containing a sentence, a label, or a full document
• A test asserting the code under test's own output back at itself
• More lines of mock setup than of arrange plus assert
• Editing an existing test's expected value while fixing a bug
• Reaching for reflection, @ts-ignore, or a private accessor to observe state
• A new test that has never been seen red

When Done

Report what you added, updated, and deleted with reasons; the failing observation for each new test; the exact command run and its output; and every defect triaged along the way.

If you are running as a subagent dispatched by necturalabs:test-manager, stop here and report back — it runs the full suite and the review once, over everything. Otherwise, including when test-manager invoked this skill inline in your own context, run the full suite yourself and then necturalabs:iterative-code-review over the changes — preceded by necturalabs:iterative-security-audit when the changes fall in that skill's trigger list (see its description; it is broader than auth and crypto), since it chains into the review. That run satisfies the orchestrator's completion gate rather than adding a second one. If the review returns test findings, fix them here under these rules rather than re-entering a test skill, so the review runs once per invocation chain.