Skip to content

docs(doubles): document bashunit::unmock and the double lifecycle #899

Description

@Chemaclass

Context

bashunit::unmock is a public helper (src/test_doubles.sh:26) that removes a
mock or spy and cleans up its state files. It is missing from
docs/test-doubles.md — the page a user or agent reads to learn the doubles API.

Where it currently appears:

  • docs/globals.md:101 — mentioned only in passing, in a note about the
    bashunit:: prefix
  • src/runner.sh:2059 — the runner's own per-test cleanup
  • tests/unit/coverage_core_test.sh:284 — one real usage in the suite

It is absent from docs/test-doubles.md, docs/public/bashunit-skill.md and
docs/ai-agents.md.

Proposal

Add a ## bashunit::unmock section to docs/test-doubles.md alongside mock and
spy, covering:

  • signature bashunit::unmock "function" and what it removes (the function
    override plus the spy's times/params files)
  • that it is a no-op for a name that was never mocked
  • when you actually need it: the runner already unmocks after each test, so
    the case that matters is undoing a double established in
    set_up_before_script, or re-mocking the same command differently inside one
    test

That last point is the real documentation gap: without it a reader cannot tell
whether they are supposed to call unmock in every tear_down.

Why this matters for agentic coding

The per-test auto-cleanup is invisible from the docs, so an agent reading only
docs/test-doubles.md has two failure modes: adding defensive bashunit::unmock
calls to every tear_down (noise, and it reads as if leakage were a real risk),
or not knowing the helper exists when a set_up_before_script mock genuinely does
leak between tests. Stating the lifecycle once removes both.

Acceptance criteria

  • bashunit::unmock documented in docs/test-doubles.md with an example
  • Lifecycle stated explicitly: automatic after each test, manual for
    set_up_before_script doubles
  • Added to docs/public/bashunit-skill.md and docs/ai-agents.md doubles
    sections
  • make lint green

Metadata

Metadata

Assignees

Labels

documentationImprovements or additions to documentationgood first issueGood for newcomers

Type

No type

Projects

Status
Done

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions