object

# lgtunit

> A unit test framework supporting predicate clause coverage, determinism testing, input/output testing, quick-check testing, and multiple test dialects.

author:
  `Paulo Moura`
version:
  `4.6`
date:
  `2017/7/22`

compilation flags:
  `static, context_switching_calls`

implements:
  `public expanding`
provides:
  `logtalk::trace_event/2`

## Public interface

### cover/1

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

compilation flags:
  `static`
template:
  `cover(Entity)`
mode – 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 – 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, failing if either step fails.

compilation flags:
  `static`
template:
  `run(Tests)`
mode – number of proofs:
  `run(+atom) – zero_or_one`
  `run(+list(atom)) – 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 – number of proofs:
  `run(+atom,+atom) – 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 – number of proofs:
  `deterministic(+callable) – zero_or_one`

### assertion/2

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

compilation flags:
  `static`
template:
  `assertion(Assertion,Goal)`
meta-predicate template:
  `assertion(*,0)`
mode – number of proofs:
  `assertion(+nonvar,+callable) – one`
exceptions:
  Goal fails: `assertion_failure(Assertion)`
  Goal throws Error: `assertion_error(Assertion,Error)`

### quick_check/3

> Generates and runs random tests for a given predicate given its mode template reporting the result in reified form: "passed" or "failed(Goal)" where Goal is the test that failed. Accepts an option n(NumberOfTests). Default is to run 100 random tests.

compilation flags:
  `static`
template:
  `quick_check(Template,Result,Options)`
mode – number of proofs:
  `quick_check(@callable,-callable,++list(compound)) – one`

### quick_check/2

> Generates and runs random tests for a given predicate given its mode template. Fails when a random generated test fails printing the test. Accepts an option n(NumberOfTests). Default is to run 100 random tests.

compilation flags:
  `static`
template:
  `quick_check(Template,Options)`
mode – number of proofs:
  `quick_check(@callable,++list(compound)) – zero_or_one`

### quick_check/1

> Generates and runs 100 random tests for a given predicate given its mode template. Fails when a random generated call fails printing the test.

compilation flags:
  `static`
template:
  `quick_check(Template)`
mode – number of proofs:
  `quick_check(@callable) – zero_or_one`

### benchmark/2

> Benchmarks a goal and returns the total execution time in seconds. 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 – number of proofs:
  `benchmark(+callable,-float) – one`

### benchmark/3

> Benchmarks a goal by repeating it the specified number of times and returning the total execution time in seconds. 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 – number of proofs:
  `benchmark(+callable,+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 – number of proofs:
  `benchmark(+callable,+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 – number of proofs:
  `variant(@term,@term) – zero_or_one`

### =~= / 2

> Compares two floats for approximate equality using 100*epsilon for the absolute error and, if that fails, 99.999% accuracy for the relative error. Handy when writing certain unit tests but the default precision values may not be adequate for all cases.

compilation flags:
  `static`
template:
  `=~=(Float1,Float2)`
mode – number of proofs:
  `=~=(+float,+float) – 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 – number of proofs:
  `epsilon(-float) – one`

## Protected interface

### run_tests/0

> Runs all defined unit tests.

compilation flags:
  `static`
mode – number of proofs:
  `run_tests – one`

### run_tests/2

> Runs a list of defined tests.

compilation flags:
  `static`
template:
  `run_tests(Tests,File)`
mode – number of proofs:
  `run_tests(+list(callable),+atom) – one`

### run_quick_check_tests/2

> Runs a list of defined tests.

compilation flags:
  `static`
template:
  `run_quick_check_tests(Template,NumberOfTests)`
mode – number of proofs:
  `run_quick_check_tests(@callable,+integer) – one_or_error`

### condition/0

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

compilation flags:
  `static`
mode – 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 – 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 – number of proofs:
  `cleanup – zero_or_one`

### note/1

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

compilation flags:
  `static`
mode – number of proofs:
  `note(?atom) – zero_or_one`

### set_text_input/3

> Creates a temporary file with the given text contents and opens it for reading referenced by the given alias and using the additional options. If not 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 – number of proofs:
  `set_text_input(+atom,+atom,+list(stream_option)) – one`

### set_text_input/2

> Creates a temporary file 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 – number of proofs:
  `set_text_input(+atom,+atom) – one`

### set_text_input/1

> Creates a temporary file 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 – number of proofs:
  `set_text_input(+atom) – one`

### check_text_input/2

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

compilation flags:
  `static`
template:
  `check_text_input(Alias,Contents)`
mode – number of proofs:
  `check_text_input(+atom,+atom) – zero_or_one`

### check_text_input/1

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

compilation flags:
  `static`
template:
  `check_text_input(Contents)`
mode – number of proofs:
  `check_text_input(+atom) – zero_or_one`

### clean_text_input/0

> Cleans the temporary file used when testing text input.

compilation flags:
  `static`
mode – number of proofs:
  `clean_text_input – one`

### set_binary_input/3

> Creates a temporary file with the given binary contents and opens it for reading referenced by the given alias and using the additional options. If not 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 – number of proofs:
  `set_binary_input(+atom,+list(byte),+list(stream_option)) – one`

### set_binary_input/2

> Creates a temporary file 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 – number of proofs:
  `set_binary_input(+atom,+list(byte)) – one`

### set_binary_input/1

> Creates a temporary file with the given binary 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_binary_input(Bytes)`
mode – number of proofs:
  `set_binary_input(+list(byte)) – one`

### check_binary_input/2

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

compilation flags:
  `static`
template:
  `check_binary_input(Alias,Bytes)`
mode – number of proofs:
  `check_binary_input(+atom,+list(byte)) – zero_or_one`

### check_binary_input/1

> Checks that the temporary file have the expected binary contents.

compilation flags:
  `static`
template:
  `check_binary_input(Bytes)`
mode – number of proofs:
  `check_binary_input(+list(byte)) – zero_or_one`

### clean_binary_input/0

> Cleans the temporary file used when testing binary input.

compilation flags:
  `static`
mode – number of proofs:
  `clean_binary_input – one`

### set_text_output/2

> Creates a temporary file with the given text contents and referenced with the given alias.

compilation flags:
  `static`
template:
  `set_text_output(Alias,Contents)`
mode – number of proofs:
  `set_text_output(+atom,+atom) – one`

### set_text_output/1

> Creates a temporary file with the given text contents and sets the current output stream to the file.

compilation flags:
  `static`
template:
  `set_text_output(Contents)`
mode – number of proofs:
  `set_text_output(+atom) – one`

### check_text_output/2

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

compilation flags:
  `static`
template:
  `check_text_output(Alias,Contents)`
mode – number of proofs:
  `check_text_output(+atom,+atom) – zero_or_one`

### 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 – number of proofs:
  `check_text_output(+atom) – zero_or_one`

### clean_text_output/0

> Cleans the temporary file used when testing text output.

compilation flags:
  `static`
mode – number of proofs:
  `clean_text_output – one`

### set_binary_output/2

> Creates a temporary file with the given binary contents and referenced with the given alias.

compilation flags:
  `static`
template:
  `set_binary_output(Alias,Bytes)`
mode – number of proofs:
  `set_binary_output(+atom,+list(byte)) – one`

### set_binary_output/1

> Creates a temporary file with the given binary contents and sets the current output stream to the file.

compilation flags:
  `static`
template:
  `set_binary_output(Bytes)`
mode – number of proofs:
  `set_binary_output(+list(byte)) – one`

### check_binary_output/2

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

compilation flags:
  `static`
template:
  `check_binary_output(Alias,Bytes)`
mode – number of proofs:
  `check_binary_output(+atom,+list(byte)) – zero_or_one`

### check_binary_output/1

> Checks that the temporary file have the expected binary contents.

compilation flags:
  `static`
template:
  `check_binary_output(Bytes)`
mode – number of proofs:
  `check_binary_output(+list(byte)) – zero_or_one`

### clean_binary_output/0

> Cleans the temporary file used when testing binary output.

compilation flags:
  `static`
mode – number of proofs:
  `clean_binary_output – one`

### create_text_file/2

> Creates a text file with the given contents.

compilation flags:
  `static`
template:
  `create_text_file(File,Contents)`
mode – number of proofs:
  `create_text_file(+atom,+atom) – one`

### create_binary_file/2

> Creates a binary file with the given contents.

compilation flags:
  `static`
template:
  `create_binary_file(File,Bytes)`
mode – number of proofs:
  `create_binary_file(+atom,+list(byte)) – one`

### check_text_file/2

> Checks that the contents of a text file match the expected contents.

compilation flags:
  `static`
template:
  `check_text_file(File,Contents)`
mode – number of proofs:
  `check_text_file(+atom,+atom) – zero_or_one`

### check_binary_file/2

> Checks the contents of a binary file match the expected contents.

compilation flags:
  `static`
template:
  `check_binary_file(File,Bytes)`
mode – number of proofs:
  `check_binary_file(+atom,+list(byte)) – zero_or_one`

### clean_file/1

> Closes any existing stream associated with the file and deletes the file if it exists.

compilation flags:
  `static`
template:
  `clean_file(File)`
mode – number of proofs:
  `clean_file(+atom) – one`

### closed_input_stream/2

> Opens a temporary file with the given options for reading, closes it, and returns its stream handle.

compilation flags:
  `static`
template:
  `closed_input_stream(Stream,Options)`
mode – number of proofs:
  `closed_input_stream(-stream,+list(stream_option)) – one`

### closed_output_stream/2

> Opens a temporary file with the given options for writing, closes it, and returns its stream handle.

compilation flags:
  `static`
template:
  `closed_output_stream(Stream,Options)`
mode – number of proofs:
  `closed_output_stream(-stream,+list(stream_option)) – zero_or_one`

### stream_position/1

> Returns a syntactically valid stream position.

compilation flags:
  `static`
template:
  `stream_position(Position)`
mode – number of proofs:
  `stream_position(-stream_position) – one`

## Private predicates

### test/3

> Specifies a unit test.

compilation flags:
  `static`
template:
  `test(Identifier,Variables,Outcome)`
mode – number of proofs:
  `test(?atom,?list(variable),?nonvar) – zero_or_more`

### test_/2

> Table of defined tests.

compilation flags:
  `dynamic`
template:
  `test_(Identifier,Test)`
mode – number of proofs:
  `test_(?atom,?compound) – zero_or_more`

### skipped_/1

> Counter for skipped tests.

compilation flags:
  `dynamic`
template:
  `skipped_(Counter)`
mode – number of proofs:
  `skipped_(?integer) – zero_or_one`

### passed_/1

> Counter for passed tests.

compilation flags:
  `dynamic`
template:
  `passed_(Counter)`
mode – number of proofs:
  `passed_(?integer) – zero_or_one`

### failed_/1

> Counter for failed tests.

compilation flags:
  `dynamic`
template:
  `failed_(Counter)`
mode – number of proofs:
  `failed_(?callable) – zero_or_one`

### fired_/3

> Fired clauses when running the unit tests.

compilation flags:
  `dynamic`
template:
  `fired_(Entity,Predicate,Clause)`
mode – 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 – number of proofs:
  `covered_(?entity_identifier,?callable,?integer,?integer) – zero_or_more`

## Operators

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

## Remarks

### (none)

## See also

### (none)