Controller configuration and journals

Version 0.2.0 Updated Nov 27, 2025

CmdMox offers configuration hooks that surface through both the fixture and the context-manager API:

  • verify_on_exit (default True) automatically calls verify() when a replay phase ends inside a with CmdMox() block. Disable it when you need to manage verification manually. Verification still runs if the body raises; when both verification and the body fail, the verification error is suppressed so the original exception surfaces.
  • max_journal_entries bounds the number of stored invocations (oldest entries are evicted FIFO when the bound is reached). The journal is exposed via cmd_mox.journal, a collections.deque[Invocation] recorded during replay.

The journal is especially handy when debugging:

exercise_system()
assert [call.command for call in cmd_mox.journal] == ["git", "curl"]
# Verification will run during fixture teardown.

To intercept a command without configuring a double—for example, to ensure it is treated as unexpected—register it explicitly. Any invocation of a registered command without a matching double will be reported as unexpected during verification:

cmd_mox.register_command("name")

CmdMox creates the shim at replay start (or immediately when registration occurs during an active replay) so the command is routed through the IPC server, even without a stub, mock, or spy. Shims are cleaned up automatically during fixture teardown.