plunit.pl -- Unit Testing

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

 current_test_flag(?Name, ?Value) is nondet[private]

Query flags that control the testing process. Emulates SWI-Prologs flags.

 set_test_flag(+Name, +Value) is det[private]

 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.

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 block concurrently.

 loading_tests[private]

True if tests must be loaded.

 begin_tests(+UnitName:atom) is det

 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).

 end_tests(+Name) is det

Close a unit-test module.

To be done

- Run tests/clean module?

- End of file?

 make_unit_module(+Name, -ModuleName) is det[private]

 unit_module(+Name, -ModuleName) is det[private]

 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.

 expand(+Term, -Clauses) is semidet[private]

 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.

 test_option(+Option) is semidet[private]

True if Option is a valid option for test(Name, Options).

 test_option(+Option) is semidet[private]

True if Option is a valid option for :- begin_tests(Name, Options).

 run_tests is semidet

 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.

 run_tests_in_files(+Files:list) is det[private]

Run all test-units that appear in the given Files.

 make_run_tests(+Files)[private]

Called indirectly from make/0 after Files have been reloaded.

 run_test(+Unit, +Name, +Line, +Options, +Body) is det[private]

Run a single test.

 test_caps(-Type, +Unit, +Name, +Line, +Options, +Body, -Result, -Key) is nondet[private]

 run_test_6(+Unit, +Name, +Line, +Options, :Body, -Result) is det[private]

Result is one of:

• blocked(Unit, Name, Line, Reason)
• failure(Unit, Name, Line, How)
• success(Unit, Name, Line, Determinism, Time)
• setup_failed(Unit, Name, Line)

 non_det_test(+Expected, +Unit, +Name, +Line, +Options, +Body, -Result)[private]

Run tests on non-deterministic predicates.

 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.

 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

 cmp(+CmpTerm, -Left, -Op, -Right) is det[private]

 call_det(:Goal, -Det) is nondet[private]

True if Goal succeeded. Det is unified to true if Goal left no choicepoints and false otherwise.

 match_error(+Expected, +Received) is semidet[private]

True if the Received errors matches the expected error. Matching is based on subsumes_term/2.

 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

 call_ex(+Module, +Goal)[private]

Call Goal in Module after applying goal expansion.

 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.

 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.

 begin_test(Unit, Test, Line, STO) is det[private]

 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

 running_tests is det

Print the currently running test.

 current_test(?Unit, ?Test, ?Line, ?Body, ?Options)

True when a test with the specified properties is loaded.

 test_summary(?Unit, -Summary) is det[private]

True if there are no failures, otherwise false.

 report is det[private]

Print a summary of the tests that ran.

 test_report(What) is det

Produce reports on test results after the run.

 current_test_set(?Unit) is nondet[private]

True if Unit is a currently loaded test-set.

 unit_file(+Unit, -File) is det[private]

unit_file(-Unit, +File) is nondet[private]

 load_test_files(+Options) is det

Load .plt test-files related to loaded source-files.

 info(+Term)[private]

Runs print_message(Level, Term), where Level is one of silent or informational (default).

 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.

 begin_tests(Arg1, Arg2)

 run_tests(Arg1)