object
lgtunit
A unit test framework supporting predicate clause coverage, determinism testing, input/output testing, property-based testing, and multiple test dialects.
logtalk_load(lgtunit(loader))static, context_switching_calls
Usage: Define test objects as extensions of the
lgtunitobject and compile their source files using the compiler optionhook(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.
Public predicates
cover/1
Declares entities being tested for which code coverage information should be collected.
staticcover(Entity)cover(?entity_identifier) - zero_or_morerun/0
Runs the unit tests, writing the results to the current output stream.
staticrun - onerun/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.
staticrun(Tests)run(++callable) - zero_or_onerun(++list(callable)) - zero_or_onerun/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).
staticrun(File,Mode)run(+atom,+atom) - onerun_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.
staticrun_test_sets(TestObjects)run_test_sets(+list(object_identifier)) - zero_or_onetest/1
Enumerates, by backtracking, the identifiers of all defined unit tests.
statictest(Identifier)test(?callable) - zero_or_morenumber_of_tests/1
Number of defined unit tests.
staticnumber_of_tests(NumerOfTests)number_of_tests(?integer) - zero_or_onedeterministic/1
True if the goal succeeds once without leaving choice-points.
staticdeterministic(Goal)deterministic(0)deterministic(+callable) - zero_or_onedeterministic/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.
staticdeterministic(Goal,Deterministic)deterministic(0,*)deterministic(+callable,--atom) - zero_or_oneassertion/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.
staticassertion(Assertion)assertion(::)assertion(@callable) - oneassertion_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.
staticassertion(Description,Assertion)assertion(*,0)assertion(+nonvar,@callable) - oneassertion_failure(Description)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.
staticquick_check(Template,Result,Options)quick_check(::,*,::)quick_check(@callable,-callable,++list(compound)) - one
SequenceSeedargument: Can be used to re-run the same exact sequence of pseudo-random tests by using thers/1option after changes to the code being tested.
TestSeedargument: Can be used to re-run the test that failed by using thers/1option after changes to the code being tested.
Discardedargument: Number of generated tests that were discarded for failing to comply a pre-condition specified using thepc/1option.
Labelsargument: List of pairsLabel-NwhereNis the number of generated tests that are classified asLabelby a closure specified using thel/1option.
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.
staticquick_check(Template,Options)quick_check(::,::)quick_check(@callable,++list(compound)) - zero_or_one
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 istrue.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/1option to specify a pre-condition closure for filtering generated tests (extended with the test arguments; no default).Generated tests classification: Use the
l/1option 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 isfalse.Progress bar: Use the
pb(Boolean,Tick)option to print a progress bar for the executed tests, advancing at everyTicktests. Default isfalse. 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.
staticquick_check(Template)quick_check(@callable) - zero_or_onebenchmark/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.
staticbenchmark(Goal,Time)benchmark(0,*)benchmark(+callable,-float) - onebenchmark_reified/3
Benchmarks a goal and returns the total execution time in seconds plus its result (success, failure, or error(Error)). Uses CPU clock.
staticbenchmark_reified(Goal,Time,Result)benchmark_reified(0,*,*)benchmark_reified(+callable,-float,-callable) - onebenchmark/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.
staticbenchmark(Goal,Repetitions,Time)benchmark(0,*,*)benchmark(@callable,+positive_integer,-float) - onebenchmark/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.
staticbenchmark(Goal,Repetitions,Clock,Time)benchmark(0,*,*,*)benchmark(@callable,+positive_integer,+atom,-float) - onevariant/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.
staticvariant(Term1,Term2)variant(@term,@term) - zero_or_oneapproximately_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.
staticapproximately_equal(Number1,Number2)approximately_equal(+number,+number) - zero_or_oneapproximately_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.
staticapproximately_equal(Number1,Number2,Epsilon)approximately_equal(+number,+number,+number) - zero_or_one
Epsilon range: Epsilon should be the
epsilonarithmetic 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.
staticessentially_equal(Number1,Number2,Epsilon)essentially_equal(+number,+number,+number) - zero_or_one
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.
statictolerance_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_oneepsilon/1
Returns the value of epsilon used in the definition of the (=~=)/2 predicate.
staticepsilon(Epsilon)epsilon(-float) - oneProtected predicates
run_tests/0
Runs all defined unit tests.
staticrun_tests - onerun_tests/1
Runs all the tests defined in the given file.
staticrun_tests(File)run_tests(+atom) - onerun_test_set/0
Runs a test set as part of running two or more test sets as a unified set.
staticrun_test_set - onerun_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.
staticrun_quick_check_tests(Template,Options,Seed,Discarded,Labels)run_quick_check_tests(::,::,*,*,*)run_quick_check_tests(@callable,+list,--nonvar,--number,--list(pair)) - one_or_errorcondition/0
Verifies conditions for running the tests. Defaults to the goal true.
staticcondition - zero_or_onesetup/0
Setup environment before running the test set. Defaults to the goal true.
staticsetup - zero_or_onecleanup/0
Cleanup environment after running the test set. Defaults to the goal true.
staticcleanup - zero_or_onemake/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.
staticmake(Target)make(?atom) - zero_or_onenote/1
Note to be printed after the test results. Defaults to the empty atom.
staticnote(Note)note(?atom) - zero_or_onefile_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.
staticfile_path(File,Path)file_path(+atom,-atom) - onesuppress_text_output/0
Suppresses text output. Useful to avoid irrelevant text output from predicates being tested to clutter the test logs.
staticsuppress_text_output - onesuppress_binary_output/0
Suppresses binary output. Useful to avoid irrelevant binary output from predicates being tested to clutter the test logs.
staticsuppress_binary_output - oneset_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.
staticset_text_input(Alias,Contents,Options)set_text_input(+atom,+atom,+list(stream_option)) - oneset_text_input(+atom,+list(atom),+list(stream_option)) - oneset_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.
staticset_text_input(Alias,Contents)set_text_input(+atom,+atom) - oneset_text_input(+atom,+list(atom)) - oneset_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.
staticset_text_input(Contents)set_text_input(+atom) - oneset_text_input(+list(atom)) - onecheck_text_input/2
Checks that the temporary file (referenced by the given alias) being read have the expected text contents.
staticcheck_text_input(Alias,Contents)check_text_input(+atom,+atom) - zero_or_onecheck_text_input/1
Checks that the temporary file being read have the expected text contents.
staticcheck_text_input(Contents)check_text_input(+atom) - zero_or_onetext_input_assertion/3
Returns an assertion for checking that the temporary file (referenced by the given alias) being read have the expected text contents.
statictext_input_assertion(Alias,Contents,Assertion)text_input_assertion(+atom,+atom,--callable) - onetext_input_assertion/2
Returns an assertion for checking that the temporary file being read have the expected text contents.
statictext_input_assertion(Contents,Assertion)text_input_assertion(+atom,--callable) - oneclean_text_input/0
Cleans the temporary file used when testing text input.
staticclean_text_input - oneset_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.
staticset_binary_input(Alias,Bytes,Options)set_binary_input(+atom,+list(byte),+list(stream_option)) - oneset_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.
staticset_binary_input(Alias,Bytes)set_binary_input(+atom,+list(byte)) - oneset_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.
staticset_binary_input(Bytes)set_binary_input(+list(byte)) - onecheck_binary_input/2
Checks that the temporary file (referenced by the given alias) being read have the expected binary contents.
staticcheck_binary_input(Alias,Bytes)check_binary_input(+atom,+list(byte)) - zero_or_onecheck_binary_input/1
Checks that the temporary file being read have the expected binary contents.
staticcheck_binary_input(Bytes)check_binary_input(+list(byte)) - zero_or_onebinary_input_assertion/3
Returns an assertion for checking that the temporary file (referenced by the given alias) being read have the expected binary contents.
staticbinary_input_assertion(Alias,Bytes,Assertion)binary_input_assertion(+atom,+list(byte),--callable) - onebinary_input_assertion/2
Returns an assertion for checking that the temporary file being read have the expected binary contents.
staticbinary_input_assertion(Bytes,Assertion)binary_input_assertion(+list(byte),--callable) - oneclean_binary_input/0
Cleans the temporary file used when testing binary input.
staticclean_binary_input - oneset_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.
staticset_text_output(Alias,Contents,Options)set_text_output(+atom,+atom,+list(stream_option)) - oneset_text_output(+atom,+list(atom),+list(stream_option)) - oneset_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.
staticset_text_output(Alias,Contents)set_text_output(+atom,+atom) - oneset_text_output(+atom,+list(atom)) - oneset_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.
staticset_text_output(Contents)set_text_output(+atom) - oneset_text_output(+list(atom)) - onecheck_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.
staticcheck_text_output(Alias,Contents,Options)check_text_output(+atom,+atom,+list(stream_option)) - zero_or_onecheck_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.
staticcheck_text_output(Alias,Contents)check_text_output(+atom,+atom) - zero_or_onecheck_text_output/1
Checks that the temporary file being written have the expected text contents.
staticcheck_text_output(Contents)check_text_output(+atom) - zero_or_onetext_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.
statictext_output_assertion(Alias,Contents,Options,Assertion)text_output_assertion(+atom,+atom,+list(stream_option),--callable) - onetext_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.
statictext_output_assertion(Alias,Contents,Assertion)text_output_assertion(+atom,+atom,--callable) - onetext_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.
statictext_output_assertion(Contents,Assertion)text_output_assertion(+atom,--callable) - onetext_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.
statictext_output_contents(Alias,Contents,Options)text_output_contents(+atom,-list(character),+list(stream_option)) - onetext_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.
statictext_output_contents(Alias,Contents)text_output_contents(+atom,-list(character)) - onetext_output_contents/1
Returns the contents of the temporary file (open with default options in the same directory as the tests object) being written.
statictext_output_contents(Contents)text_output_contents(-list(character)) - oneclean_text_output/0
Cleans the temporary file used when testing text output.
staticclean_text_output - oneset_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.
staticset_binary_output(Alias,Contents,Options)set_binary_output(+atom,+list(byte),+list(stream_option)) - oneset_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.
staticset_binary_output(Alias,Bytes)set_binary_output(+atom,+list(byte)) - oneset_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.
staticset_binary_output(Bytes)set_binary_output(+list(byte)) - onecheck_binary_output/2
Checks that the temporary file (referenced by the given alias) have the expected binary contents.
staticcheck_binary_output(Alias,Bytes)check_binary_output(+atom,+list(byte)) - zero_or_onecheck_binary_output/1
Checks that the temporary file (open in the same directory as the tests object) have the expected binary contents.
staticcheck_binary_output(Bytes)check_binary_output(+list(byte)) - zero_or_onebinary_output_assertion/3
Returns an assertion for checking that the temporary file (referenced by the given alias) have the expected binary contents.
staticbinary_output_assertion(Alias,Bytes,Assertion)binary_output_assertion(+atom,+list(byte),--callable) - onebinary_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.
staticbinary_output_assertion(Bytes,Assertion)binary_output_assertion(+list(byte),--callable) - onebinary_output_contents/2
Returns the binary contents of the temporary file (referenced by the given alias) being written.
staticbinary_output_contents(Alias,Bytes)binary_output_contents(+atom,-list(byte)) - onebinary_output_contents/1
Returns the binary contents of the temporary file being written.
staticbinary_output_contents(Bytes)binary_output_contents(-list(byte)) - oneclean_binary_output/0
Cleans the temporary file used when testing binary output.
staticclean_binary_output - onecreate_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.
staticcreate_text_file(File,Contents,Options)create_text_file(+atom,+atom,+list(stream_option)) - onecreate_text_file(+atom,+list(atom),+list(stream_option)) - onecreate_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.
staticcreate_text_file(File,Contents)create_text_file(+atom,+atom) - onecreate_text_file(+atom,+list(atom)) - onecreate_binary_file/2
Creates a binary file with the given contents. Relative file paths are interpreted as relative to the tests object path.
staticcreate_binary_file(File,Bytes)create_binary_file(+atom,+list(byte)) - onecheck_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.
staticcheck_text_file(File,Contents,Options)check_text_file(+atom,+atom,+list(stream_option)) - zero_or_onecheck_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.
staticcheck_text_file(File,Contents)check_text_file(+atom,+atom) - zero_or_onetext_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.
statictext_file_assertion(File,Contents,Options,Assertion)text_file_assertion(+atom,+atom,+list(stream_option),--callable) - onetext_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.
statictext_file_assertion(File,Contents,Assertion)text_file_assertion(+atom,+atom,--callable) - onecheck_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.
staticcheck_binary_file(File,Bytes)check_binary_file(+atom,+list(byte)) - zero_or_onebinary_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.
staticbinary_file_assertion(File,Bytes,Assertion)binary_file_assertion(+atom,+list(byte),--callable) - oneclean_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.
staticclean_file(File)clean_file(+atom) - oneclean_directory/1
Deletes an empty directory if it exists. Relative directory paths are interpreted as relative to the tests object path.
staticclean_directory(Directory)clean_directory(+atom) - oneclosed_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.
staticclosed_input_stream(Stream,Options)closed_input_stream(-stream,+list(stream_option)) - oneclosed_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.
staticclosed_output_stream(Stream,Options)closed_output_stream(-stream,+list(stream_option)) - zero_or_onestream_position/1
Returns a syntactically valid stream position by opening a temporary file in the same directory as the tests object.
staticstream_position(Position)stream_position(-stream_position) - onetest/2
Table of defined tests.
statictest(Identifier,Test)test(?callable,?compound) - zero_or_morePrivate predicates
running_test_sets_/0
Internal flag used when running two or more test sets as a unified set.
dynamicrunning_test_sets_ - zero_or_onetest/3
Compiled unit tests. The list of variables is used to ensure variable sharing between a test with its test options.
statictest(Identifier,Variables,Outcome)test(*,*,*)test(?callable,?list(variable),?nonvar) - zero_or_moreauxiliary_predicate_counter_/1
Counter for generating unique auxiliary predicate names.
dynamicauxiliary_predicate_counter_(Counter)auxiliary_predicate_counter_(?integer) - one_or_moretest_/2
Table of compiled tests.
dynamictest_(Identifier,Test)test_(?callable,?compound) - zero_or_moreskipped_/1
Counter for skipped tests.
dynamicskipped_(Counter)skipped_(?integer) - zero_or_onepassed_/2
Counter and total time for passed tests.
dynamicpassed_(Counter,Time)passed_(?integer,-float) - zero_or_onefailed_/2
Counter and total time for failed tests.
dynamicfailed_(Counter,Time)failed_(?integer,-float) - zero_or_oneflaky_/1
Counter for failed tests that are marked as flaky.
dynamicflaky_(Counter)flaky_(?integer) - zero_or_onefired_/3
Fired clauses when running the unit tests.
dynamicfired_(Entity,Predicate,Clause)fired_(?entity_identifier,?predicate_indicator,?integer) - zero_or_morecovered_/4
Auxiliary predicate for collecting statistics on clause coverage.
dynamiccovered_(Entity,Predicate,Covered,Total)covered_(?entity_identifier,?callable,?integer,?integer) - zero_or_moreOperators
op(700,xfx,=~=)
public