SWI-Prolog 9.1.2
AllApplicationManualNameSummaryHelp

All predicatesShow sourceplunit.pl -- Unit Testing

Unit testing environment for SWI-Prolog and SICStus Prolog. For usage, please visit https://www.swi-prolog.org/pldoc/package/plunit.

Source current_test_flag(?Name, ?Value) is nondet[private]
Query flags that control the testing process. Emulates SWI-Prologs flags.
Source set_test_flag(+Name, +Value) is det[private]
Source set_test_options(+Options)
Specifies how to deal with test suites. Defined options are:
load(+Load)
Whether or not the tests must be loaded. Values are never, always, normal (only if not optimised)
run(+When)
When the tests are run. Values are manual, make or make(all).
silent(+Bool)
If true (default false), report successful tests using message level silent, only printing errors and warnings.
output(+When)
If always, emit all output as it is produced, if never, suppress all output and if on_failure, emit the output if the test fails.
sto(+Bool)
How to test whether code is subject to occurs check (STO). If false (default), STO is not considered. If true and supported by the hosting Prolog, code is run in all supported unification mode and reported if the results are inconsistent.
cleanup(+Bool)
If true (default =false), cleanup report at the end of run_tests/1. Used to improve cooperation with memory debuggers such as dmalloc.
concurrent(+Bool)
If true (default false), run all tests in a unit concurrently.
Source loading_tests[private]
True if tests must be loaded.
Source begin_tests(+UnitName:atom) is det
Source begin_tests(+UnitName:atom, Options) is det
Start a test-unit. UnitName is the name of the test set. the unit is ended by :- end_tests(UnitName).
Source end_tests(+Name) is det
Close a unit-test module.
To be done
- Run tests/clean module?
- End of file?
Source make_unit_module(+Name, -ModuleName) is det[private]
Source unit_module(+Name, -ModuleName) is det[private]
Source expand_test(+Name, +Options, +Body, -Clause) is det[private]
Expand test(Name, Options) :- Body into a clause for 'unit test'/4 and 'unit body'/2.
Source expand(+Term, -Clauses) is semidet[private]
Source valid_options(+Options, :Pred) is det[private]
Verify Options to be a list of valid options according to Pred.
throws
- type_error or instantiation_error.
Source test_option(+Option) is semidet[private]
True if Option is a valid option for test(Name, Options).
Source test_option(+Option) is semidet[private]
True if Option is a valid option for :- begin_tests(Name, Options).
Source reify(:Goal, -Result) is det[private]
Source run_tests is semidet
Source run_tests(+TestSet) is semidet
Run tests and report about the results. The predicate run_tests/0 runs all known tests that are not blocked. The predicate run_tests/1 takes a specification of tests to run. This is either a single specification or a list of specifications. Each single specification is either the name of a test-unit or a term <test-unit>:<test>, denoting a single test within a unit.
Source count_tests(+Spec, -Count) is det[private]
Count the number of tests to run.
Source run_tests_in_files(+Files:list) is det[private]
Run all test-units that appear in the given Files.
Source make_run_tests(+Files)[private]
Called indirectly from make/0 after Files have been reloaded.
Source run_test(+Unit, +Name, +Line, +Options, +Body) is det[private]
Run a single test.
Source test_caps(-Type, +Unit, +Name, +Line, +Options, +Body, -Result, -Key) is nondet[private]
Source run_test_6(+Unit, +Name, +Line, +Options, :Body, -Result) is det[private]
6th step of the tests. Deals with tests that must be ignored (blocked, conditions fails), setup and cleanup at the test level. Result is one of:
blocked(Unit, Name, Line, Reason)
condition_failed(Unit, Name, Line)
failure(Unit, Name, Line, How, Time)
How is one of:
  • succeeded
  • Exception
  • cmp_error(Cmp, E)
  • wrong_answer(Cmp)
  • failed
  • no_exception
  • wrong_error(Expect, E)
  • wrong_answer(Expected, Bindings)
success(Unit, Name, Line, Determinism, Time)
setup_failed(Unit, Name, Line)
Source run_test_7(+Unit, +Name, +Line, +Options, :Body, -Result) is det[private]
This step deals with the expected outcome of the test. It runs the actual test and then compares the result to the outcome. There are two main categories: dealing with a single result and all results.
 non_det_test(+Expected, +Unit, +Name, +Line, +Options, +Body, -Result)[private]
Run tests on non-deterministic predicates.
Source result_vars(+Expected, -Vars) is det[private]
Create a term v(V1, ...) containing all variables at the left side of the comparison operator on Expected.
Source nondet_compare(+Expected, +Bindings, +Unit, +Name, +Line) is semidet[private]
Compare list/set results for non-deterministic predicates.
bug
- Sort should deal with equivalence on the comparison operator.
To be done
- Properly report errors
Source cmp(+CmpTerm, -Left, -Op, -Right) is det[private]
Source call_det(:Goal, -Det) is nondet[private]
True if Goal succeeded. Det is unified to true if Goal left no choicepoints and false otherwise.
Source match_error(+Expected, +Received) is semidet[private]
True if the Received errors matches the expected error. Matching is based on subsumes_term/2.
Source setup(+Module, +Context, +Options) is semidet[private]
Call the setup handler and fail if it cannot run for some reason. The condition handler is similar, but failing is not considered an error. Context is one of
unit(Unit)
If it is the setup handler for a unit
test(Unit, Name, Line)
If it is the setup handler for a test
Source condition(+Module, +Context, +Options) is semidet[private]
Evaluate the test or test unit condition.
Source call_ex(+Module, +Goal)[private]
Call Goal in Module after applying goal expansion.
Source cleanup(+Module, +Options) is det[private]
Call the cleanup handler and succeed. Failure or error of the cleanup handler is reported, but tests continue normally.
Source failure(+Unit, +Name, +Line, +How, +Time, +Options) is det[private]
Test failed. Report the error.
Source assert_cyclic(+Term) is det[private]
Assert a possibly cyclic unit clause. Current SWI-Prolog assert/1 does not handle cyclic terms, so we emulate this using the recorded database.
To be done
- Implement cycle-safe assert and remove this.
Source begin_test(Unit, Test, Line, STO) is det[private]
Source end_test(Unit, Test, Line, STO) is det[private]
Maintain running/5 and report a test has started/is ended using a silent message:
  • plunit(begin(Unit:Test, File:Line, STO))
  • plunit(end(Unit:Test, File:Line, STO))
See also
- message_hook/3 for intercepting these messages
Source running_tests is det
Print the currently running test.
Source current_test(?Unit, ?Test, ?Line, ?Body, ?Options) is nondet
True when a test with the specified properties is loaded.
Source current_test_unit(?Unit, ?Options) is nondet
True when a Unit is a current unit test declared with Options.
Source test_summary(?Unit, -Summary) is det[private]
True if there are no failures, otherwise false.
Source report is det[private]
Print a summary of the tests that ran.
Source test_report(+What) is det
Produce reports on test results after the run. Currently only supports fixme for What.
Source current_test_set(?Unit) is nondet[private]
True if Unit is a currently loaded test-set.
Source unit_file(+Unit, -File) is det[private]
unit_file(-Unit, +File) is nondet[private]
Source load_test_files(+Options) is det
Load .plt test-files related to loaded source-files.
Source info(+Term)[private]
Runs print_message(Level, Term), where Level is one of silent or informational (default).
Source user:message_hook(+Severity, +Message, +Lines) is semidet[multifile]
Redefine printing some messages. It appears SICStus has no way to get multiple messages at the same line, so we roll our own. As there is a lot pre-wired and checked in the SICStus message handling we cannot reuse the lines. Unless I miss something ...

Undocumented predicates

The following predicates are exported, but not or incorrectly documented.

Source run_tests(Arg1)
Source begin_tests(Arg1, Arg2)
ClioPatria (version no GIT?)