STDLIB Testing Complete Function Reference
Index
assert_array_equals
Asserts that two arrays are equal.
Arguments
$1 (string): The first array to compare.
$2 (string): The second array to compare.
Exit codes
0: If the arrays match.
1: If the arrays do not match.
Output on stderr
The error message if the assertion fails.
assert_array_length
Asserts that an array has the expected length.
Arguments
$1 (integer): The expected length.
$2 (string): The name of the array variable.
Exit codes
0: If the array length matches the expected length.
1: If the array length does not match the expected length.
Output on stderr
The error message if the assertion fails.
assert_is_array
Asserts that a variable is an array.
Arguments
$1 (string): The name of the variable to check.
Exit codes
0: If the variable is an array.
1: If the variable is not an array.
Output on stderr
The error message if the assertion fails.
assert_is_array_containing
Asserts that a variable is an array containing a value.
Arguments
$1 (string): The value to assert is present.
$2 (string): The name of the variable to check.
Exit codes
0: If the value is present in the array.
1: If the value is not present in the array.
Output on stderr
The error message if the assertion fails.
assert_is_fn
Asserts that a value is a function.
Arguments
$1 (string): The function name to check.
Exit codes
0: If the function is defined.
1: If the function is not defined.
Output on stderr
The error message if the assertion fails.
assert_not_fn
Asserts that a value is not a function.
Arguments
$1 (string): The function name to check.
Exit codes
0: If the function is not defined.
1: If the function is defined.
Output on stderr
The error message if the assertion fails.
assert_logger_error_matches
Asserts that the stdlib.logger.error function was mocked and called with specific arguments, or alternatively, not called at all.
STDLIB_LOGGING_MESSAGE_PREFIX string keyword: If the mock has this keyword set, then the value of this keyword is used when matching (default=””).
Arguments
… (array): A list of message strings the logger is expected to have been called with. An empty list asserts that the logger was not called.
Exit codes
0: If the assertion passed.
1: If the assertion fails, or if the logger has not been mocked.
Output on stderr
The error message if the assertion fails.
assert_logger_info_matches
Asserts that the stdlib.logger.info function was mocked and called with specific arguments, or alternatively, not called at all.
STDLIB_LOGGING_MESSAGE_PREFIX string keyword: If the mock has this keyword set, then the value of this keyword is used when matching (default=””).
Arguments
… (array): A list of message strings the logger is expected to have been called with. An empty list asserts that the logger was not called.
Exit codes
0: If the assertion passed.
1: If the assertion fails, or if the logger has not been mocked.
Output on stderr
The error message if the assertion fails.
assert_logger_notice_matches
Asserts that the stdlib.logger.notice function was mocked and called with specific arguments, or alternatively, not called at all.
STDLIB_LOGGING_MESSAGE_PREFIX string keyword: If the mock has this keyword set, then the value of this keyword is used when matching (default=””).
Arguments
… (array): A list of message strings the logger is expected to have been called with. An empty list asserts that the logger was not called.
Exit codes
0: If the assertion passed.
1: If the assertion fails, or if the logger has not been mocked.
Output on stderr
The error message if the assertion fails.
assert_logger_success_matches
Asserts that the stdlib.logger.success function was mocked and called with specific arguments, or alternatively, not called at all.
STDLIB_LOGGING_MESSAGE_PREFIX string keyword: If the mock has this keyword set, then the value of this keyword is used when matching (default=””).
Arguments
… (array): A list of message strings the logger is expected to have been called with. An empty list asserts that the logger was not called.
Exit codes
0: If the assertion passed.
1: If the assertion fails, or if the logger has not been mocked.
Output on stderr
The error message if the assertion fails.
assert_logger_warning_matches
Asserts that the stdlib.logger.warning function was mocked and called with specific arguments, or alternatively, not called at all.
STDLIB_LOGGING_MESSAGE_PREFIX string keyword: If the mock has this keyword set, then the value of this keyword is used when matching (default=””).
Arguments
… (array): A list of message strings the logger is expected to have been called with. An empty list asserts that the logger was not called.
Exit codes
0: If the assertion passed.
1: If the assertion fails, or if the logger has not been mocked.
Output on stderr
The error message if the assertion fails.
assert_is_mock
Asserts that a mock exists with the given name.
Arguments
$1 (string): The name of an expected mock object.
Exit codes
0: If the assertion passed.
1: If the assertion fails, or if logger has not been mocked.
Output on stderr
The error message if the assertion fails.
assert_not_null
Asserts that a value is not null.
Arguments
$1 (string): The value to check.
Exit codes
0: If the value is not null.
1: If the value is null.
Output on stderr
The error message if the assertion fails.
assert_null
Asserts that a value is null.
Arguments
$1 (string): The value to check.
Exit codes
0: If the value is null.
1: If the value is not null.
Output on stderr
The error message if the assertion fails.
assert_output
Asserts that the captured output matches the expected value.
Arguments
$1 (string): The expected output.
Exit codes
0: If the output matches.
1: If the output does not match.
Output on stderr
The error message if the assertion fails.
assert_output_null
Asserts that the captured output is null.
Function has no arguments.
Exit codes
0: If the output is null.
1: If the output is not null.
Output on stderr
The error message if the assertion fails.
assert_output_raw
Asserts that the captured output matches the expected value (raw).
Arguments
$1 (string): The expected output.
Exit codes
0: If the output matches.
1: If the output does not match.
Output on stderr
The error message if the assertion fails.
assert_rc
Asserts that the captured return code matches the expected value.
Arguments
$1 (integer): The expected return code.
Exit codes
0: If the return code matches.
1: If the return code does not match.
Output on stderr
The error message if the assertion fails.
assert_snapshot
Asserts that the captured output matches a snapshot file.
Arguments
$1 (string): A path relative to the test directory containing a text file.
Exit codes
0: If the output matches the snapshot.
1: If the output does not match the snapshot.
Output on stderr
The error message if the assertion fails.
_capture.assertion_failure
Captures the output of a command that is expected to fail.
STDLIB_TESTING_TRACEBACK_REGEX string keyword: A regex used to identify and remove traceback lines (default=”$’^([^:]+:[0-9]+|environment:[0-9]+):.+$’”).
Arguments
… (array): The command to execute.
Variables set
TEST_OUTPUT (string): The captured output from the failing command.
Exit codes
0: If the assertion failed as expected.
1: If the assertion succeeded unexpectedly.
Output on stdout
The filtered output of the failing command.
Output on stderr
The error message if the assertion fails.
_capture.output
Captures the stdout and stderr of a command.
Arguments
… (array): The command to execute.
Variables set
TEST_OUTPUT (string): The combined stdout and stderr from the command.
Exit codes
0: If the output was captured successfully.
_capture.output_raw
Captures the stdout and stderr of a command (raw).
Arguments
… (array): The command to execute.
Variables set
TEST_OUTPUT (string): The combined stdout and stderr from the command.
Exit codes
0: If the command succeeded.
1: If the command failed.
126: If an invalid argument has been provided.
127: If the wrong number of arguments were provided.
_capture.rc
Captures the return code of a command.
Arguments
… (array): The command to execute.
Variables set
TEST_RC (integer): The return code from the command.
Exit codes
0: If the return code was captured successfully.
_capture.stderr
Captures the stderr of a command.
Arguments
… (array): The command to execute.
Variables set
TEST_OUTPUT (string): The captured stderr from the command.
Exit codes
0: If the command succeeded.
1: If the command failed.
126: If an invalid argument has been provided.
127: If the wrong number of arguments were provided.
_capture.stderr_raw
Captures the stderr of a command (raw).
Arguments
… (array): The command to execute.
Variables set
TEST_OUTPUT (string): The captured stderr from the command.
Exit codes
0: If the command succeeded.
1: If the command failed.
126: If an invalid argument has been provided.
127: If the wrong number of arguments were provided.
_capture.stdout
Captures the stdout of a command.
Arguments
… (array): The command to execute.
Variables set
TEST_OUTPUT (string): The captured stdout from the command.
Exit codes
0: If the stdout was captured successfully.
_capture.stdout_raw
Captures the stdout of a command (raw).
Arguments
… (array): The command to execute.
Variables set
TEST_OUTPUT (string): The captured stdout from the command.
Exit codes
0: If the command succeeded.
1: If the command failed.
126: If an invalid argument has been provided.
127: If the wrong number of arguments were provided.
_testing.error
Logs an error message.
STDLIB_TESTING_THEME_ERROR string global: The colour to use for the message (default=”LIGHT_RED”).
Arguments
… (array): The error messages to log.
Exit codes
0: If the error message was logged.
Output on stderr
The error message if the operation fails.
_testing.error_pipe
A pipeable version _testing.error that can read from stdin and return specific error codes when errors are found.
STDLIB_TESTING_THEME_ERROR string global: The colour to use for the message (default=”LIGHT_RED”).
Arguments
$1 (integer): (optional, default=1) The error code that should be returned if any error message is piped to this function.
Exit codes
0: If the error message was not logged.
1: If an error message is logged. (This value is configurable via arguments).
Output on stderr
The error message if the operation fails.
_testing.fixtures.debug.diff
Prints a diff between two values for debugging.
STDLIB_TESTING_THEME_DEBUG_FIXTURE string global: The colour to use for the debug output (default=”GREY”).
Arguments
$1 (string): The expected value.
$2 (string): The actual value.
Exit codes
0: If the values match.
1: If the values do not match.
Output on stdout
The debug diff output.
_testing.fixtures.mock.logger
Creates mocks for all stdlib.logger functions.
Function has no arguments.
Exit codes
0: If the logger mocks were created successfully.
126: If an invalid argument has been provided.
127: If the wrong number of arguments were provided.
Output on stdout
The informational messages.
Output on stderr
The error message if the operation fails.
_testing.fixtures.random.name
Generates a random alphanumeric name.
Arguments
$1 (integer): (optional, default=50) The length of the name to generate.
Exit codes
0: If the random name was generated.
Output on stdout
The generated random name.
_testing.load
Loads a module with error support.
STDLIB_TESTING_THEME_LOAD string global: The colour to use for the message (default=”GREY”).
Arguments
$1 (string): The module path to source.
Exit codes
0: If the module was loaded.
126: If an invalid argument has been provided.
127: If the wrong number of arguments were provided.
Output on stdout
The notification message.
Output on stderr
The error message if the operation fails.
_mock.arg_string.make.from_array
Generates a mock argument string from an array.
Arguments
$1 (string): The name of the array containing positional arguments.
$2 (string): (optional) The name of the array containing keyword arguments.
Exit codes
0: If the mock argument string was generated.
126: If an invalid argument has been provided.
127: If the wrong number of arguments were provided.
Output on stdout
The generated mock argument string.
_mock.arg_string.make.from_string
Generates a mock argument string from a delimited string.
STDLIB_LINE_BREAK_DELIMITER string keyword: The delimiter used to split the string (default=” “).
Arguments
$1 (string): The delimited string of positional arguments.
$2 (string): (optional) The name of the array containing keyword arguments.
Exit codes
0: If the mock argument string was generated.
125: If an invalid keyword has been provided.
126: If an invalid argument has been provided.
127: If the wrong number of arguments were provided.
Output on stdout
The generated mock argument string.
_mock.clear_all
Clears all calls from all registered mocks.
Function has no arguments.
Exit codes
0: If all registered mocks were cleared.
_mock.create
Creates a new mock object.
Arguments
$1 (string): The name of the function or binary to mock.
Exit codes
0: If the mock object was created successfully.
123: If a variable reserved for use by the BASH stdlib has been assigned an invalid value.
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.
_mock.delete
Deletes a mock object and restores its original implementation.
Arguments
$1 (string): The name of the mock to delete.
Exit codes
0: If the mock object was deleted.
127: If the wrong number of arguments were provided.
_mock.register_cleanup
Registers the mock cleanup function with the exit trap.
Function has no arguments.
Exit codes
0: If the cleanup function was registered successfully.
_mock.reset_all
Resets all registered mocks to their default state.
Function has no arguments.
Exit codes
0: If all registered mocks were reset.
_mock.sequence.assert_is
Asserts that the sequence of mock calls matches the expected values.
Arguments
… (array): The expected sequence of mock calls.
Exit codes
0: If the sequence matches.
1: If the sequence does not match.
Output on stderr
The error message if the assertion fails.
_mock.sequence.assert_is_empty
Asserts that no mock calls have been recorded.
Function has no arguments.
Exit codes
0: If the sequence is empty.
1: If the sequence is not empty.
Output on stderr
The error message if the assertion fails.
_mock.sequence.clear
Clears the recorded sequence of mock calls.
Function has no arguments.
Exit codes
0: If the sequence was cleared.
_mock.sequence.record.resume
Resumes recording of mock calls in the sequence.
Function has no arguments.
Exit codes
0: If the recording was resumed.
_mock.sequence.record.start
Starts recording a new sequence of mock calls.
Function has no arguments.
Exit codes
0: If the recording was started.
_mock.sequence.record.stop
Stops recording of mock calls in the sequence.
Function has no arguments.
Exit codes
0: If the recording was stopped.
@parametrize.apply
Applies multiple parametrizer functions to a test function.
STDLIB_TESTING_PARAMETRIZE_SETTING_DEBUG_BOOLEAN boolean keyword: Whether to show debug information (default=”0”).
STDLIB_TESTING_PARAMETRIZE_SETTING_FIELD_SEPARATOR string keyword: The field separator for scenarios (default=”;”).
STDLIB_TESTING_PARAMETRIZE_SETTING_FIXTURE_COMMAND_PREFIX string keyword: The prefix for fixture commands (default=”@fixture “).
STDLIB_TESTING_PARAMETRIZE_SETTING_PREFIX string keyword: The prefix for parametrizer functions (default=”@parametrize_with_”).
STDLIB_TESTING_PARAMETRIZE_SETTING_SHOW_ORIGINAL_TEST_NAMES_BOOLEAN boolean keyword: Whether to show original test names (default=”0”).
STDLIB_TESTING_PARAMETRIZE_SETTING_VARIANT_TAG string keyword: The tag in the test function name to replace (default=”@vary”).
Arguments
$1 (string): The name of the test function to parametrize.
… (array): A series of parametrizer functions to apply.
Exit codes
0: If the parametrizer functions were applied successfully.
123: If a variable reserved for use by the BASH stdlib has been assigned an invalid value.
125: If an invalid keyword has been provided.
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.
@parametrize.compose
Composes multiple parametrizer functions to create a product of scenarios.
STDLIB_TESTING_PARAMETRIZE_SETTING_DEBUG_BOOLEAN boolean keyword: Whether to show debug information (default=”0”).
STDLIB_TESTING_PARAMETRIZE_SETTING_FIELD_SEPARATOR string keyword: The field separator for scenarios (default=”;”).
STDLIB_TESTING_PARAMETRIZE_SETTING_FIXTURE_COMMAND_PREFIX string keyword: The prefix for fixture commands (default=”@fixture “).
STDLIB_TESTING_PARAMETRIZE_SETTING_PREFIX string keyword: The prefix for parametrizer functions (default=”@parametrize_with_”).
STDLIB_TESTING_PARAMETRIZE_SETTING_SHOW_ORIGINAL_TEST_NAMES_BOOLEAN boolean keyword: Whether to show original test names (default=”0”).
STDLIB_TESTING_PARAMETRIZE_SETTING_VARIANT_TAG string keyword: The tag in the test function name to replace (default=”@vary”).
Arguments
$1 (string): The name of the test function to parametrize.
… (array): A series of parametrizer functions to compose.
Exit codes
0: If the parametrizer functions were composed successfully.
123: If a variable reserved for use by the BASH stdlib has been assigned an invalid value.
125: If an invalid keyword has been provided.
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.
@parametrize
Parametrizes a test function with multiple scenarios.
STDLIB_TESTING_THEME_PARAMETRIZE_HIGHLIGHT string global: A theme colour used to highlight informational messages (default=”LIGHT_BLUE”).
STDLIB_TESTING_PARAMETRIZE_SETTING_DEBUG_BOOLEAN boolean keyword: Whether to show debug information (default=”0”).
STDLIB_TESTING_PARAMETRIZE_SETTING_FIELD_SEPARATOR string keyword: The field separator for scenarios (default=”;”).
STDLIB_TESTING_PARAMETRIZE_SETTING_FIXTURE_COMMAND_PREFIX string keyword: The prefix for fixture commands (default=”@fixture “).
STDLIB_TESTING_PARAMETRIZE_SETTING_SHOW_ORIGINAL_TEST_NAMES_BOOLEAN boolean keyword: Whether to show original test names (default=”0”).
STDLIB_TESTING_PARAMETRIZE_SETTING_VARIANT_TAG string keyword: The tag in the test function name to replace (default=”@vary”).
Arguments
$1 (string): The name of the test function to parametrize.
… (array): Optional fixture commands (prefixed with ‘@fixture ‘), followed by a semicolon-separated list of variable names, and then one or more semicolon-separated scenarios (scenario name followed by values).
Exit codes
0: If the test function was parametrized successfully.
123: If a variable reserved for use by the BASH stdlib has been assigned an invalid value.
125: If an invalid keyword has been provided.
126: If an invalid argument has been provided.
127: If the wrong number of arguments were provided.
Output on stdout
The informational messages.
Output on stderr
The error message if the operation fails.