The Ciao assertion language (see The Ciao assertion language) allows writing tests (including unit tests) by means of test assertions. These assertions make it possible to write specific test cases at the predicate level. This library contains predicates that can be used to run tests in modules and gather or pretty print the results. It also provides some special properties that are convenient when writing tests and the required run-time support.
Recall that a test assertion is written as follows:
:- test predicate(A1, A2, ..., An) : <Precondition> => <Postcondition> + <Global properties> # <Comment>.
Where the fields of the test assertion have the usual meaning in Ciao assertions, i.e., they contain conjunctions of properties which must hold at certain points in the execution. Here we give a somewhat more operational (“test oriented”), reading to these fields:
The following are some example tests for a complex number evaluator (see Examples (unittest) for the full code):
:- module(ceval2, [ceval/2], [assertions, regtypes, nativeprops]). :- test ceval(A, B) : (A = c(3, 4) + c(1, 2) - c(2, 3)) => (B = c(2, 3)) + (not_fails, is_det). :- test ceval(A, B) : (A = c(3, 4) * c(1, 2) / c(1, 2)) => (B = c(3.0, 4.0)) + (not_fails, is_det). ceval(A, A) :- complex(A), !. ceval(A+B, C) :- ceval(A, CA), ceval(B, CB), add(CA, CB, C). ceval(A-B, C) :- ceval(A, CA), ceval(B, CB), sub(CA, CB, C). ceval(A*B, C) :- ceval(A, CA), ceval(B, CB), mul(CA, CB, C). ceval(A/B, C) :- ceval(A, CA), ceval(B, CB), div(CA, CB, C). ... :- regtype complex/1. :- export(complex/1). complex(c(A, B)) :- num(A), num(B).
Test assertions can be combined with other assertions:
:- test ceval(A, B) : (A = c(3, 4) + c(1, 2) - c(2, 3)) => (B = c(2, 3)) + (not_fails, is_det). :- test ceval(A, B) : (A = c(3, 4) * c(1, 2) / c(1, 2)) => (B = c(3.0, 4.0)) + (not_fails, is_det). :- check pred ceval/2 : gnd * term => gnd * complex.
Test assertions can also take the standard assertion status prefixes. In particular, a status of false can be used to state that a test fails. This can be useful to flag bugs as known.
:- false test ceval(A, B) : (A = c(3, 4) + c(1, 2) - c(2, 3)) => (B = c(2, 3)) + (not_fails, is_det).
Tests with a false (or true) prefix are not run.
Due to the non-determinism of logic programs, the test engine needs to test all the solutions that can be tested up to given limits (for example, a maximum number of solutions, or a given timeout).
There are some specific properties that only apply to testing which are provided in module unittest_props.pl. For example try_sols(N) specifies that the first N solutions of the predicate predicate/n are tested. times(N) specifies that the given test should be executed N times, etc.
The tests can also be run from the top level, loading this module (unittest.pl) and calling the appropiate predicates that it exports (see the module Usage and Interface section below). This can also be done from a program, provided it imports this module.
If you need to write tests for predicates that are spread over several modules, but work together, it may be useful to create a separate module, and reexport the predicates required to build the tests. This allows performing integration testing, using the same syntax of the test assertions.
Run the tests in module Alias (using default options). The results of the tests are printed out.
Run the tests in module Alias (with options Opts). The results of the tests are returned as data in TestSummaries. TestSummaries can be pretty printed using show_test_summaries/1 and statistical_summary/2.
Executes all the tests in the modules of the given directory and its subdirectories. You can indicate that the modules in a sub-directory should not be tested by placing an empty NOTEST file in that sub-directory. Also, is a NOTESTFILES is present containing patterns for modules those modules will not be tested.
Show any exported predicates that do not have test assertions. This is an aid towards ensuring that all exported predicates have tests.
Pretty print the test results contained in TestSummaries.
Given a file Alias, tries to lookup the respective unittest output file and print it to the standard output in the specified Format ('output' for test full trace, 'stats' for a statistical summary only, 'full' for both), otherwise emits a warning message that no test output file is avaiable.
Opt is a testing option.
Action is a testing action