Get Notified the Moment Your Tests Finish

On the matte-black Status Light, three domed lenses provide red, amber and green positions for test results. The physical layout fits the job, but its catalogue facts do not confirm an automation interface, so begin with a software notifier.

How do you wrap a test command with a notification?

Put the real test command inside a small shell function or script. Run it without hiding its output, save its exit status immediately, call the notification adapter and return the original status to the shell. The wrapper must not turn a failing suite into a successful command just because the notifier worked.

Pass arguments as separate shell arguments, not a string evaluated a second time. Start with one named suite and print the start time, working directory and command in a log so a later alert can be traced.

How do you signal pass versus fail differently?

Map a completed zero exit status to pass and a completed nonzero status to failure, unless the test runner documents a richer result that matters. Notification failure is a separate unknown state. Never display green when the suite did not start, was interrupted or produced an unreadable report.

Include the suite name and finish time in a companion terminal message. Colour alone cannot distinguish a failed assertion from a broken test environment.

How does this work with watch-mode runners?

A watch process may stay alive through many cycles, so wrapping the outer process only reports when watch mode finally exits. To signal every cycle, use a documented reporter or lifecycle callback from the actual test runner, or run explicit one-shot test commands.

Debounce rapid reruns and attach a run identifier to each result. An older slow run should not overwrite a newer result. If the runner cannot expose a reliable cycle boundary, keep notifications off rather than scraping arbitrary console phrases.

When is a sound better than a light?

Sound is useful when a person has stepped away and one important suite finishes rarely. A visual signal is quieter in shared rooms and can remain visible until reviewed. Desktop notifications provide useful text but can disappear among unrelated alerts.

The Status Light could hold the latest known test state only after its real control path is confirmed. Test the wrapper with intentional pass, failure, interruption and notifier outage cases. Keep the terminal exit status as the source of truth. Prevent overlapping wrappers from writing one shared file without coordination. Give each suite or worktree its own record, then aggregate deliberately if one indicator serves several runs. On restart, mark abandoned in-progress records unknown instead of preserving amber forever.