test_toolbox package

Submodules

test_toolbox.bdd module

class test_toolbox.bdd.BDD(description=None, level_bullet='->', max_width=120, indent_str=' ', output_functions=TestOutputFunctions(info=functools.partial(<function _print_formatter>, 'x1b[35m'), pass_=functools.partial(<function _print_formatter>, 'x1b[32m'), ignore=functools.partial(<function _print_formatter>, 'x1b[32m'), warn=functools.partial(<function _print_formatter>, 'x1b[33m'), fail=functools.partial(<function _print_formatter>, 'x1b[31m')))

Bases: object

FAIL = 'fail'
IGNORE = 'ignore'
PASS = 'pass'
UNKNOWN = 'unknown'
WARNING = 'warning'
generate_report()
classmethod scenario(scenario_description, level_bullet='->', max_width=120, indent_str=' ', output_functions=TestOutputFunctions(info=functools.partial(<function _print_formatter>, '\x1b[35m'), pass_=functools.partial(<function _print_formatter>, '\x1b[32m'), ignore=functools.partial(<function _print_formatter>, '\x1b[32m'), warn=functools.partial(<function _print_formatter>, '\x1b[33m'), fail=functools.partial(<function _print_formatter>, '\x1b[31m')))

test_toolbox.helpers module

This modules contains miscellaneous helpers for various testing and stubbing scenarios.

Included are:

  • modify_buffer_object() – Modifies a Python buffer object to allow the user to replace weird and challenging
    functions/methods like socket.recv_into()
  • await_condition() – Repeated evaluates a callable at a specified poll rate for a given amount of time, and
    either returns if the callable became true quickly enough, or asserts otherwise.
test_toolbox.helpers.await_condition(description, condition_eval_callable, on_failure=<function <lambda>>, timeout=10, poll_s=0.1)

Await a condition function to return True, otherwise raise an AssertionError if the condition did not return True within the alloted time.

Parameters:
  • description (str) – A string description of the condition we are awaiting.
  • condition_eval_callable (-> bool) – The callable of arity 0 (function, lambda, etc.) to monitor. This should return False when not completed, and return True when done.
  • on_failure (-> NoneType) – A callable of arity 0 that is called when a failure condition occurs. Default: NOOP
  • timeout (float | int) – The number of seconds to wait for the condition to become True. Default: 10 s
  • poll_s (float | int) – The period of time between checking the condition. Default: 100 ms
Returns:

None.
Raises:

AssertionError
test_toolbox.helpers.modify_buffer_object(source_buffer, dest_buffer, nbytes=None)

Modify a python object that supports the buffer interface internally. This is useful for testing things like socket.recv_into()

dest_buffer must be smaller than source_buffer, or the code will assert.

Parameters:
  • source_buffer – The source for the new data to be written into dest_buffer.
  • dest_buffer – The buffer to be modified inline.
  • nbytes – (OPTIONAL) The maximum number of bytes to write into the dest_buffer. If set, the number of bytes written is the minimum of nbytes and the source length. Default: None
Returns:

The total number of bytes written into dest_buffer.

test_toolbox.output module

The output module provides convenience methods for utilizing ANSI terminal color codes, which may be used to help visually differentiate output from scripts and tests.

There are two ways primary ways to consume this module: using output formatter functions or using print wrapper functions.

The following output format functions may be used to generate new text with the appropriate ANSI terminal codes to get the named effect:

  • purple()
  • green()
  • red()
  • yellow()
  • green()
  • blue()
  • cyan()
  • white()
  • bold()
  • half_bright()
  • underline()
  • blinking()

Each of these functions takes one argument and returns a string.

The following print functions work as you would expect the normal print function to, but print the arguments to the function with the named effect:

  • print_purple()
  • print_green()
  • print_red()
  • print_yellow()
  • print_cyan()
  • print_blue()
  • print_black()
  • print_white()
  • print_bold()
  • print_half_bright()
  • print_underline()
  • print_blinking()

All of these functions have the same arity as the underlying print function (that is to say they all may take zero or more arguments).

class test_toolbox.output.ANSITermCodes

Bases: object

BLACK = '\x1b[30m'
BLUE = '\x1b[34m'
BOLD = '\x1b[1m'
CYAN = '\x1b[36m'
GREEN = '\x1b[32m'
HALF_BRIGHT = '\x1b[1m'
NORMAL_BRIGHT = '\x1b[22m'
NORMAL_COLOR = '\x1b[39m'
PURPLE = '\x1b[35m'
RED = '\x1b[31m'
RESET = '\x1b[0m'
UNDERLINE = '\x1b[4m'
UNDERLINE_OFF = '\x1b[24m'
WHITE = '\x1b[37m'
YELLOW = '\x1b[33m'
class test_toolbox.output.TestOutputFunctions(info, pass_, ignore, warn, fail)

Bases: tuple

fail

Alias for field number 4

ignore

Alias for field number 2

info

Alias for field number 0

pass_

Alias for field number 1

warn

Alias for field number 3

test_toolbox.output.black(text, *, terminator_code='\x1b[39m')
test_toolbox.output.blinking(text, *, terminator_code='\x1b[25m')
test_toolbox.output.blue(text, *, terminator_code='\x1b[39m')
test_toolbox.output.bold(text, *, terminator_code='\x1b[22m')
test_toolbox.output.cyan(text, *, terminator_code='\x1b[39m')
test_toolbox.output.green(text, *, terminator_code='\x1b[39m')
test_toolbox.output.half_bright(text, *, terminator_code='\x1b[22m')
test_toolbox.output.print_black(*args)
test_toolbox.output.print_blinking(*args)
test_toolbox.output.print_blue(*args)
test_toolbox.output.print_bold(*args)
test_toolbox.output.print_cyan(*args)
test_toolbox.output.print_green(*args)
test_toolbox.output.print_half_bright(*args)
test_toolbox.output.print_purple(*args)
test_toolbox.output.print_red(*args)
test_toolbox.output.print_underline(*args)
test_toolbox.output.print_white(*args)
test_toolbox.output.print_yellow(*args)
test_toolbox.output.purple(text, *, terminator_code='\x1b[39m')
test_toolbox.output.red(text, *, terminator_code='\x1b[39m')
test_toolbox.output.underline(text, *, terminator_code='\x1b[24m')
test_toolbox.output.white(text, *, terminator_code='\x1b[39m')
test_toolbox.output.wrap_text_cleanly(text, width=120, preserve_newlines=False, initial_indent='', subsequent_indent='\t\t')
test_toolbox.output.yellow(text, *, terminator_code='\x1b[39m')

test_toolbox.spy module

class test_toolbox.spy.Spy(target_func, is_method=False, is_not_inspectable=False, verbose=True)

Bases: object

A Spy is an callable wrapper which intercepts the invocations and results of the wrapped function, method, or other callable in order to allow users to examine and verify how callables might be consumed by other code.

Parameters:
  • target_func – A function of any arity that will be wrapped with by this Spy.
  • is_method – True if this is wrapped an uninitialized method (i.e. in a class declaration), False otherwise.
  • is_not_inspectable – True if this is a built-in (i.e. implemented in C) or is otherwise unable to be inspected by the “inspect” module, False otherwise.
  • verbose – True if verbose reporting is desired, False otherwise.
Returns:

A new callable, which wraps target_func and may be used as a stand in.
assert_all_exact_match(*args, **kwargs)

Wraps assert_quantified_exact_match, seeing if the specified arguments always appear.

Parameters:
  • args – The arguments to attempt to match on.
  • kwargs – The keyword arguments to match on.
Returns:

None
Raises:

AssertionError on failure to match.
assert_all_partial_match(*args, **kwargs)

Wraps assert_quantified_partial_match, seeing if the specified arguments always show up.

Parameters:
  • args – The arguments to attempt to match on.
  • kwargs – The keyword arguments to match on.
Returns:

None
Raises:

AssertionError on failure to match.
assert_all_result_match(result_predicate)

Wraps assert_quantified_partial_match, seeing if the result predicate is always true.

Parameters:result_predicate – The function to match against stored results.
Returns:None
Raises:AssertionError on failure to match.
assert_any_exact_match(*args, **kwargs)

Wraps assert_quantified_exact_match, seeing if the specified arguments show up at least once.

Parameters:
  • args – The arguments to attempt to match on.
  • kwargs – The keyword arguments to match on.
Returns:

None
Raises:

AssertionError on failure to match.
assert_any_partial_match(*args, **kwargs)

Wraps assert_quantified_partial_match, seeing if the specified arguments show up at least once.

Parameters:
  • args – The arguments to attempt to match on.
  • kwargs – The keyword arguments to match on.
Returns:

None
Raises:

AssertionError on failure to match.
assert_any_result_match(result_predicate)

Wraps assert_quantified_partial_match, seeing if the result predicate returns true at least once.

Parameters:result_predicate – The function to match against stored results.
Returns:None
Raises:AssertionError on failure to match.
assert_one_exact_match(*args, **kwargs)

Wraps assert_quantified_exact_match, seeing if the specified arguments show up exactly once.

Parameters:
  • args – The arguments to attempt to match on.
  • kwargs – The keyword arguments to match on.
Returns:

None
Raises:

AssertionError on failure to match.
assert_one_partial_match(*args, **kwargs)

Wraps assert_quantified_partial_match, seeing if the specified arguments show up exactly once.

Parameters:
  • args – The arguments to attempt to match on.
  • kwargs – The keyword arguments to match on.
Returns:

None
Raises:

AssertionError on failure to match.
assert_one_result_match(result_predicate)

Wraps assert_quantified_partial_match, seeing if the result predicate is true exactly once.

Parameters:result_predicate – The function to match against stored results.
Returns:None
Raises:AssertionError on failure to match.
assert_quantified_exact_match(times_predicate, *args, **kwargs)

Assert that an exact match exists for the given times invoked predicate and argument matcher predicate. If there are unmatched arguments, this will return false.

Parameters:
  • times_predicate – An arity 2 predicate that takes the successful invocation list, and the total invocation list, returns true or false based on these matching number of times executed expectation embedded in this predicate.
  • args – The predicate positional arguments to match up against the call arguments, to check and verify against. These should all be arity 1 and return True/False.
  • kwargs – The predicate keyword arguments to match up against the call arguments, to check and verify against. These should all be arity 1 and return True/False.
Returns:

None.
Raises:

AssertionError on failure to match.
assert_quantified_exact_plus_result_match(times_predicate, result_predicate, *args, **kwargs)

Assert over the spied results of all of the callable invocations, see if any match satisfies the number of times predicate, the result predicate and the given exact invocation args/kwargs predicates.

Parameters:
  • times_predicate – An arity 2 predicate that takes the successful invocation list, and the total invocation list, returns true or false based on these matching number of times executed expectation embedded in this predicate.
  • result_predicate – An arity 1 predicate to match against the recorded result of a function call.
  • args – The predicate positional arguments to match up against the call arguments, to check and verify against. These should all be arity 1 and return True/False.
  • kwargs – The predicate keyword arguments to match up against the call arguments, to check and verify against. These should all be arity 1 and return True/False.
Returns:

None
Raises:

AssertionError on failure to match.
assert_quantified_partial_match(times_predicate, *args, **kwargs)

Assert that an partial match exists for the given times invoked predicate and argument matcher predicate. Arguments that do no have corresponding matcher predicates are ignored.

Parameters:
  • times_predicate – An arity 2 predicate that takes the successful invocation list, and the total invocation list, returns true or false based on these matching number of times executed expectation embedded in this predicate.
  • args – The predicate positional arguments to match up against the call arguments, to check and verify against. These should all be arity 1 and return True/False.
  • kwargs – The predicate keyword arguments to match up against the call arguments, to check and verify against. These should all be arity 1 and return True/False.
Returns:

None.
Raises:

AssertionError on failure to match.
assert_quantified_partial_plus_result_match(times_predicate, result_predicate, *args, **kwargs)

Assert over the spied results of all of the callable invocations, see if any match satisfies the number of times predicate, the result predicate and the given partial invocation args/kwargs predicates.

Parameters:
  • times_predicate – An arity 2 predicate that takes the successful invocation list, and the total invocation list, returns true or false based on these matching number of times executed expectation embedded in this predicate.
  • result_predicate – An arity 1 predicate to match against the recorded result of a function call.
  • args – The predicate positional arguments to match up against the call arguments, to check and verify against. These should all be arity 1 and return True/False.
  • kwargs – The predicate keyword arguments to match up against the call arguments, to check and verify against. These should all be arity 1 and return True/False.
Returns:

None
Raises:

AssertionError on failure to match.
assert_quantified_result_match(times_predicate, result_predicate)

Assert the spied results of all of the callable invocations, see if any match the specified predicates.

Parameters:
  • times_predicate – An arity 2 predicate that takes the successful invocation list, and the total invocation list, returns true or false based on these matching number of times executed expectation embedded in this predicate.
  • result_predicate – An arity 1 predicate to match against the recorded result of a function call.
Returns:

None.
Raises:

AssertionError on failure to match.
check_quantified_exact_match(times_predicate, *args, **kwargs)

Check to see if an exact match exists for the given times invoked predicate and argument matcher predicate. If there are unmatched arguments, this will return false.

Parameters:
  • times_predicate – An arity 2 predicate that takes the successful invocation list, and the total invocation list, returns true or false based on these matching number of times executed expectation embedded in this predicate.
  • args – The predicate positional arguments to match up against the call arguments, to check and verify against. These should all be arity 1 and return True/False.
  • kwargs – The predicate keyword arguments to match up against the call arguments, to check and verify against. These should all be arity 1 and return True/False.
Returns:

True if a match/matches was found that satisfies all of the predicates, False otherwise.
check_quantified_exact_plus_result_match(times_predicate, result_predicate, *args, **kwargs)

Check the spied results of all of the callable invocations, see if any match satisfies the number of times predicate, the result predicate and the given exact invocation args/kwargs predicates.

Parameters:
  • times_predicate – An arity 2 predicate that takes the successful invocation list, and the total invocation list, returns true or false based on these matching number of times executed expectation embedded in this predicate.
  • result_predicate – An arity 1 predicate to match against the recorded result of a function call.
  • args – The predicate positional arguments to match up against the call arguments, to check and verify against. These should all be arity 1 and return True/False.
  • kwargs – The predicate keyword arguments to match up against the call arguments, to check and verify against. These should all be arity 1 and return True/False.
Returns:

True all of the predicates satisfied, False otherwise.
check_quantified_partial_match(times_predicate, *args, **kwargs)

Check to see if an partial match exists for the given times invoked predicate and argument matcher predicate. Arguments that do no have corresponding matcher predicates are ignored.

Parameters:
  • times_predicate – An arity 2 predicate that takes the successful invocation list, and the total invocation list, returns true or false based on these matching number of times executed expectation embedded in this predicate.
  • args – The predicate positional arguments to match up against the call arguments, to check and verify against. These should all be arity 1 and return True/False.
  • kwargs – The predicate keyword arguments to match up against the call arguments, to check and verify against. These should all be arity 1 and return True/False.
Returns:

True if a match/matches was found that satisfies all of the predicates, False otherwise.
check_quantified_partial_plus_result_match(times_predicate, result_predicate, *args, **kwargs)

Check the spied results of all of the callable invocations, see if any match satisfies the number of times predicate, the result predicate and the given partial invocation args/kwargs predicates.

Parameters:
  • times_predicate – An arity 2 predicate that takes the successful invocation list, and the total invocation list, returns true or false based on these matching number of times executed expectation embedded in this predicate.
  • result_predicate – An arity 1 predicate to match against the recorded result of a function call.
  • args – The predicate positional arguments to match up against the call arguments, to check and verify against. These should all be arity 1 and return True/False.
  • kwargs – The predicate keyword arguments to match up against the call arguments, to check and verify against. These should all be arity 1 and return True/False.
Returns:

True all of the predicates satisfied, False otherwise.
check_quantified_result_match(times_predicate, result_predicate)

Check the spied results of all of the callable invocations, see if any match the specified predicates.

Parameters:
  • times_predicate – An arity 2 predicate that takes the successful invocation list, and the total invocation list, returns true or false based on these matching number of times executed expectation embedded in this predicate.
  • result_predicate – An arity 1 predicate to match against the recorded result of a function call.
Returns:

True if a result/results were found that satisfy both predicates.
num_invocations

Access the number of successful invocations recorded.

Returns:The integer number of invocations the Spy knows about.
reset()

Clear all of the recorded invocations to return to an “uninvoked” state.

Returns:True
class test_toolbox.spy.TargetInvocation(args, kwargs, result)

Bases: tuple

args

Alias for field number 0

kwargs

Alias for field number 1

result

Alias for field number 2

test_toolbox.spy.always(matching_invocations, all_invocations)

This predicate verifies that all invocations must have matched.

Parameters:
  • matching_invocations – All found matching invocations.
  • all_invocations – All invocations of the Spy
Returns:

True or False.
test_toolbox.spy.any_of(elements)

Check to see if the argument is contained in a list of possible elements.

Parameters:elements – The elements to check the argument against in the predicate.
Returns:A predicate to check if the argument is a constituent element.
test_toolbox.spy.anything(_)

This predicate will always return True, and thus matches anything.

Parameters:_ – The argument, which is ignored.
Returns:True
test_toolbox.spy.apply_builtin_function_spy(func)

Apply a spy to a built-in function that does not work with inspect.getargspec.

Parameters:func – The function to spy on.
Returns:The function with a spy attached.
test_toolbox.spy.apply_function_spy(func)

Apply a Spy to a function, lambda, staticmethod, or instantiated object’s method.

Parameters:func – The callable to spy on.
Returns:The callable with attached spy.
test_toolbox.spy.apply_method_spy(method)

Apply a spy to an instance method declaration on an object. This must be handled differently because of the way Python handles decorators and does virtual method dispatch on instance methods.

Parameters:method – The instance method (or possibly classmethod) to spy on.
Returns:The method with attached spy.
test_toolbox.spy.at_least_once(matching_invocations, _)
test_toolbox.spy.at_least_times(num_times)

Create a predicate that checks to see if the number of matching invocations occur at least the specified number of times.

Parameters:num_times – The minimum number of matches that must have occurred.
Returns:A predicate to check the resulting matching invocations list.
test_toolbox.spy.contains(element)

Check to see if an argument contains a specified element.

Parameters:element – The element to check against.
Returns:A predicate to check if the argument is equal to the element.
test_toolbox.spy.equal_to(element)

Check to see if the argument is equal to the specified element

Parameters:element – The element to check against the argument.
Returns:A predicate to check if the argument is equal to the element.
test_toolbox.spy.get_reporting_max_width()

Get the current max width for reported parameters used in the Spy module.

Returns:The current reported max width.
Return type:int
test_toolbox.spy.identical_to(element)

Check to see if the argument is identical to the specified element

Parameters:element – The element to check against the argument.
Returns:A predicate to check if the argument is identical to the element.
test_toolbox.spy.instance_of(cls)

Check to see if the argument is an instance of the specified class element.

Parameters:cls – The element to use to check inheritance of the argument.
Returns:A predicate to check if the argument an instance of the element.
test_toolbox.spy.never(matching_invocations, _)
test_toolbox.spy.once(matching_invocations, _)
test_toolbox.spy.set_reporting_max_width(w)

Set the max width for reported parameters. This is used to that failures don’t overflow terminals in the event arguments are dumped.

Parameters:w (int) – The new max width to enforce for the module
Returns:True
test_toolbox.spy.times(num_times)

Create a predicate that checks to see if the number of matching invocations occur exactly the specified number of times.

Parameters:num_times – The exact number of matches that must have occurred.
Returns:A predicate to check the resulting matching invocations list.

Module contents