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).^{4This 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.^{5If 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