unittest — Testing user code

This module provides functions to facilitate testing of user code. It provides an interface for writing unit tests and printing out the results. (The printouts are not “pretty”; they are designed to be interpreted by a wrapping script such as the Mars Test Framework.)

The test framework communicates with a wrapper by printing messages to standard output. Such messages are single lines beginning with “:test:”.

A “test case” is a single unit, which can be as big or small as the caller wishes. Zero or more asserts can be made within a single case. The case fails if any one of the asserts fails. The reason for this two-tiered system is so you can try a whole bunch of cascading asserts in a single case, and not have a mountain of failures if one fails.

Test cases must be explicitly begun and ended, in order to make sure rogue assert statements in between test cases are reported by the wrapper (rather than simply being believed to be in the most recent test case).

An “assert” is a test of a single condition. Each assert has a message, which describes what might go wrong. The message of the first failing assert will be printed if a test case fails.

Note once again that the output of this module is not meant to be viewed by a human, but processed by a wrapper and displayed in a nicer format.

begin_case(name :: Array(Num)) :: io Num

Begin a new test case. The name of the test case is for output purposes only, and does not have to be unique. It will be printed if the case fails.

Note

name should not contain newlines (this restriction may be relaxed).

begin_case_pending(name :: Array(Num)) :: io Num

Same as begin_case, but flag the case as expected to fail (as a temporary measure, so that you may check in code which is broken but which you intend to fix).

Will report an explicit “pass” if none of the asserts fail. Will not report anything if at least one assert fails.

end_case(name :: Array(Num)) :: io Num

End the current test case. Must use same name as most recent begin.

assert(value :: Num, message :: Array(Num)) :: io Num

Checks that value is nonzero. If value is nonzero, returns 1. Otherwise, prints an assert error with message and returns 0.

Describe in message what went wrong if the case fails. For example, assert_(4 == 9, "4 != 9").

Note

message should not contain newlines (this restriction may be relaxed).

assert_eq(x :: a, y :: a, _message :: Array(Num)) :: io Num

Checks that x equals y, according to eq. If x equals y, returns 1. Otherwise, prints an assert error with the values of x and y and returns 0. (_message is ignored, and is included for historical reasons.)

assert_near(x :: Num, y :: Num, message :: Array(Num)) :: io Num

Checks that x and y are within ϵ of one another, where ϵ is a small value (currently, 2^-16). Use this to test the result of floating point arithmetic. If x is within ϵ of y, returns 1. Otherwise, prints an assert error with message and returns 0.