Assertions provide an easy way to test that conditions that you expect are true. When an unexpected condition arises, the assert macros throw a special exception of the class AssertionFailedError. Your test harness can either let that exception die uncaught, or catch it and process the message it includes.
Example usage:
record
lval ,int
proc
lval = myfunc()
assert_equal(1, lval, "Return value for myfunc was %a, expected %a")
pass()
Note that we avoid embedding myfunc() within the assert_equal statement, because it could then be executed twice: once for the assertion, and again when formatting the message.
If you don't supply a message format, a default message will be applied in some cases.
See test_assertions.dbl for a full test suite for assertions themselves.
Assertion macros and what they mean:
| Macro | Explanation | Arguments to build_message |
|---|---|---|
| assert(condition,message,arg1,arg2,arg3) | Asserts condition is TRUE | arg1, arg2, arg3 (if passed) |
| assert_equal(expected,actual,message) | Asserts actual == expected | actual, expected |
| assert_not_equal(expected,actual,message) | Asserts actual != expected | actual, expected |
| assert_not_null(object,message) | Asserts object != ^null | none |
| assert_null(object,message) | Asserts object == ^null | none |
| assert_kind_of(klass,object,message) | Asserts object .is. klass | "klass" |
| assert_in_delta(expected,actual,delta,message) | Asserts (expected - delta) <= actual <= (expected + delta) | actual expected, delta |
| assert_throws(exceptype,routine) | Asserts that routine throws an exception of class exceptype | N/A |
| assert_fails(routine) | Asserts that routine throws an AssertionFailedError | N/A |
| assert_fails_with(routine, msg) | Asserts that routine throws an exception with the Message property containing msg | N/A |
| flunk(message) | Throws an AssertionFailedError with Message msg | N/A |
| pass(what) | Suppresses STOP message and prints a message indicating that the routine passed. | N/A |
In the macros that accept a message argument, that string will be used as the Message property for the exception if the assertion fails. If the message is not passed, a default mesage will be used in some cases. For the generic assert, just "Assertion failed" will be used.
If the macro passes arguments to build_message, then those arguments can be formatted into the message using s_bld syntax. All arguments are converted to string first, so only %a should be used for formatting.
The included function build_message is simply a syntactically handier version of s_bld, in that it returns the formatted string as its return value rather than as an argument.
You can conditionally disable assertions by:
.define D_NO_ASSERTIONS
prior to including synthesis.def.