2.2 Writing the test body
The test-body is ordinary Prolog code. Without any options, the body
must be designed to succeed deterministically. Any other result
is considered a failure. One of the options fail
, true
,
throws
, all
or set
can be used to
specify a different expected result. See section
2 for details. In this section we illustrate typical test-scenarios
by testing SWI-Prolog built-in and library predicates.
2.2.1 Testing deterministic predicates
Deterministic predicates are predicates that must succeed exactly once and, for well behaved predicates, leave no choicepoints. Typically they have zero or more input- and zero or more output arguments. The test goal supplies proper values for the input arguments and verifies the output arguments. Verification can use test-options or be explicit in the body. The tests in the example below are equivalent.
test(add) :- A is 1 + 2, A =:= 3. test(add, [true(A =:= 3)]) :- A is 1 + 2.
The test engine verifies that the test-body does not leave a choicepoint. We illustrate that using the test below:
test(member) :- member(b, [a,b,c]).
Although this test succeeds, member/2 leaves a choicepoint which is reported by the test subsystem. To make the test silent, use one of the alternatives below.
test(member) :- member(b, [a,b,c]), !. test(member, [nondet]) :- member(b, [a,b,c]).
2.2.2 Testing semi-deterministic predicates
Semi-deterministic predicates are predicates that either fail or
succeed exactly once and, for well behaved predicates, leave no
choicepoints. Testing such predicates is the same as testing
deterministic predicates. Negative tests must be specified using the
option
fail
or by negating the body using \+/1
.
test(is_set) :- \+ is_set([a,a]). test(is_set, [fail]) :- is_set([a,a]).
2.2.3 Testing non-deterministic predicates
Non-deterministic predicates succeed zero or more times. Their
results are tested either using findall/3
or setof/3
followed by a value-check or using the all
or set
options. The following are equivalent tests:
test(member) :- findall(X, member(X, [a,b,c]), Xs), Xs == [a,b,c]. test(member, all(X == [a,b,c])) :- member(X, [a,b,c]).
2.2.4 Testing error conditions
Error-conditions are tested using the option throws(Error)
or by wrapping the test in a catch/3.
The following tests are equivalent:
test(div0) :- catch(A is 1/0, error(E, _), true), E =@= evaluation_error(zero_divisor). test(div0, [error(evaluation_error(zero_divisor))]) :- A is 1/0.
2.2.5 One body with multiple tests using assertions
PlUnit is designed to cooperate with the assertion/1 test provided by library(debug).3This integration was suggested by Günter Kniesel. If an assertion fails in the context of a test, the test framework reports this and considers the test failed, but does not trap the debugger. Using assertion/1 in the test-body is attractive for two scenarios:
- Confirm that multiple claims hold. Where multiple claims about variable bindings can be tested using the == option in the test header, arbitrary boolean tests, notably about the state of the database, are harder to combine. Simply adding them in the body of the test has two disadvantages: it is less obvious to distinguish the tested code from the test and if one of the tests fails there is no easy way to find out which one.
- Testing‘scenarios’or sequences of actions. If one step in such a sequence fails there is again no easy way to find out which one. By inserting assertions into the sequence this becomes obvious.
Below is a simple example, showing two failing assertions. The first line of the failure message gives the test. The second reports the location of the assertion.4If known. The location is determined by analysing the stack. The second failure shows a case where this does not work because last-call optimization has already removed the context of the test-body. If the assertion call originates from a different file this is reported appropriately. The last line gives the actually failed goal.
:- begin_tests(test). test(a) :- A is 2^3, assertion(float(A)), assertion(A == 9). :- end_tests(test).
?- run_tests. % PL-Unit: test ERROR: /home/jan/src/pl-devel/linux/t.pl:5: test a: assertion at line 7 failed Assertion: float(8) ERROR: /home/jan/src/pl-devel/linux/t.pl:5: test a: assertion failed Assertion: 8==9 . done % 2 assertions failed