object

# lgtunit

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

author:
  `Paulo Moura`
version:
  `2.11`
date:
  `2016/3/20`

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/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`

### run/0

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

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

### deterministic/1

> True if a 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`

### benchmark/2

> Benchmarks a goal and returns the total execution time in seconds.

compilation flags:
  `static`
template:
  `benchmark(Goal,Time)`
meta-predicate template:
  `benchmark(0,*)`
mode – number of proofs:
  `benchmark(+callable,-float) – zero_or_one`

### benchmark/3

> Benchmarks a goal by repeating it the specified number of times and returning the total execution time in seconds.

compilation flags:
  `static`
template:
  `benchmark(Goal,Repetitions,Time)`
meta-predicate template:
  `benchmark(0,*,*)`
mode – number of proofs:
  `benchmark(+callable,+integer,-float) – 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`

## 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`

### 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_/2

> Auxiliary predicate for collecting statistics on clause coverage.

compilation flags:
  `dynamic`
template:
  `covered_(Covered,Total)`
mode – number of proofs:
  `covered_(?integer,?integer) – zero_or_more`

## Operators

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

## Remarks

### (none)

## See also

### (none)