Skip to content
Tutorials Center
My learning

Topics

Lesson 30 of 38 ยท Testing Real Projects

Testing Command-Line Programs

Test Python command-line tools with pytest: capture printed output with capsys, call main(argv), check exit codes and SystemExit, fake stdin, and assert on log messages with caplog.

A command-line program has three kinds of input (arguments, standard input, environment) and four kinds of output (standard output, standard error, the exit code, and files it writes). Testing it looks daunting if the only way to run it is to start a new process. The trick is to structure the program so that its logic can be called as a normal function, and then use pytest's capture fixtures to check what it printed.

This lesson shows a design that makes CLIs easy to test, then covers capsys, exit codes, standard input, caplog for logging and the subprocess approach for true end-to-end checks.

Design for testability: main(argv)

The usual script pattern hides everything behind if __name__ == "__main__":. A testable version takes the argument list as a parameter and returns an exit code:

Python
import argparse, sys

def build_parser():
    p = argparse.ArgumentParser(prog="wc-lite")
    p.add_argument("path")
    p.add_argument("--words", action="store_true")
    return p

def main(argv=None):
    args = build_parser().parse_args(argv)
    ...
    return 0

if __name__ == "__main__":
    sys.exit(main())

argv=None makes argparse read sys.argv in real use, while tests pass an explicit list: main(["notes.txt", "--words"]). No process spawning, no patching of sys.argv.

flowchart LR
    T["test"] -->|"main(['file.txt', '--words'])"| M["main(argv)"]
    M -->|"print()"| O["stdout / stderr"]
    M -->|"return code"| T
    T -->|"capsys.readouterr()"| O

The test calls the function directly and reads the captured output afterwards.

capsys: read what was printed

The capsys fixture captures everything written to sys.stdout and sys.stderr during the test. capsys.readouterr() returns a named tuple (out, err) and clears the buffers. For output written by C extensions or subprocesses directly to the file descriptors, use capfd instead.

Python Test a small CLI with capsys

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Checking err == "" is a cheap and valuable assertion: a command that succeeds should usually be silent on stderr.

Exit codes and SystemExit

argparse calls sys.exit(2) after printing a usage error, and many scripts call sys.exit(1) on failure. sys.exit raises SystemExit, which pytest lets you catch with pytest.raises. The code is in excinfo.value.code.

Python Asserting on SystemExit and usage errors

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

sys.exit("message") prints the message to stderr and exits with status 1, but excinfo.value.code holds the string, which is why the test compares to the text.

Standard input and prompts

Programs that read input() or sys.stdin are tested by replacing the input. Two simple tools:

  • monkeypatch.setattr("builtins.input", lambda prompt="": "yes") for single answers; use an iterator for several: answers = iter(["Ada", "36"]); monkeypatch.setattr("builtins.input", lambda p="": next(answers)).
  • monkeypatch.setattr("sys.stdin", io.StringIO("line1\nline2\n")) for programs that loop over stdin.
Python Faking input() and sys.stdin

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Logging: caplog

Well-behaved tools log through the logging module rather than print. The caplog fixture collects log records during a test so you can assert on level and message, without them appearing on screen:

Python
import logging

def test_warns_on_old_format(caplog):
    with caplog.at_level(logging.WARNING):
        convert("legacy.cfg")
    assert "legacy format" in caplog.text
    assert caplog.records[0].levelname == "WARNING"

caplog.at_level(level, logger="name") sets the level for a block, caplog.record_tuples gives (logger, level, message) triples, and caplog.clear() resets between phases.

End to end: run the real command

Calling main() does not prove that the entry point, shebang or python -m package wiring works. Keep one or two process-level tests that run the real program with subprocess.run([sys.executable, "-m", "wclite", ...], capture_output=True, text=True) and check returncode, stdout and stderr. They are slower and more brittle than function-level tests, so use them as a thin smoke layer. (The in-browser Python cannot start subprocesses, so run these on your own machine.)

For frameworks that provide their own test helpers, such as click.testing.CliRunner or typer.testing.CliRunner, the idea is the same: invoke the command in-process, then inspect result.exit_code and result.output.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does capsys.readouterr() return?

    It returns (out, err) for everything written since the previous call, and resets the capture.
  2. 2. Why give main() an argv parameter that defaults to None?

    parse_args(None) reads sys.argv, while parse_args([...]) parses the given list, so the same code is testable and real.
  3. 3. How do you check that a function exits with status 2?

    sys.exit raises SystemExit; the status is available in the exception's code attribute.
  4. 4. Which fixture lets you assert on warnings and errors written with the logging module?

    caplog captures log records, offering .text, .records and .record_tuples.

Summary

  • Structure the program as main(argv=None) returning an exit code, so tests call it directly.
  • capsys (and capfd) capture output; assert on both stdout and stderr.
  • Use pytest.raises(SystemExit) for usage errors and sys.exit paths, and read .value.code.
  • Fake input with monkeypatch on builtins.input or sys.stdin; use caplog for logging.
  • Keep a thin layer of real-process tests for the entry point.

Next: Testing Database Code