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:
6.24
date:
2018/8/1
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

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 – number of proofs:
run_test_sets(+list(object_identifier)) – 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 – 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 – 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 – 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 – 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 the result as "passed", "failed(Goal)" where Goal is the test that failed, or "error(Error,Template)".

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. 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 – 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 – 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 – 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 – 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 – number of proofs:
variant(@term,@term) – zero_or_one

approximately_equal/3

Compares two numbers for approximate equality given an 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 – number of proofs:
approximately_equal(+number,+number,+number) – zero_or_one

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 – number of proofs:
essentially_equal(+number,+number,+number) – zero_or_one

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 – 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. Note that these precision values may not be adequate for all cases. Type-checked.

compilation flags:
static
template:
=~=(Number1,Number2)
mode – 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 – 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_test_set/0

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

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

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, check}.

compilation flags:
static
mode – 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
mode – number of proofs:
note(?atom) – zero_or_one

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 – 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 – number of proofs:
suppress_binary_output – 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 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 – 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 (referenced with the given alias) 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

text_input_assertion/3

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

compilation flags:
static
template:
text_input_assertion(Alias,Contents,Assertion)
mode – number of proofs:
text_input_assertion(+atom,+atom,--callable) – one

text_input_assertion/2

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

compilation flags:
static
template:
text_input_assertion(Contents,Assertion)
mode – number of proofs:
text_input_assertion(+atom,--callable) – 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 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 – 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

binary_input_assertion/3

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

compilation flags:
static
template:
binary_input_assertion(Alias,Bytes,Assertion)
mode – number of proofs:
binary_input_assertion(+atom,+list(byte),--callable) – one

binary_input_assertion/2

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

compilation flags:
static
template:
binary_input_assertion(Bytes,Assertion)
mode – number of proofs:
binary_input_assertion(+list(byte),--callable) – 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 (referenced with the given alias) 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

text_output_assertion/3

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

compilation flags:
static
template:
text_output_assertion(Alias,Contents,Assertion)
mode – number of proofs:
text_output_assertion(+atom,+atom,--callable) – one

text_output_assertion/2

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

compilation flags:
static
template:
text_output_assertion(Contents,Assertion)
mode – number of proofs:
text_output_assertion(+atom,--callable) – 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

binary_output_assertion/3

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

compilation flags:
static
template:
binary_output_assertion(Alias,Bytes,Assertion)
mode – number of proofs:
binary_output_assertion(+atom,+list(byte),--callable) – one

binary_output_assertion/2

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

compilation flags:
static
template:
binary_output_assertion(Bytes,Assertion)
mode – number of proofs:
binary_output_assertion(+list(byte),--callable) – 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

running_test_sets_/0

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

compilation flags:
dynamic
mode – number of proofs:
running_test_sets_ – zero_or_one

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

auxiliary_predicate_counter_/1

Counter for generarting unique auxiliary predicate names.

compilation flags:
dynamic
template:
auxiliary_predicate_counter_(Counter)
mode – number of proofs:
auxiliary_predicate_counter_(?integer) – one_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)