STDLIB Testing Mock Object Reference

This reference uses the fictional example of a mock created with _mock.create object.

Index

object

A placeholder function that takes the place of a specific function or binary during testing.

_object_mock_pipeable: This boolean determines if the mock should read from stdin (default=”0”).
_object_mock_rc: This is the exit code the mock is configured to return (default=”0”).

Arguments

… (array): These are the arguments that are passed to the original function or binary.

Exit codes

0: If the mock call succeeded.

Input on stdin

The mock can be configured to receive arguments from stdin.

Output on stdout

The mock can be configured to emit stdout.

Output on stderr

The mock can be configured to emit stderr.

object.mock.clear

Clears the mock’s call history and configured side effects.

_object_mock_calls_file string global: The filename containing the persisted calls of the mock (default=””).
_object_mock_side_effects_file string global: The filename containing the persisted side effects of the mock (default=””).

Function has no arguments.

Exit codes

0: If the mock’s history was cleared successfully.

object.mock.reset

Clears the mock’s call history and configured side effects as well as its configured exit code, stdout, stderr and subcommand properties.

_object_mock_rc integer global: This is the exit code the mock is configured to return (default=”0”).
_object_mock_stderr string global: This is the string that will be emitted to stderr when the mock is called (default=””).
_object_mock_stdout string global: This is the string that will be emitted to stdout when the mock is called (default=””).

Function has no arguments.

Exit codes

0: If the mock was reset successfully.

object.mock.assert_any_call_is

Asserts any call in the mock’s call history matches the given arg string.

Arguments

$1 (string): The arg string to compare against the mock’s call history.

Exit codes

0: If the mock was called at least once with the specified arguments.
1: If the mock was never called with the specified arguments.
126: If an invalid argument has been provided.
127: If the wrong number of arguments were provided.

Output on stderr

The error message if the assertion fails.

object.mock.assert_call_n_is

Asserts a call at a specific index in the mock’s call history matches the given arg string.

Arguments

$1 (integer): An index (from 1) in the mock’s call history to compare against.
$2 (string): The arg string to compare against the mock’s call history.

Exit codes

0: If the call at the specified index in the mock’s call history matches the given arg string.
1: If the call at the specified index in the mock’s call history does not match the given arg string.
126: If an invalid argument has been provided.
127: If the wrong number of arguments were provided.

Output on stderr

The error message if the assertion fails.

object.mock.assert_called_once_with

Asserts the mock was called once with a call matching the given arg string.

Arguments

$1 (string): The arg string to compare against the mock’s call history.

Exit codes

0: If the mock was called exactly once with the given arg string.
1: If the mock was not called exactly once with the given arg string.
126: If an invalid argument has been provided.
127: If the wrong number of arguments were provided.

Output on stdout

The actual first arg string this mock was called with, if the assertion fails.

Output on stderr

The error message if the assertion fails.

object.mock.assert_calls_are

Asserts the mock’s call history matches the given arg strings. (Call this function without args to assert this mock was not called at all).

_object_mock_calls_file string global: The filename containing the persisted calls of the mock (default=””).

Arguments

… (array): An array of arg strings that is expected to match the mock’s call history.

Exit codes

0: If the mock’s call history matches the given arg strings.
1: If the mock’s call history does not match the given arg strings.

Output on stderr

The error message if the assertion fails.

object.mock.assert_count_is

Asserts the mock was called the number of times specified by the given count.

Arguments

$1 (integer): A positive integer representing the expected number of times this mock was called.

Exit codes

0: If the mock was called a number of times that matches the specified count.
1: If the mock was called a number of times that does not match the specified count.
126: If an invalid argument has been provided.
127: If the wrong number of arguments were provided.

Output on stderr

The error message if the assertion fails.

object.mock.assert_not_called

Asserts the mock was not called.

Function has no arguments.

Exit codes

0: If the mock was not called.
1: If the mock was called any number of times.
127: If the wrong number of arguments were provided.

Output on stderr

The error message if the assertion fails.

object.mock.get.call

This function will retrieve the call at the specified index from the mock’s call history.

Arguments

$1 (integer): An index (from 1) in the mock’s call history to retrieve.

Exit codes

0: If the mock’s call was retrieved successfully.
126: If an invalid argument has been provided.
127: If the wrong number of arguments were provided.

Output on stdout

The specified mock call as an arg string.

Output on stderr

The error message if the operation fails.

object.mock.get.calls

This function will retrieve all calls from the mock’s call history.

Function has no arguments.

Exit codes

0: If all the mock’s calls were retrieved successfully.
127: If the wrong number of arguments were provided.

Output on stdout

All calls made by this mock as new line separated arg strings.

Output on stderr

The error message if the operation fails.

object.mock.get.count

This function will retrieve a count of the number of times this mock has been called.

_object_mock_calls_file string global: The filename containing the persisted calls of the mock (default=””).

Function has no arguments.

Exit codes

0: If the mock’s call count was retrieved successfully.
127: If the wrong number of arguments were provided.

Output on stdout

A count of the number of times this mock has been called.

Output on stderr

The error message if the operation fails.

object.mock.get.keywords

This function will retrieve the keywords assigned to this mock. (These keywords are variables whose values are recorded during each mock call).

_object_mock_keywords array global: These are the keywords, or variables, that the mock will record each time it’s called (default=()).

Function has no arguments.

Exit codes

0: If the mock’s keywords were retrieved successfully.
127: If the wrong number of arguments were provided.

Output on stdout

The keywords currently assigned to this mock.

Output on stderr

The error message if the operation fails.

object.mock.set.keywords

This function will set the keywords assigned to this mock. (These keywords are variables whose values are recorded during each mock call).

Arguments

… (array): These are the keywords, or variables, that the mock will record each time it’s called. (Call this function without any arguments to disable this feature).

Variables set

_object_mock_keywords (array): These are the keywords, or variables, that the mock will record each time it’s called.

Exit codes

0: If the mock’s keywords were set successfully.
126: If an invalid argument has been provided.

Output on stderr

The error message if the operation fails.

object.mock.set.pipeable

This function will toggle the ‘pipeable’ behaviour of the mock. Turning this on allows the mock to receive stdin.

Arguments

$1 (boolean): This enables or disables the ‘pipeable’ behaviour of the mock, (default=”0”).

Variables set

_object_mock_pipeable (boolean): This enables or disables the ‘pipeable’ behaviour of the mock.

Exit codes

0: If the mock’s pipeable behavior was toggled successfully.
126: If an invalid argument has been provided.
127: If the wrong number of arguments were provided.

Output on stderr

The error message if the operation fails.

object.mock.set.rc

This function will set the return code (exit code) of the mock. This behaviour can be overridden by configuring side effects or a subcommand.

Arguments

$1 (integer): This is the return code (or exit code) you wish the mock to emit. (Please note that any non-zero number emitted by the side effects or subcommand configured on this mock will override this value and be returned instead).

Variables set

_object_mock_rc (integer): This is the exit code the mock is configured to return.

Exit codes

0: If the mock’s return code was set successfully.
126: If an invalid argument has been provided.
127: If the wrong number of arguments were provided.

Output on stderr

The error message if the operation fails.

object.mock.set.side_effects

This function will set the side effects of the mock. These are a series of one or more commands the mock will execute each time it’s called.

_object_mock_side_effects_file string global: The filename containing the persisted side effects of the mock (default=””).

Arguments

… (array): This is a series of commands the mock will execute each time it’s called. (Call this function without any arguments to disable this feature).

Variables set

_object_mock_side_effects_boolean (boolean): This is a boolean indicating the mock has been configured with at least one side effect.

Exit codes

0: If the mock’s side effects were set successfully.
126: If an invalid argument has been provided.

Output on stderr

The error message if the operation fails.

object.mock.set.stderr

This function will set the stderr this mock will emit when called.

Arguments

$1 (string): This is the string that will be emitted to stderr when the mock is called.

Variables set

_object_mock_stderr (string): This is the string that will be emitted to stderr when the mock is called.

Exit codes

0: If the mock’s stderr was set successfully.
126: If an invalid argument has been provided.
127: If the wrong number of arguments were provided.

Output on stderr

The error message if the operation fails.

object.mock.set.stdout

This function will set the stdout this mock will emit when called.

Arguments

$1 (string): This is the string that will be emitted to stdout when the mock is called.

Variables set

_object_mock_stdout (string): This is the string that will be emitted to stdout when the mock is called.

Exit codes

0: If the mock’s stdout was set successfully.
126: If an invalid argument has been provided.
127: If the wrong number of arguments were provided.

Output on stderr

The error message if the operation fails.

object.mock.set.subcommand

This function will set the subcommand this mock will call when the mock is called. All arguments passed to the mock are accessible in the subcommand as escaped arguments ($1 $2).

Arguments

… (array): This is a series of commands the mock will execute each time it’s called. This is distinct from side effects in that the subcommand will receive all arguments sent to the mock itself.

Exit codes

0: If the mock’s subcommand was set successfully.