Face provides a full-featured test client for maintaining high-quality command-line applications.
CommandChecker(cmd, env=None, chdir=None, mix_stderr=False, reraise=False)[source]¶
Face’s main testing interface.
Commandinstance in a
run()commands with arguments, and get
RunResultobjects to validate your Command’s behavior.
- cmd – The
Commandinstance 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
Trueto 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
- reraise (bool) – Reraise uncaught exceptions from within cmd’s
endpoint functions, instead of returning a
RunResultinstance. Defaults to
run(args, input=None, env=None, chdir=None, exit_code=0)[source]¶
run()method acts as the primary entrypoint to the
CommandCheckerinstance. Pass arguments as a list or string, and receive a
RunResultwith which to verify your command’s output.
If the arguments do not result in an expected exit_code, a
CheckErrorwill be raised.
- args – A list or string representing arguments, as one might
sys.argvor 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,
CheckErroris raised. Set to
Noneto disable this behavior and always return
RunResult. Defaults to
At this time,
run()interacts with global process state, and is not designed for parallel usage.
- args – A list or string representing arguments, as one might find in
Convenience method around
run(), with the same signature, except that this will raise a
CheckErrorif the command completes with exit code
Test that a command fails with exit code
Xis an integer.
For testing convenience, any method of pattern
fail_X()is the equivalent to
fail_X_Y()is equivalent to
fail(exit_code=[X, Y]), providing
- cmd – The
RunResult(args, input, exit_code, stdout_bytes, stderr_bytes, exc_info=None, checker=None)[source]¶
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
API modeled after
subprocess.CompletedProcessfor familiarity and porting of tests.
The string input passed to the command, if any.
The integer exit code returned by the command.
0conventionally indicates success.
The text output (“stdout”) of the command, as a decoded string. See
stdout_bytesfor the bytestring.
The error output (“stderr”) of the command, as a decoded string. See
stderr_bytesfor the bytestring. May be
Noneif mix_stderr was set to
The output (“stdout”) of the command, as an encoded bytestring. See
stdoutfor the decoded text.
The error output (“stderr”) of the command, as an encoded bytestring. See
stderrfor the decoded text. May be
Noneif mix_stderr was set to
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
CommandCheckerwith reraise set to
True. For advanced use only.
Exception instance, if an uncaught error was raised. Equivalent to
run_res.exc_info, but more readable.
Rarely raised directly,
CheckErroris 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.