Write Unit Tests

Main exception

Use a more direct style mainly in brownfield code when all of these are true:

• introducing the DSL would force broad rewrites,
• team adoption cost is high,
• and the near-term payoff is not worth the disruption.

Even in brownfield code, prefer incremental DSL adoption around new work, painful tests, and flaky areas rather than copying the old style forever.

When to Use (and When NOT to)

Goal: maximize regression protection without coupling tests to implementation details.

Core Defaults

1. Default to DSL-driven testing for new code. Prefer business-language scenarios over framework-shaped tests.
2. Inside that DSL, prefer classic-style (Chicago school) tests. Test observable behavior, not internal choreography.
3. Use a fast in-memory or domain driver first. Multiple drivers are optional, not required.
4. Use real in-memory collaborators when they are deterministic and fast.
5. Prefer fakes over mocks for external boundaries you must isolate.
6. Use mocks only as a last resort for outbound commands/side effects you cannot observe otherwise.
7. Structure every test with Arrange, Act, Assert, even when the scenario is wrapped in a business-language layer.
8. Treat coverage as a diagnostic, not the goal.

Quick Decision Trees

"What should I unit test first?"

What has the highest payoff?
├─ Important business behavior in new code    → Start with a small business DSL
├─ Complex business rules or branching     → Test first
├─ Code with frequent regressions          → Test first
├─ Public behavior used by many callers    → Test first
├─ Simple pass-through glue                → Lower priority
└─ Trivial code with no real risk          → Maybe skip

"Should I write the test directly or via a DSL?"

What context am I in?
├─ New feature or greenfield area            → Use a DSL by default
├─ Long-lived test suite                     → Use a DSL by default
├─ Need scenarios to read like specifications → Use a DSL by default
├─ Brownfield code, high migration cost      → Be pragmatic; direct tests may be fine
└─ Tiny trivial logic with no useful language → Direct test is acceptable

"Should I use a real dependency, fake, or mock?"

What kind of dependency is it?
├─ Pure, deterministic, in-memory          → Use the real dependency
├─ External but easy to model in memory    → Use a fake
├─ Need canned answers only                → Use a stub
├─ Need to observe calls after execution   → Use a spy
└─ Need strict interaction verification     → Mock as last resort

"What kind of assertion should I write?"

What do I care about?
├─ Final state / returned value            → State assertion
├─ Error condition or boundary case        → Exception / error assertion
├─ Side effect recorded in fake/spy        → Verify observable effect
└─ Internal call order or private methods  → Usually don't test that

"Why is this test fragile?"

Why does it break too often?
├─ Fails after harmless refactor           → Coupled to implementation
├─ Mocks every collaborator                → Over-mocked, too isolated
├─ Huge setup hides the intent             → Obscure Arrange phase
├─ Many unrelated assertions               → Assertion Roulette
└─ Depends on clock, DB, file system       → Not a true unit test

The Unit-Test Workflow

1. Pick one behavior with business value.
2. Name it in business language first. Create a small business DSL before writing low-level test code.
3. Choose the smallest meaningful scope that still exercises real logic.
4. Use a fast in-memory or domain driver as the default execution path.
5. Keep collaborators real if they are fast, deterministic, and in-memory.
6. Replace only unstable boundaries with a fake, stub, spy, or rare mock.
7. Write one clear Act step.
8. Assert on outcomes visible to the caller or domain.
9. Refactor the test for readability without changing intent.
10. Check for smells before adding more tests.

DSL-First Unit Testing

When the code is new or expected to live a long time, prefer this stack:

Test case / scenario → small business DSL → in-memory driver → system under test

Why this should be the default:

• scenarios read like executable specifications,
• tests stay decoupled from HTTP/UI/framework details,
• the same language can often scale beyond unit level later,
• and teams avoid locking their test suite to implementation noise.

If you need the full architecture and migration guidance, use dsl-driven-testing together with this skill.

AAA / Four-Phase Structure

Arrange → Act → Assert → (Optional) Teardown

• Arrange: only the data and collaborators needed for this scenario
• Act: ideally one triggering call
• Assert: verify the business-relevant outcome
• Teardown: only when a shared resource truly needs cleanup

Test Double Selection

Default order: real dependency → fake → stub/spy → mock.

Example Guidance

• Prefer DSL-first tests in new code: test case → small business DSL → in-memory driver → SUT.
• Prefer observable outcomes over interaction verification.
• Keep one Act step per scenario.
• Treat coverage as a clue, not proof of quality.

For worked examples, see:

• examples/SERVICE-EXAMPLE.md
• ../dsl-driven-testing/SKILL.md

Anti-Patterns

The Four Quality Pillars

Evaluate each test against these four properties:

If a test scores poorly on refactoring resistance, redesign it before adding more assertions.

Review Checklist

• Does the test describe a business-relevant behavior?
• In new code, should this be expressed through a small business DSL first?
• Is the Act phase a single meaningful trigger?
• Are assertions about outcomes instead of internals?
• Could a real in-memory dependency replace a mock?
• Would the test survive a harmless refactor?
• Is the setup shorter than the behavior being tested?
• Is the test deterministic and fast locally?
• Does it avoid using coverage as the definition of quality?

AI-Specific Guidance

Coding agents often generate too many mocks. When writing tests with AI assistance:

1. Explicitly ask for DSL-driven tests in new code.
2. Ask for a small business DSL first, then a fast in-memory driver.
3. State “prefer classic-style assertions and fakes over mocks.”
4. Forbid verification of private calls or call order unless strictly necessary.
5. Require AAA layout and one behavior per test.
6. Ask the agent to explain why each test double is needed and why a DSL was or was not introduced.

Reference Documentation

Sources

Primary Source

• User-provided literature review on unit testing — local reference used to synthesize the guidance in this skill

Key Authors and Concepts Reflected

• Gerard Meszaros — xUnit Test Patterns (AAA / Four-Phase, test doubles, test smells)
• Vladimir Khorikov — Unit Testing: Principles, Practices, and Patterns (four quality pillars, classic style, refactoring resistance)
• Martin Fowler — test doubles taxonomy and mocking guidance
• Empirical findings summarized in the review: TDD/testing improves quality, excessive mocking increases fragility, and code coverage is useful as a signal but weak as a target