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)[source]¶ Face’s main testing interface.
Wrap your
Command
instance in aCommandChecker
,run()
commands with arguments, and getRunResult
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. IfTrue
, this checker’s results’ error_bytes will be set toNone
. Defaults toFalse
. - reraise (bool) – Reraise uncaught exceptions from within cmd’s
endpoint functions, instead of returning a
RunResult
instance. Defaults toFalse
.
-
run
(args, input=None, env=None, chdir=None, exit_code=0)[source]¶ The
run()
method acts as the primary entrypoint to theCommandChecker
instance. Pass arguments as a list or string, and receive aRunResult
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 toNone
to disable this behavior and always returnRunResult
. Defaults to0
.
Note
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
-
fail
(*a, **kw)[source]¶ Convenience method around
run()
, with the same signature, except that this will raise aCheckError
if the command completes with exit code0
.
-
fail_X
()¶ Test that a command fails with exit code
X
, whereX
is an integer.For testing convenience, any method of pattern
fail_X()
is the equivalent tofail(exit_code=X)
, andfail_X_Y()
is equivalent tofail(exit_code=[X, Y])
, providingX
andY
are integers.
- cmd – The
-
class
face.testing.
RunResult
(args, input, exit_code, stdout_bytes, stderr_bytes, exc_info=None, checker=None)[source]¶ 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
andstderr
attributes.API modeled after
subprocess.CompletedProcess
for familiarity and porting of tests.-
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 beNone
if mix_stderr was set toTrue
in theCommandChecker
.
-
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 beNone
if mix_stderr was set toTrue
in theCommandChecker
.
-
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 aCommandChecker
with reraise set toTrue
. 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)[source]¶ Rarely raised directly,
CheckError
is automatically raised when aCommandChecker.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.