Overview¶

The netsa.util.clitest module provides an API for driving automated tests of command-line applications. It doesn’t do the work of a test framekwork; for that, use a framework library such as unittest or functest.

Enough of netsa.util.clitest has been implemented to fulfill a minimal set of requirements. Additional features will be added as necessary to support more complex testing.

This module is influenced by https://pypi.python.org/pypi/Paste

A usage example:

from clitest import *
env = Environment("./test-output")
# Run the command
result = env.run("ryscatterplot --help")
assert(result.success())
assert(result.stdout() == "whatever the help output is")
assert(result.stderr() == "")
# Clean up whatever detritus the command left
env.cleanup()

Exceptions¶

exception netsa.util.clitest.TestingException¶

Class of exceptions raised by the clitest module.

Classes¶

class netsa.util.clitest.Environment([work_dir : str][, save_work_dir : bool][, debug : bool][, <env_name>=<env_val>, ...])¶

An environment for running commands, including a set of environment variables and a working directory.

The work_dir argument is the working directory in which the commands are run. If work_dir is None, a directory will be made using tempfile.mkdtemp with default values.

work_dir must not already exist or run will raise a TestingException. If save_work_dir is False, cleanup will remove this directory when it is called.

If debug is True, several debug messages will be emitted on stderr.

Any additional keyword arguments are used as environment variables.

get_env(env_name : str) → str¶

Returns the value of env_name in the environment. If env_name does not exist in the environment, this method returns None.

set_env(env_name : str, env_val : str)¶

Sets the value of env_name in the environment to env_val. env_val must be a string.

del_env(env_name : str)¶

Removes env_name from the environment. If env_name doesn’t exist, this method has no effect.

get_work_dir() → str¶

Returns the working directory in which the commands are run.

run(command : str[, <keyword>=<value>, ...]) → Result¶

Runs a single command, capturing and returning result information. Keyword arguments are passed to netsa.util.shell.run_parallel. See the documentation of that function for an explanation of how such arguments are interpreted.

Returns a Result object representing the outcome.

cleanup()¶

Cleans up resources left behind by the test process.

class netsa.util.clitest.Result(command, envars, exit_codes, stdout, stderr, debug=False)¶

Contains information on a command’s exit status and output.

success() → bool¶

Returns True if the exit code of the process was 0. This usually, but not always, indicates that the process ran successfully. Know Your Tool before relying on this function.

exited([code]) → bool¶

Returns True if the process exited with the specified exit code. If the exit code is None or unsupplied, returns True if the process terminated normally (e.g., not on a signal).

exit_status() → int or None¶

Returns the exit status of the process, if the process exited normally (e.g., was not terminated on a signal). Otherwise, this function returns None.

signal() → int or None¶

Returns the signal on which the process terminated, if the process terminated on a signal. Otherwise, this function returns None.

signaled() → bool¶

Returns True if the process terminated on the specified signal. If the signal is None or unsupplied, returns True if the process terminated on a signal.

format_status() → str¶

Returns a human-readable representation of how the process exited.

get_status() → int¶

Returns the raw exit status of the process, as an integer formatted in the style of os.wait.

get_stdout() → str¶

Returns the standard output of the process as a string.

get_stderr() → str¶

Returns the standard error of the process as a string.

get_info() → str¶

Returns the information contained in the result as a human-readable string.