object

# `lgtunit`

A unit test framework supporting predicate clause coverage, determinism testing, input/output testing, property-based testing, and multiple test dialects.

Availability:
`logtalk_load(lgtunit(loader))`
Author: Paulo Moura
Version: 16:7:0
Date: 2023-12-07
Compilation flags:
`static, context_switching_calls`
Implements:
`public` expanding
Provides:
logtalk::trace_event/2
Uses:
fast_random
list
logtalk
os
type
user
Remarks:

> - Usage: Define test objects as extensions of the `lgtunit` object and compile their source files using the compiler option `hook(lgtunit)`.

> - Portability: Deterministic unit tests are currently not available when using Quintus Prolog as the backend compiler.

> - Known issues: Parameter variables cannot currently be used in the definition of test options.

Inherited public predicates:
goal_expansion/2 term_expansion/2

## Public predicates

### `cover/1`

Declares entities being tested for which code coverage information should be collected.

Compilation flags:
`static`
Template:
`cover(Entity)`
Mode and number of proofs:
`cover(?entity_identifier)` - `zero_or_more`

### `run/0`

Runs the unit tests, writing the results to the current output stream.

Compilation flags:
`static`
Mode and number of proofs:
`run` - `one`

### `run/1`

Runs a unit test or a list of unit tests, writing the results to the current output stream. Runs the global setup and cleanup steps when defined. Fails when given a partial list of tests or when one of the test identifiers is not valid.

Compilation flags:
`static`
Template:
`run(Tests)`
Mode and number of proofs:
`run(++callable)` - `zero_or_one`
`run(++list(callable))` - `zero_or_one`

### `run/2`

Runs the unit tests, writing the results to the specified file. Mode can be either `write` (to create a new file) or `append` (to add results to an existing file).

Compilation flags:
`static`
Template:
`run(File,Mode)`
Mode and number of proofs:
`run(+atom,+atom)` - `one`

### `run_test_sets/1`

Runs two or more test sets as a unified set generating a single code coverage report if one is requested. Fails if the list does not contains at least two test objects.

Compilation flags:
`static`
Template:
`run_test_sets(TestObjects)`
Mode and number of proofs:
`run_test_sets(+list(object_identifier))` - `zero_or_one`

### `test/1`

Enumerates, by backtracking, the identifiers of all defined unit tests.

Compilation flags:
`static`
Template:
`test(Identifier)`
Mode and number of proofs:
`test(?callable)` - `zero_or_more`

### `number_of_tests/1`

Number of defined unit tests.

Compilation flags:
`static`
Template:
`number_of_tests(NumerOfTests)`
Mode and number of proofs:
`number_of_tests(?integer)` - `zero_or_one`

### `deterministic/1`

True if the goal succeeds once without leaving choice-points.

Compilation flags:
`static`
Template:
`deterministic(Goal)`
Meta-predicate template:
`deterministic(0)`
Mode and number of proofs:
`deterministic(+callable)` - `zero_or_one`

### `deterministic/2`

Reified version of the `deterministic/1` predicate. True if the goal succeeds. Returns a boolean value (`true` or `false`) indicating if the goal succeeded without leaving choice-points.

Compilation flags:
`static`
Template:
`deterministic(Goal,Deterministic)`
Meta-predicate template:
`deterministic(0,*)`
Mode and number of proofs:
`deterministic(+callable,--atom)` - `zero_or_one`

### `assertion/1`

True if the assertion goal succeeds. Throws an error using the assertion goal as argument if the assertion goal throws an error or fails.

Compilation flags:
`static`
Template:
`assertion(Assertion)`
Meta-predicate template:
`assertion(::)`
Mode and number of proofs:
`assertion(@callable)` - `one`
Exceptions:
Assertion goal fails:
`assertion_failure(Assertion)`
Assertion goal throws Error:
`assertion_error(Assertion,Error)`

### `assertion/2`

True if the assertion goal succeeds. Throws an error using the description as argument if the assertion goal throws an error or fails. The description argument helps to distinguish between different assertions in the same test body.

Compilation flags:
`static`
Template:
`assertion(Description,Assertion)`
Meta-predicate template:
`assertion(*,0)`
Mode and number of proofs:
`assertion(+nonvar,@callable)` - `one`
Exceptions:
Assertion goal fails:
`assertion_failure(Description)`
Assertion goal throws Error:
`assertion_error(Description,Error)`

### `quick_check/3`

Reified version of the `quick_check/2` predicate. Reports `passed(SequenceSeed,Discarded,Labels)`, `failed(Goal,SequenceSeed,TestSeed)`, `error(Error,Goal,SequenceSeed,TestSeed)`, or `broken(Why,Culprit)`. `Goal` is the failed test.

Compilation flags:
`static`
Template:
`quick_check(Template,Result,Options)`
Meta-predicate template:
`quick_check(::,*,::)`
Mode and number of proofs:
`quick_check(@callable,-callable,++list(compound))` - `one`
Remarks:

> - `SequenceSeed` argument: Can be used to re-run the same exact sequence of pseudo-random tests by using the `rs/1` option after changes to the code being tested.

> - `TestSeed` argument: Can be used to re-run the test that failed by using the `rs/1` option after changes to the code being tested.

> - `Discarded` argument: Number of generated tests that were discarded for failing to comply a pre-condition specified using the `pc/1` option.

> - `Labels` argument: List of pairs `Label-N` where `N` is the number of generated tests that are classified as `Label` by a closure specified using the `l/1` option.

> - `broken(Why,Culprit)` result: This result signals a broken setup. For example, an invalid template, a broken pre-condition or label goal, or broken test generation.

### `quick_check/2`

Generates and runs random tests for a predicate given its mode template and a set of options. Fails when a generated test fails printing the test. Also fails on an invalid option, printing the option.

Compilation flags:
`static`
Template:
`quick_check(Template,Options)`
Meta-predicate template:
`quick_check(::,::)`
Mode and number of proofs:
`quick_check(@callable,++list(compound))` - `zero_or_one`
Remarks:

> - Number of tests: Use the `n(NumberOfTests)` option to specify the number of random tests. Default is 100.

> - Maximum number of shrink operations: Use the `s(MaxShrinks)` option to specify the number of shrink operations when a counter example is found. Default is 64.

> - Type edge cases: Use the `ec(Boolean)` option to specify if type edge cases are tested (before generating random tests). Default is `true`.

> - Starting seed: Use the `rs(Seed)` option to specify the random generator starting seed to be used when generating tests. No default. Seeds should be regarded as opaque terms.

> - Test generation filtering: Use the `pc/1` option to specify a pre-condition closure for filtering generated tests (extended with the test arguments; no default).

> - Generated tests classification: Use the `l/1` option to specify a label closure for classifying the generated tests (extended with the test arguments plus the labels argument; no default). The labelling predicate can return a single test label or a list of test labels.

> - Verbose test generation: Use the `v(Boolean)` option to specify verbose reporting of generated random tests. Default is `false`.

> - Progress bar: Use the `pb(Boolean,Tick)` option to print a progress bar for the executed tests, advancing at every `Tick` tests. Default is `false`. Only applies when the verbose option is false.

### `quick_check/1`

Generates and runs random tests using default options for a predicate given its mode template. Fails when a generated test fails printing the test.

Compilation flags:
`static`
Template:
`quick_check(Template)`
Mode and number of proofs:
`quick_check(@callable)` - `zero_or_one`

### `benchmark/2`

Benchmarks a goal and returns the total execution time in seconds. Uses CPU clock. Goals that may throw an exception should be wrapped by the `catch/3` control construct.

Compilation flags:
`static`
Template:
`benchmark(Goal,Time)`
Meta-predicate template:
`benchmark(0,*)`
Mode and number of proofs:
`benchmark(+callable,-float)` - `one`

### `benchmark_reified/3`

Benchmarks a goal and returns the total execution time in seconds plus its result (`success`, `failure`, or `error(Error))`. Uses CPU clock.

Compilation flags:
`static`
Template:
`benchmark_reified(Goal,Time,Result)`
Meta-predicate template:
`benchmark_reified(0,*,*)`
Mode and number of proofs:
`benchmark_reified(+callable,-float,-callable)` - `one`

### `benchmark/3`

Benchmarks a goal by repeating it the specified number of times and returning the total execution time in seconds. Uses CPU clock. Goals that may throw an exception should be wrapped by the `catch/3` control construct.

Compilation flags:
`static`
Template:
`benchmark(Goal,Repetitions,Time)`
Meta-predicate template:
`benchmark(0,*,*)`
Mode and number of proofs:
`benchmark(@callable,+positive_integer,-float)` - `one`

### `benchmark/4`

Benchmarks a goal by repeating it the specified number of times and returning the total execution time in seconds using the given clock (`cpu` or `wall`). Goals that may throw an exception should be wrapped by the `catch/3` control construct.

Compilation flags:
`static`
Template:
`benchmark(Goal,Repetitions,Clock,Time)`
Meta-predicate template:
`benchmark(0,*,*,*)`
Mode and number of proofs:
`benchmark(@callable,+positive_integer,+atom,-float)` - `one`

### `variant/2`

True when the two arguments are a variant of each other. I.e. if is possible to rename the term variables to make them identical. Useful for checking expected test results that contain variables.

Compilation flags:
`static`
Template:
`variant(Term1,Term2)`
Mode and number of proofs:
`variant(@term,@term)` - `zero_or_one`

### `approximately_equal/2`

Compares two numbers for approximate equality given the `epsilon` arithmetic constant value using the de facto standard formula `abs(Number1 - Number2) =< max(abs(Number1), abs(Number2)) * epsilon`. Type-checked.

Compilation flags:
`static`
Template:
`approximately_equal(Number1,Number2)`
Mode and number of proofs:
`approximately_equal(+number,+number)` - `zero_or_one`

### `approximately_equal/3`

Compares two numbers for approximate equality given a user-defined epsilon value using the de facto standard formula `abs(Number1 - Number2) =< max(abs(Number1), abs(Number2)) * Epsilon`. Type-checked.

Compilation flags:
`static`
Template:
`approximately_equal(Number1,Number2,Epsilon)`
Mode and number of proofs:
`approximately_equal(+number,+number,+number)` - `zero_or_one`
Remarks:

> - Epsilon range: Epsilon should be the `epsilon` arithmetic constant value or a small multiple of it. Only use a larger value if a greater error is expected.

> - Comparison with essential equality: For the same epsilon value, approximate equality is weaker requirement than essential equality.

### `essentially_equal/3`

Compares two numbers for essential equality given an epsilon value using the de facto standard formula `abs(Number1 - Number2) =< min(abs(Number1), abs(Number2)) * Epsilon`. Type-checked.

Compilation flags:
`static`
Template:
`essentially_equal(Number1,Number2,Epsilon)`
Mode and number of proofs:
`essentially_equal(+number,+number,+number)` - `zero_or_one`
Remarks:

> - Comparison with approximate equality: For the same epsilon value, essential equality is a stronger requirement than approximate equality.

### `tolerance_equal/4`

Compares two numbers for close equality given relative and absolute tolerances using the de facto standard formula `abs(Number1 - Number2) =< max(RelativeTolerance * max(abs(Number1), abs(Number2)), AbsoluteTolerance)`. Type-checked.

Compilation flags:
`static`
Template:
`tolerance_equal(Number1,Number2,RelativeTolerance,AbsoluteTolerance)`
Mode and number of proofs:
`tolerance_equal(+number,+number,+number,+number)` - `zero_or_one`

### `=~= / 2`

Compares two numbers (or lists of numbers) for approximate equality using `100*epsilon` for the absolute error and, if that fails, `99.999%` accuracy for the relative error. But these precision values may not be adequate for all cases. Type-checked.

Compilation flags:
`static`
Template:
`=~=(Number1,Number2)`
Mode and number of proofs:
`=~=(+number,+number)` - `zero_or_one`
`=~=(+list(number),+list(number))` - `zero_or_one`

### `epsilon/1`

Returns the value of epsilon used in the definition of the `(=~=)/2` predicate.

Compilation flags:
`static`
Template:
`epsilon(Epsilon)`
Mode and number of proofs:
`epsilon(-float)` - `one`

## Protected predicates

### `run_tests/0`

Runs all defined unit tests.

Compilation flags:
`static`
Mode and number of proofs:
`run_tests` - `one`

### `run_tests/1`

Runs all the tests defined in the given file.

Compilation flags:
`static`
Template:
`run_tests(File)`
Mode and number of proofs:
`run_tests(+atom)` - `one`

### `run_test_set/0`

Runs a test set as part of running two or more test sets as a unified set.

Compilation flags:
`static`
Mode and number of proofs:
`run_test_set` - `one`

### `run_quick_check_tests/5`

Runs a list of defined tests using the given options. Returns the starting seed used to generate the random tests, the number of discarded tests, and the test label statistics.

Compilation flags:
`static`
Template:
`run_quick_check_tests(Template,Options,Seed,Discarded,Labels)`
Meta-predicate template:
`run_quick_check_tests(::,::,*,*,*)`
Mode and number of proofs:
`run_quick_check_tests(@callable,+list,--nonvar,--number,--list(pair))` - `one_or_error`

### `condition/0`

Verifies conditions for running the tests. Defaults to the goal `true`.

Compilation flags:
`static`
Mode and number of proofs:
`condition` - `zero_or_one`

### `setup/0`

Setup environment before running the test set. Defaults to the goal `true`.

Compilation flags:
`static`
Mode and number of proofs:
`setup` - `zero_or_one`

### `cleanup/0`

Cleanup environment after running the test set. Defaults to the goal `true`.

Compilation flags:
`static`
Mode and number of proofs:
`cleanup` - `zero_or_one`

### `make/1`

Make target for automatically running the test set when calling the `logtalk_make/1` built-in predicate. No default. Possible values are `all` and `check`.

Compilation flags:
`static`
Template:
`make(Target)`
Mode and number of proofs:
`make(?atom)` - `zero_or_one`

### `note/1`

Note to be printed after the test results. Defaults to the empty atom.

Compilation flags:
`static`
Template:
`note(Note)`
Mode and number of proofs:
`note(?atom)` - `zero_or_one`

### `file_path/2`

Returns the absolute path for a file path that is relative to the tests object path. When the file path is already an absolute path, it is expanded to resolve any remaining relative file path parts.

Compilation flags:
`static`
Template:
`file_path(File,Path)`
Mode and number of proofs:
`file_path(+atom,-atom)` - `one`
See also:
clean_file/1
clean_directory/1

### `suppress_text_output/0`

Suppresses text output. Useful to avoid irrelevant text output from predicates being tested to clutter the test logs.

Compilation flags:
`static`
Mode and number of proofs:
`suppress_text_output` - `one`

### `suppress_binary_output/0`

Suppresses binary output. Useful to avoid irrelevant binary output from predicates being tested to clutter the test logs.

Compilation flags:
`static`
Mode and number of proofs:
`suppress_binary_output` - `one`

### `set_text_input/3`

Creates a temporary file, in the same directory as the tests object, with the given text contents, and opens it for reading referenced by the given alias and using the additional options. If no `eof_action/1` option is specified, its value will be the default used by the backend compiler.

Compilation flags:
`static`
Template:
`set_text_input(Alias,Contents,Options)`
Mode and number of proofs:
`set_text_input(+atom,+atom,+list(stream_option))` - `one`
`set_text_input(+atom,+list(atom),+list(stream_option))` - `one`
See also:
text_input_assertion/3
check_text_input/2
clean_text_input/0

### `set_text_input/2`

Creates a temporary file, in the same directory as the tests object, with the given text contents, and opens it for reading referenced by the given alias and using the default end-of-file action for the used backend compiler.

Compilation flags:
`static`
Template:
`set_text_input(Alias,Contents)`
Mode and number of proofs:
`set_text_input(+atom,+atom)` - `one`
`set_text_input(+atom,+list(atom))` - `one`
See also:
text_input_assertion/3
check_text_input/2
clean_text_input/0

### `set_text_input/1`

Creates a temporary file, in the same directory as the tests object, with the given text contents, opens it for reading using the default end-of-file action for the used backend compiler, and sets the current input stream to the file.

Compilation flags:
`static`
Template:
`set_text_input(Contents)`
Mode and number of proofs:
`set_text_input(+atom)` - `one`
`set_text_input(+list(atom))` - `one`
See also:
text_input_assertion/2
check_text_input/1
clean_text_input/0

### `check_text_input/2`

Checks that the temporary file (referenced by the given alias) being read have the expected text contents.

Compilation flags:
`static`
Template:
`check_text_input(Alias,Contents)`
Mode and number of proofs:
`check_text_input(+atom,+atom)` - `zero_or_one`
See also:
set_text_input/2
set_text_input/2
text_input_assertion/3
clean_text_input/0

### `check_text_input/1`

Checks that the temporary file being read have the expected text contents.

Compilation flags:
`static`
Template:
`check_text_input(Contents)`
Mode and number of proofs:
`check_text_input(+atom)` - `zero_or_one`
See also:
set_text_input/1
text_input_assertion/2
clean_text_input/0

### `text_input_assertion/3`

Returns an assertion for checking that the temporary file (referenced by the given alias) being read have the expected text contents.

Compilation flags:
`static`
Template:
`text_input_assertion(Alias,Contents,Assertion)`
Mode and number of proofs:
`text_input_assertion(+atom,+atom,--callable)` - `one`
See also:
set_text_input/3
check_text_input/2
clean_text_input/0

### `text_input_assertion/2`

Returns an assertion for checking that the temporary file being read have the expected text contents.

Compilation flags:
`static`
Template:
`text_input_assertion(Contents,Assertion)`
Mode and number of proofs:
`text_input_assertion(+atom,--callable)` - `one`
See also:
set_text_input/1
check_text_input/1
clean_text_input/0

### `clean_text_input/0`

Cleans the temporary file used when testing text input.

Compilation flags:
`static`
Mode and number of proofs:
`clean_text_input` - `one`
See also:
set_text_input/3
set_text_input/2
set_text_input/1

### `set_binary_input/3`

Creates a temporary file, in the same directory as the tests object, with the given binary contents, and opens it for reading referenced by the given alias and using the additional options. If no `eof_action/1` option is specified, its value will be the default used by the backend compiler.

Compilation flags:
`static`
Template:
`set_binary_input(Alias,Bytes,Options)`
Mode and number of proofs:
`set_binary_input(+atom,+list(byte),+list(stream_option))` - `one`
See also:
binary_input_assertion/3
check_binary_input/2
clean_binary_input/0

### `set_binary_input/2`

Creates a temporary file, in the same directory as the tests object, with the given binary contents, and opens it for reading referenced by the given alias and using the default end-of-file action for the used backend compiler.

Compilation flags:
`static`
Template:
`set_binary_input(Alias,Bytes)`
Mode and number of proofs:
`set_binary_input(+atom,+list(byte))` - `one`
See also:
binary_input_assertion/3
check_binary_input/2
clean_binary_input/0

### `set_binary_input/1`

Creates a temporary file, in the same directory as the tests object, with the given binary contents, and opens it for reading using the default end-of-file action for the used backend compiler, and sets the current input stream to the file.

Compilation flags:
`static`
Template:
`set_binary_input(Bytes)`
Mode and number of proofs:
`set_binary_input(+list(byte))` - `one`
See also:
binary_input_assertion/2
check_binary_input/1
clean_binary_input/0

### `check_binary_input/2`

Checks that the temporary file (referenced by the given alias) being read have the expected binary contents.

Compilation flags:
`static`
Template:
`check_binary_input(Alias,Bytes)`
Mode and number of proofs:
`check_binary_input(+atom,+list(byte))` - `zero_or_one`
See also:
set_binary_input/3
set_binary_input/2
binary_input_assertion/3
clean_binary_input/0

### `check_binary_input/1`

Checks that the temporary file being read have the expected binary contents.

Compilation flags:
`static`
Template:
`check_binary_input(Bytes)`
Mode and number of proofs:
`check_binary_input(+list(byte))` - `zero_or_one`
See also:
binary_input_assertion/2
set_binary_input/1
clean_binary_input/0

### `binary_input_assertion/3`

Returns an assertion for checking that the temporary file (referenced by the given alias) being read have the expected binary contents.

Compilation flags:
`static`
Template:
`binary_input_assertion(Alias,Bytes,Assertion)`
Mode and number of proofs:
`binary_input_assertion(+atom,+list(byte),--callable)` - `one`
See also:
check_binary_input/2
set_binary_input/3
set_binary_input/2
clean_binary_input/0

### `binary_input_assertion/2`

Returns an assertion for checking that the temporary file being read have the expected binary contents.

Compilation flags:
`static`
Template:
`binary_input_assertion(Bytes,Assertion)`
Mode and number of proofs:
`binary_input_assertion(+list(byte),--callable)` - `one`
See also:
check_binary_input/1
set_binary_input/1
clean_binary_input/0

### `clean_binary_input/0`

Cleans the temporary file used when testing binary input.

Compilation flags:
`static`
Mode and number of proofs:
`clean_binary_input` - `one`
See also:
set_binary_input/3
set_binary_input/2
set_binary_input/1

### `set_text_output/3`

Creates a temporary file, in the same directory as the tests object, with the given text contents, and opens it for writing referenced by the given alias and using the additional options.

Compilation flags:
`static`
Template:
`set_text_output(Alias,Contents,Options)`
Mode and number of proofs:
`set_text_output(+atom,+atom,+list(stream_option))` - `one`
`set_text_output(+atom,+list(atom),+list(stream_option))` - `one`
See also:
text_output_assertion/4
check_text_output/3
clean_text_output/0

### `set_text_output/2`

Creates a temporary file, in the same directory as the tests object, with the given text contents, and referenced by the given alias.

Compilation flags:
`static`
Template:
`set_text_output(Alias,Contents)`
Mode and number of proofs:
`set_text_output(+atom,+atom)` - `one`
`set_text_output(+atom,+list(atom))` - `one`
See also:
text_output_assertion/3
check_text_output/2
clean_text_output/0

### `set_text_output/1`

Creates a temporary file, in the same directory as the tests object, with the given text contents, and sets the current output stream to the file.

Compilation flags:
`static`
Template:
`set_text_output(Contents)`
Mode and number of proofs:
`set_text_output(+atom)` - `one`
`set_text_output(+list(atom))` - `one`
See also:
text_output_assertion/2
check_text_output/1
clean_text_output/0

### `check_text_output/3`

Checks that the temporary file (open with the given options and alias in the same directory as the tests object) being written have the expected text contents.

Compilation flags:
`static`
Template:
`check_text_output(Alias,Contents,Options)`
Mode and number of proofs:
`check_text_output(+atom,+atom,+list(stream_option))` - `zero_or_one`
See also:
set_text_output/3
text_output_assertion/4
clean_text_output/0

### `check_text_output/2`

Checks that the temporary file (open with default options and alias in the same directory as the tests object) being written have the expected text contents.

Compilation flags:
`static`
Template:
`check_text_output(Alias,Contents)`
Mode and number of proofs:
`check_text_output(+atom,+atom)` - `zero_or_one`
See also:
set_text_output/2
text_output_assertion/3
clean_text_output/0

### `check_text_output/1`

Checks that the temporary file being written have the expected text contents.

Compilation flags:
`static`
Template:
`check_text_output(Contents)`
Mode and number of proofs:
`check_text_output(+atom)` - `zero_or_one`
See also:
set_text_output/1
text_output_assertion/2
clean_text_output/0

### `text_output_assertion/4`

Returns an assertion for checking that the temporary file (open with the given options and alias in the same directory as the tests object) being written have the expected text contents.

Compilation flags:
`static`
Template:
`text_output_assertion(Alias,Contents,Options,Assertion)`
Mode and number of proofs:
`text_output_assertion(+atom,+atom,+list(stream_option),--callable)` - `one`
See also:
set_text_output/3
check_text_output/3
clean_text_output/0

### `text_output_assertion/3`

Returns an assertion for checking that the temporary file (open with default options and alias in the same directory as the tests object) being written have the expected text contents.

Compilation flags:
`static`
Template:
`text_output_assertion(Alias,Contents,Assertion)`
Mode and number of proofs:
`text_output_assertion(+atom,+atom,--callable)` - `one`
See also:
set_text_output/2
check_text_output/2
clean_text_output/0

### `text_output_assertion/2`

Returns an assertion for checking that the temporary file (open with default options in the same directory as the tests object) being written have the expected text contents.

Compilation flags:
`static`
Template:
`text_output_assertion(Contents,Assertion)`
Mode and number of proofs:
`text_output_assertion(+atom,--callable)` - `one`
See also:
set_text_output/1
check_text_output/1
clean_text_output/0

### `text_output_contents/3`

Returns the contents of the temporary file (open with the given options and alias in the same directory as the tests object) being written.

Compilation flags:
`static`
Template:
`text_output_contents(Alias,Contents,Options)`
Mode and number of proofs:
`text_output_contents(+atom,-list(character),+list(stream_option))` - `one`

### `text_output_contents/2`

Returns the contents of the temporary file (open with default options and alias in the same directory as the tests object) being written.

Compilation flags:
`static`
Template:
`text_output_contents(Alias,Contents)`
Mode and number of proofs:
`text_output_contents(+atom,-list(character))` - `one`

### `text_output_contents/1`

Returns the contents of the temporary file (open with default options in the same directory as the tests object) being written.

Compilation flags:
`static`
Template:
`text_output_contents(Contents)`
Mode and number of proofs:
`text_output_contents(-list(character))` - `one`

### `clean_text_output/0`

Cleans the temporary file used when testing text output.

Compilation flags:
`static`
Mode and number of proofs:
`clean_text_output` - `one`
See also:
set_text_output/3
set_text_output/2
set_text_output/1

### `set_binary_output/3`

Creates a temporary file, in the same directory as the tests object, with the given binary contents, and opens it for writing referenced by the given alias and using the additional options.

Compilation flags:
`static`
Template:
`set_binary_output(Alias,Contents,Options)`
Mode and number of proofs:
`set_binary_output(+atom,+list(byte),+list(stream_option))` - `one`
See also:
binary_output_assertion/3
check_binary_output/2
clean_binary_output/0

### `set_binary_output/2`

Creates a temporary file, in the same directory as the tests object, with the given binary contents, and opens it for writing referenced with the given alias.

Compilation flags:
`static`
Template:
`set_binary_output(Alias,Bytes)`
Mode and number of proofs:
`set_binary_output(+atom,+list(byte))` - `one`
See also:
binary_output_assertion/3
check_binary_output/2
clean_binary_output/0

### `set_binary_output/1`

Creates a temporary file, in the same directory as the tests object, with the given binary contents, and sets the current output stream to the file.

Compilation flags:
`static`
Template:
`set_binary_output(Bytes)`
Mode and number of proofs:
`set_binary_output(+list(byte))` - `one`
See also:
binary_output_assertion/2
check_binary_output/1
clean_binary_output/0

### `check_binary_output/2`

Checks that the temporary file (referenced by the given alias) have the expected binary contents.

Compilation flags:
`static`
Template:
`check_binary_output(Alias,Bytes)`
Mode and number of proofs:
`check_binary_output(+atom,+list(byte))` - `zero_or_one`
See also:
set_binary_output/3
set_binary_output/2
binary_output_assertion/3
clean_binary_output/0

### `check_binary_output/1`

Checks that the temporary file (open in the same directory as the tests object) have the expected binary contents.

Compilation flags:
`static`
Template:
`check_binary_output(Bytes)`
Mode and number of proofs:
`check_binary_output(+list(byte))` - `zero_or_one`
See also:
set_binary_output/1
binary_output_assertion/2
clean_binary_output/0

### `binary_output_assertion/3`

Returns an assertion for checking that the temporary file (referenced by the given alias) have the expected binary contents.

Compilation flags:
`static`
Template:
`binary_output_assertion(Alias,Bytes,Assertion)`
Mode and number of proofs:
`binary_output_assertion(+atom,+list(byte),--callable)` - `one`
See also:
set_binary_output/2
check_binary_output/2
clean_binary_output/0

### `binary_output_assertion/2`

Returns an assertion for checking that the temporary file (open in the same directory as the tests object) have the expected binary contents.

Compilation flags:
`static`
Template:
`binary_output_assertion(Bytes,Assertion)`
Mode and number of proofs:
`binary_output_assertion(+list(byte),--callable)` - `one`
See also:
set_binary_output/1
check_binary_output/1
clean_binary_output/0

### `binary_output_contents/2`

Returns the binary contents of the temporary file (referenced by the given alias) being written.

Compilation flags:
`static`
Template:
`binary_output_contents(Alias,Bytes)`
Mode and number of proofs:
`binary_output_contents(+atom,-list(byte))` - `one`

### `binary_output_contents/1`

Returns the binary contents of the temporary file being written.

Compilation flags:
`static`
Template:
`binary_output_contents(Bytes)`
Mode and number of proofs:
`binary_output_contents(-list(byte))` - `one`

### `clean_binary_output/0`

Cleans the temporary file used when testing binary output.

Compilation flags:
`static`
Mode and number of proofs:
`clean_binary_output` - `one`
See also:
set_binary_output/3
set_binary_output/2
set_binary_output/1

### `create_text_file/3`

Creates a text file with the given contents. The file is open for writing using the given options. Relative file paths are interpreted as relative to the tests object path.

Compilation flags:
`static`
Template:
`create_text_file(File,Contents,Options)`
Mode and number of proofs:
`create_text_file(+atom,+atom,+list(stream_option))` - `one`
`create_text_file(+atom,+list(atom),+list(stream_option))` - `one`

### `create_text_file/2`

Creates a text file with the given contents. The file is open for writing using default options. Relative file paths are interpreted as relative to the tests object path.

Compilation flags:
`static`
Template:
`create_text_file(File,Contents)`
Mode and number of proofs:
`create_text_file(+atom,+atom)` - `one`
`create_text_file(+atom,+list(atom))` - `one`

### `create_binary_file/2`

Creates a binary file with the given contents. Relative file paths are interpreted as relative to the tests object path.

Compilation flags:
`static`
Template:
`create_binary_file(File,Bytes)`
Mode and number of proofs:
`create_binary_file(+atom,+list(byte))` - `one`

### `check_text_file/3`

Checks that the contents of a text file match the expected contents. The file is open for reading using the given options. Relative file paths are interpreted as relative to the tests object path.

Compilation flags:
`static`
Template:
`check_text_file(File,Contents,Options)`
Mode and number of proofs:
`check_text_file(+atom,+atom,+list(stream_option))` - `zero_or_one`
See also:
text_file_assertion/4

### `check_text_file/2`

Checks that the contents of a text file (open for reading using default options) match the expected contents. Relative file paths are interpreted as relative to the tests object path.

Compilation flags:
`static`
Template:
`check_text_file(File,Contents)`
Mode and number of proofs:
`check_text_file(+atom,+atom)` - `zero_or_one`
See also:
text_file_assertion/3

### `text_file_assertion/4`

Returns an assertion for checking that the given file have the expected text contents. The file is open for reading using the given options. Relative file paths are interpreted as relative to the tests object path.

Compilation flags:
`static`
Template:
`text_file_assertion(File,Contents,Options,Assertion)`
Mode and number of proofs:
`text_file_assertion(+atom,+atom,+list(stream_option),--callable)` - `one`
See also:
check_text_file/3

### `text_file_assertion/3`

Returns an assertion for checking that the given file have the expected text contents. The file is open for reading using default options. Relative file paths are interpreted as relative to the tests object path.

Compilation flags:
`static`
Template:
`text_file_assertion(File,Contents,Assertion)`
Mode and number of proofs:
`text_file_assertion(+atom,+atom,--callable)` - `one`
See also:
check_text_file/2

### `check_binary_file/2`

Checks the contents of a binary file match the expected contents. Relative file paths are interpreted as relative to the tests object path.

Compilation flags:
`static`
Template:
`check_binary_file(File,Bytes)`
Mode and number of proofs:
`check_binary_file(+atom,+list(byte))` - `zero_or_one`
See also:
binary_file_assertion/3

### `binary_file_assertion/3`

Returns an assertion for checking that the given file have the expected binary contents. Relative file paths are interpreted as relative to the tests object path.

Compilation flags:
`static`
Template:
`binary_file_assertion(File,Bytes,Assertion)`
Mode and number of proofs:
`binary_file_assertion(+atom,+list(byte),--callable)` - `one`
See also:
check_binary_file/2

### `clean_file/1`

Closes any existing stream associated with the file and deletes the file if it exists. Relative file paths are interpreted as relative to the tests object path.

Compilation flags:
`static`
Template:
`clean_file(File)`
Mode and number of proofs:
`clean_file(+atom)` - `one`
See also:
clean_directory/1
file_path/2

### `clean_directory/1`

Deletes an empty directory if it exists. Relative directory paths are interpreted as relative to the tests object path.

Compilation flags:
`static`
Template:
`clean_directory(Directory)`
Mode and number of proofs:
`clean_directory(+atom)` - `one`
See also:
clean_file/1
file_path/2

### `closed_input_stream/2`

Opens a temporary file in the same directory as the tests object with the given options for reading, closes it, and returns its stream handle.

Compilation flags:
`static`
Template:
`closed_input_stream(Stream,Options)`
Mode and number of proofs:
`closed_input_stream(-stream,+list(stream_option))` - `one`

### `closed_output_stream/2`

Opens a temporary file in the same directory as the tests object with the given options for writing, closes it, and returns its stream handle.

Compilation flags:
`static`
Template:
`closed_output_stream(Stream,Options)`
Mode and number of proofs:
`closed_output_stream(-stream,+list(stream_option))` - `zero_or_one`

### `stream_position/1`

Returns a syntactically valid stream position by opening a temporary file in the same directory as the tests object.

Compilation flags:
`static`
Template:
`stream_position(Position)`
Mode and number of proofs:
`stream_position(-stream_position)` - `one`

### `test/2`

Table of defined tests.

Compilation flags:
`static`
Template:
`test(Identifier,Test)`
Mode and number of proofs:
`test(?callable,?compound)` - `zero_or_more`

## Private predicates

### `running_test_sets_/0`

Internal flag used when running two or more test sets as a unified set.

Compilation flags:
`dynamic`
Mode and number of proofs:
`running_test_sets_` - `zero_or_one`

### `test/3`

Compiled unit tests. The list of variables is used to ensure variable sharing between a test with its test options.

Compilation flags:
`static`
Template:
`test(Identifier,Variables,Outcome)`
Meta-predicate template:
`test(*,*,*)`
Mode and number of proofs:
`test(?callable,?list(variable),?nonvar)` - `zero_or_more`

### `auxiliary_predicate_counter_/1`

Counter for generating unique auxiliary predicate names.

Compilation flags:
`dynamic`
Template:
`auxiliary_predicate_counter_(Counter)`
Mode and number of proofs:
`auxiliary_predicate_counter_(?integer)` - `one_or_more`

### `test_/2`

Table of compiled tests.

Compilation flags:
`dynamic`
Template:
`test_(Identifier,Test)`
Mode and number of proofs:
`test_(?callable,?compound)` - `zero_or_more`

### `skipped_/1`

Counter for skipped tests.

Compilation flags:
`dynamic`
Template:
`skipped_(Counter)`
Mode and number of proofs:
`skipped_(?integer)` - `zero_or_one`

### `passed_/2`

Counter and total time for passed tests.

Compilation flags:
`dynamic`
Template:
`passed_(Counter,Time)`
Mode and number of proofs:
`passed_(?integer,-float)` - `zero_or_one`

### `failed_/2`

Counter and total time for failed tests.

Compilation flags:
`dynamic`
Template:
`failed_(Counter,Time)`
Mode and number of proofs:
`failed_(?integer,-float)` - `zero_or_one`

### `flaky_/1`

Counter for failed tests that are marked as flaky.

Compilation flags:
`dynamic`
Template:
`flaky_(Counter)`
Mode and number of proofs:
`flaky_(?integer)` - `zero_or_one`

### `fired_/3`

Fired clauses when running the unit tests.

Compilation flags:
`dynamic`
Template:
`fired_(Entity,Predicate,Clause)`
Mode and number of proofs:
`fired_(?entity_identifier,?predicate_indicator,?integer)` - `zero_or_more`

### `covered_/4`

Auxiliary predicate for collecting statistics on clause coverage.

Compilation flags:
`dynamic`
Template:
`covered_(Entity,Predicate,Covered,Total)`
Mode and number of proofs:
`covered_(?entity_identifier,?callable,?integer,?integer)` - `zero_or_more`

## Operators

### `op(700,xfx,=~=)`

Scope:
`public`