Fluent API reference

The DSL methods closely mirror those described in the design specification. A few common ones are:

• with_args(*args) – require exact arguments.
• with_matching_args(*matchers) – match arguments using comparators.
• with_stdin(data_or_matcher) – expect specific standard input (str) or validate it with a predicate Callable[[str], bool].
• with_env(mapping) – inject additional environment variables into the invocation. The mapping is merged into the recorded Invocation.env, applied when custom handlers or canned responses run, and does not mutate the test process's os.environ. Conflicting keys override the caller-provided environment so passthrough commands honour the injected values.
• returns(stdout="", stderr="", exit_code=0) – static response using text values; CmdMox operates in text mode—pass str (bytes are not supported). Note: For binary payloads, prefer passthrough() or encode/decode at the boundary (e.g., base64) so handlers exchange str.
• runs(handler) – call a function to produce dynamic output. The handler receives an Invocation and should return either a (stdout, stderr, exit_code) tuple or a Response instance.

Example:

  def handler(inv: Invocation) -> tuple[str, str, int]:
      if "--fail" in inv.argv:
          return ("", "boom", 2)  # non-zero exit
      return ("ok", "", 0)

  cmd_mox.mock("tool").with_args("run").runs(handler)

• times(count) – expect the command exactly count times.

• times_called(count) – alias for times that emphasizes spy call counts.

• in_order() – enforce strict ordering with other expectations.

• any_order() – allow the expectation to be satisfied in any position.
• passthrough() – for spies, run the real command while recording it.
• assert_called(), assert_not_called(), assert_called_with(*args, stdin=None, env=None) – spy-only helpers for post-verification assertions.

Refer to the design document for the full table of methods and examples.