Testing

Face provides a full-featured test client for maintaining high-quality command-line applications.

class face.CommandChecker(cmd, env=None, chdir=None, mix_stderr=False, reraise=False)

Face’s main testing interface.

Wrap your Command instance in a CommandChecker, run() commands with arguments, and get RunResult objects to validate your Command’s behavior.

Parameters:

• cmd – The Command instance to test.
• env (dict) – An optional base environment to use for subsequent calls issued through this checker. Defaults to {}.
• chdir (str) – A default path to execute this checker’s commands in. Great for temporary directories to ensure test isolation.
• mix_stderr (bool) – Set to True to capture stderr into stdout. This makes it easier to verify order of standard output and errors. If True, this checker’s results’ error_bytes will be set to None. Defaults to False.
• reraise (bool) – Reraise uncaught exceptions from within cmd’s endpoint functions, instead of returning a RunResult instance. Defaults to False.

run(args, input=None, env=None, chdir=None, exit_code=0)

The run() method acts as the primary entrypoint to the CommandChecker instance. Pass arguments as a list or string, and receive a RunResult with which to verify your command’s output.

If the arguments do not result in an expected exit_code, a CheckError will be raised.

Parameters:

• args – A list or string representing arguments, as one might find in sys.argv or at the command line.
• input (str) – A string (or list of lines) to be passed to the command’s stdin. Used for testing prompt() interactions, among others.
• env (dict) – A mapping of environment variables to apply on top of the CommandChecker’s base env vars.
• chdir (str) – A string (or stringifiable path) path to switch to before running the command. Defaults to None (runs in current directory).
• exit_code (int) – An integer or list of integer exit codes expected from running the command with args. If the actual exit code does not match exit_code, CheckError is raised. Set to None to disable this behavior and always return RunResult. Defaults to 0.

Note

At this time, run() interacts with global process state, and is not designed for parallel usage.

fail(*a, **kw)

Convenience method around run(), with the same signature, except that this will raise a CheckError if the command completes with exit code 0.

fail_X()

Test that a command fails with exit code X, where X is an integer.

For testing convenience, any method of pattern fail_X() is the equivalent to fail(exit_code=X), and fail_X_Y() is equivalent to fail(exit_code=[X, Y]), providing X and Y are integers.

class face.testing.RunResult(args, input, exit_code, stdout_bytes, stderr_bytes, exc_info=None, checker=None)

Returned from CommandChecker.run(), complete with the relevant inputs and outputs of the run.

Instances of this object are especially valuable for verifying expected output via the stdout and stderr attributes.

API modeled after subprocess.CompletedProcess for familiarity and porting of tests.

args

The arguments passed to run().

input

The string input passed to the command, if any.

exit_code

The integer exit code returned by the command. 0 conventionally indicates success.

stdout

The text output (“stdout”) of the command, as a decoded string. See stdout_bytes for the bytestring.

stderr

The error output (“stderr”) of the command, as a decoded string. See stderr_bytes for the bytestring. May be None if mix_stderr was set to True in the CommandChecker.

stdout_bytes

The output (“stdout”) of the command, as an encoded bytestring. See stdout for the decoded text.

stderr_bytes

The error output (“stderr”) of the command, as an encoded bytestring. See stderr for the decoded text. May be None if mix_stderr was set to True in the CommandChecker.

returncode

Alias of exit_code, for parity with subprocess.CompletedProcess

exc_info

A 3-tuple of the internal exception, in the same fashion as sys.exc_info(), representing the captured uncaught exception raised by the command function from a CommandChecker with reraise set to True. For advanced use only.

exception

Exception instance, if an uncaught error was raised. Equivalent to run_res.exc_info[1], but more readable.

exception face.testing.CheckError(result, exit_codes)

Rarely raised directly, CheckError is automatically raised when a CommandChecker.run() call does not terminate with an expected error code.

This error attempts to format the stdout, stderr, and stdin of the run for easier debugging.