Context
Snapshot files are named after the test file and test function
(bashunit::snapshot::resolve_file, src/assert_snapshot.sh:91-116). Rename or
delete a test and its snapshot file stays on disk forever. Nothing reads it,
nothing reports it, and it survives every run silently.
The repo itself carries a tests/acceptance/snapshots/ directory large enough
that a dead file there is not noticeable by eye.
Proposal
Report snapshot files that no test resolved during the run. The runner already
knows every resolved path (it computes one per assert_match_snapshot call), so
the check is: collect resolved paths, list snapshots/ directories under the
tested paths, report the difference.
Surface it behind a flag rather than always-on, since a partial run (--filter,
--shard) legitimately resolves only a subset — an unconditional warning would
be noise most of the time. Something like --snapshot-report-unused, meaningful
only on a full run.
Deliberately out of scope: deleting the files. Report only. A wrong deletion here
is unrecoverable, and the existing warning that a missing snapshot never fails
applies with full force.
Why this matters for agentic coding
Renaming a test function is a routine refactor an agent performs, and it silently
orphans the snapshot every time. The cost compounds: the next agent reading
snapshots/ cannot tell which files are live, so it cannot safely reason about
what is covered, and it may re-record against a stale file whose owning test no
longer exists. A report turns invisible drift into a line of output.
Acceptance criteria
Context
Snapshot files are named after the test file and test function
(
bashunit::snapshot::resolve_file,src/assert_snapshot.sh:91-116). Rename ordelete a test and its snapshot file stays on disk forever. Nothing reads it,
nothing reports it, and it survives every run silently.
The repo itself carries a
tests/acceptance/snapshots/directory large enoughthat a dead file there is not noticeable by eye.
Proposal
Report snapshot files that no test resolved during the run. The runner already
knows every resolved path (it computes one per
assert_match_snapshotcall), sothe check is: collect resolved paths, list
snapshots/directories under thetested paths, report the difference.
Surface it behind a flag rather than always-on, since a partial run (
--filter,--shard) legitimately resolves only a subset — an unconditional warning wouldbe noise most of the time. Something like
--snapshot-report-unused, meaningfulonly on a full run.
Deliberately out of scope: deleting the files. Report only. A wrong deletion here
is unrecoverable, and the existing warning that a missing snapshot never fails
applies with full force.
Why this matters for agentic coding
Renaming a test function is a routine refactor an agent performs, and it silently
orphans the snapshot every time. The cost compounds: the next agent reading
snapshots/cannot tell which files are live, so it cannot safely reason aboutwhat is covered, and it may re-record against a stale file whose owning test no
longer exists. A report turns invisible drift into a line of output.
Acceptance criteria
--filter/--shard) makes thereport meaningless — or the flag refuses to run alongside them
docs/snapshots.md+docs/command-line.mdmake sa+make lintgreen