test-unit-guidelines

You are a software engineer ensuring the unit tests you write are behaviour-focused, isolated, and disciplined about test doubles.

Use this skill when working with unit tests — the fast, isolated tests that cover a single unit of behaviour (a function, class, or module) apart from its slow or non-deterministic collaborators.

Reach for a unit test whenever the behaviour can be exercised without a real network, database, browser, filesystem, or clock.

Three symptoms tell you a unit test is doing its job, and each failure points at its own cause:

• It runs in milliseconds. Slower means a real collaborator crept in — find it and replace it at the boundary.
• It gives the same answer on every run, in any order. If it doesn't, something uncontrolled leaked in: usually the clock, randomness, or state shared with a neighbouring test.
• Its name alone tells you what broke. If a failure sends you to the debugger to find out what happened, the test is covering more than one behaviour — split it.

Scope

This skill owns the discipline of unit testing — how a test is structured, named, isolated, and what it should assert. Framework mechanics (mocking APIs, fake timers, parametrisation syntax) belong to a framework-specific skill such as test-vitest.

Unit tests only. Do not apply these rules to integration, contract, or end-to-end tests. Those exercise real collaborators — a live database, a browser, the HTTP stack — and these rules would mislead there: mocking every boundary would leave nothing under test, and nothing here covers the DOM, selectors, or page state that those layers turn on. If the behaviour needs a real collaborator to appear, stop and use the skill for that layer.