object
lgtunit
¶
A unit test framework supporting predicate clause coverage, determinism testing, input/output testing, property-based testing, and multiple test dialects.
static, context_switching_calls
Usage: Define test objects as extensions of the
lgtunit
object and compile their source files using the compiler optionhook(lgtunit)
.Portability: Deterministic unit tests are currently not available when using Lean Prolog or Quintus Prolog as backend compilers.
Known issues: Parameter variables cannot currently be used in the definition of test options.
Public predicates¶
cover/1
¶
Declares entities being tested for which code coverage information should be collected.
static
cover(Entity)
cover(?entity_identifier)
- zero_or_more
run/0
¶
Runs the unit tests, writing the results to the current output stream.
static
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.
static
run(Tests)
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).
static
run(File,Mode)
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.
static
run_test_sets(TestObjects)
run_test_sets(+list(object_identifier))
- zero_or_one
deterministic/1
¶
True if the goal succeeds once without leaving choice-points.
static
deterministic(Goal)
deterministic(0)
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.
static
deterministic(Goal,Deterministic)
deterministic(0,*)
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.
static
assertion(Assertion)
assertion(::)
assertion(+callable)
- one
assertion_failure(Assertion)
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.
static
assertion(Description,Assertion)
assertion(*,0)
assertion(+nonvar,+callable)
- one
assertion_failure(Description)
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)
.
static
quick_check(Template,Result,Options)
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 n(NumberOfTests)
and s(MaximumNumberOfShrinks)
options. Defaults are n(100)
and s(64)
.
static
quick_check(Template,Options)
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.
static
quick_check(Template)
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.
static
benchmark(Goal,Time)
benchmark(0,*)
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.
static
benchmark_reified(Goal,Time,Result)
benchmark_reified(0,*,*)
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.
static
benchmark(Goal,Repetitions,Time)
benchmark(0,*,*)
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.
static
benchmark(Goal,Repetitions,Clock,Time)
benchmark(0,*,*,*)
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.
static
variant(Term1,Term2)
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.
static
approximately_equal(Number1,Number2,Epsilon)
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.
static
essentially_equal(Number1,Number2,Epsilon)
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.
static
tolerance_equal(Number1,Number2,RelativeTolerance,AbsoluteTolerance)
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.
static
=~=(Number1,Number2)
=~=(+number,+number)
- zero_or_one
=~=(+list(number),+list(number))
- zero_or_one
Protected predicates¶
number_of_tests/1
¶
Number of defined unit tests.
static
number_of_tests(?integer)
- one
run_tests/0
¶
Runs all defined unit tests.
static
run_tests
- one
run_tests/2
¶
Runs a list of defined tests.
static
run_tests(Tests,File)
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.
static
run_test_set
- one
run_quick_check_tests/2
¶
Runs a list of defined tests using the given options.
static
run_quick_check_tests(Template,Options)
run_quick_check_tests(@callable,+list)
- one_or_error
condition/0
¶
Verifies conditions for running the tests. Defaults to the goal true
.
static
condition
- zero_or_one
setup/0
¶
Setup environment before running the test set. Defaults to the goal true
.
static
setup
- zero_or_one
cleanup/0
¶
Cleanup environment after running the test set. Defaults to the goal true
.
static
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
.
static
make(?atom)
- zero_or_one
note/1
¶
Note to be printed after the test results. Defaults to the empty atom.
static
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.
static
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.
static
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.
static
set_text_input(Alias,Contents,Options)
set_text_input(+atom,+atom,+list(stream_option))
- one
set_text_input(+atom,+list(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.
static
set_text_input(Alias,Contents)
set_text_input(+atom,+atom)
- one
set_text_input(+atom,+list(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.
static
set_text_input(Contents)
set_text_input(+atom)
- one
set_text_input(+list(atom))
- one
check_text_input/2
¶
Checks that the temporary file (referenced with the given alias) being written have the expected text contents.
static
check_text_input(Alias,Contents)
check_text_input(+atom,+atom)
- zero_or_one
check_text_input/1
¶
Checks that the temporary file being written have the expected text contents.
static
check_text_input(Contents)
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.
static
text_input_assertion(Alias,Contents,Assertion)
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.
static
text_input_assertion(Contents,Assertion)
text_input_assertion(+atom,--callable)
- one
clean_text_input/0
¶
Cleans the temporary file used when testing text input.
static
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.
static
set_binary_input(Alias,Bytes,Options)
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.
static
set_binary_input(Alias,Bytes)
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.
static
set_binary_input(Bytes)
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.
static
check_binary_input(Alias,Bytes)
check_binary_input(+atom,+list(byte))
- zero_or_one
check_binary_input/1
¶
Checks that the temporary file have the expected binary contents.
static
check_binary_input(Bytes)
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.
static
binary_input_assertion(Alias,Bytes,Assertion)
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.
static
binary_input_assertion(Bytes,Assertion)
binary_input_assertion(+list(byte),--callable)
- one
clean_binary_input/0
¶
Cleans the temporary file used when testing binary input.
static
clean_binary_input
- one
set_text_output/2
¶
Creates a temporary file with the given text contents and referenced with the given alias.
static
set_text_output(Alias,Contents)
set_text_output(+atom,+atom)
- one
set_text_output(+atom,+list(atom))
- one
set_text_output/1
¶
Creates a temporary file with the given text contents and sets the current output stream to the file.
static
set_text_output(Contents)
set_text_output(+atom)
- one
set_text_output(+list(atom))
- one
check_text_output/2
¶
Checks that the temporary file (referenced with the given alias) being written have the expected text contents.
static
check_text_output(Alias,Contents)
check_text_output(+atom,+atom)
- zero_or_one
check_text_output/1
¶
Checks that the temporary file being written have the expected text contents.
static
check_text_output(Contents)
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.
static
text_output_assertion(Alias,Contents,Assertion)
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.
static
text_output_assertion(Contents,Assertion)
text_output_assertion(+atom,--callable)
- one
clean_text_output/0
¶
Cleans the temporary file used when testing text output.
static
clean_text_output
- one
set_binary_output/2
¶
Creates a temporary file with the given binary contents and referenced with the given alias.
static
set_binary_output(Alias,Bytes)
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.
static
set_binary_output(Bytes)
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.
static
check_binary_output(Alias,Bytes)
check_binary_output(+atom,+list(byte))
- zero_or_one
check_binary_output/1
¶
Checks that the temporary file have the expected binary contents.
static
check_binary_output(Bytes)
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.
static
binary_output_assertion(Alias,Bytes,Assertion)
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.
static
binary_output_assertion(Bytes,Assertion)
binary_output_assertion(+list(byte),--callable)
- one
clean_binary_output/0
¶
Cleans the temporary file used when testing binary output.
static
clean_binary_output
- one
create_text_file/2
¶
Creates a text file with the given contents.
static
create_text_file(File,Contents)
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.
static
create_binary_file(File,Bytes)
create_binary_file(+atom,+list(byte))
- one
check_text_file/2
¶
Checks that the contents of a text file match the expected contents.
static
check_text_file(File,Contents)
check_text_file(+atom,+atom)
- zero_or_one
check_binary_file/2
¶
Checks the contents of a binary file match the expected contents.
static
check_binary_file(File,Bytes)
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.
static
clean_file(File)
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.
static
closed_input_stream(Stream,Options)
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.
static
closed_output_stream(Stream,Options)
closed_output_stream(-stream,+list(stream_option))
- zero_or_one
stream_position/1
¶
Returns a syntactically valid stream position.
static
stream_position(Position)
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.
dynamic
running_test_sets_
- zero_or_one
test/3
¶
Specifies a unit test.
static
test(Identifier,Variables,Outcome)
test(?atom,?list(variable),?nonvar)
- zero_or_more
auxiliary_predicate_counter_/1
¶
Counter for generating unique auxiliary predicate names.
dynamic
auxiliary_predicate_counter_(Counter)
auxiliary_predicate_counter_(?integer)
- one_or_more
test_/2
¶
Table of defined tests.
dynamic
test_(Identifier,Test)
test_(?atom,?compound)
- zero_or_more
skipped_/1
¶
Counter for skipped tests.
dynamic
skipped_(Counter)
skipped_(?integer)
- zero_or_one
passed_/1
¶
Counter for passed tests.
dynamic
passed_(Counter)
passed_(?integer)
- zero_or_one
failed_/1
¶
Counter for failed tests.
dynamic
failed_(Counter)
failed_(?callable)
- zero_or_one
fired_/3
¶
Fired clauses when running the unit tests.
dynamic
fired_(Entity,Predicate,Clause)
fired_(?entity_identifier,?predicate_indicator,?integer)
- zero_or_more
covered_/4
¶
Auxiliary predicate for collecting statistics on clause coverage.
dynamic
covered_(Entity,Predicate,Covered,Total)
covered_(?entity_identifier,?callable,?integer,?integer)
- zero_or_more
Operators¶
op(700,xfx,=~=)
¶
public