NAME

     zt_check, zt_assert — verify a test claim

SYNOPSIS

     #include <zt.h>

     void
     zt_check(zt_t t, zt_claim claim);

     void
     zt_assert(zt_t t, zt_claim claim);

DESCRIPTION

     Both zt_check() and zt_assert() verify a claim, encompassing a function with arguments, and
     is meant to be used inside test functions.

     The first argument is a pointer to opaque type encapsulating test outcome.  The second
     argument is usually constructed with a helper macro, such as ZT_CMP_TRUE() or
     ZT_CMP_FALSE().

     If the claim holds then happens and execution continues normally.  If the claim does not
     hold then the test is marked as failed and a diagnostic message is printed to stderr.

     The only difference between zt_check() and zt_assert() is that the former allows the test to
     continue executing while the latter performs a non-local exit from the test function. Note
     that only the currently executing test function is affected. Other tests cases and test
     suites will still execute normally.

     zt_check() should be used when it is safe to execute remainder of the test even if the claim
     is not true. This approach allows each failure to be accompanied by as much diagnostic
     output as possible, without causing the test program to crash.

     zt_assert() should be used when it is not safe or meaningless to execute remainder of the
     test on failure.

IMPLEMENTATION NOTES

     Non-local exit from zt_assert() is implemented using siglongjump().  One should not depend
     on neither C++ destructors nor the GCC cleanup function extension for correct resource
     management.

RETURN VALUES

     Neither function return anything. Failures are remembered inside the opaque zt_test
     structure passed by pointer (aka zt_t) as the first argument.

EXAMPLES

     A minimal test program that looks up the UNIX user root and measures several properties of
     the returned record.

           #include <sys/types.h>
           #include <pwd.h>

           #include <zt.h>

           static void test_root_user(zt_t t) {
               struct passwd *p = getpwnam("root");
               zt_assert(t, ZT_NOT_NULL(p));
               zt_check(t, ZT_CMP_CSTR(p->pw_name, ==, "root"));
               zt_check(t, ZT_CMP_INT(p->pw_uid, ==, 0));
               zt_check(t, ZT_CMP_INT(p->pw_gid, ==, 0));
           }

           static void test_suite(zt_visitor v) {
               ZT_VISIT_TEST_CASE(v, test_root_user);
           }

           int main(int argc, char** argv, char** envp) {
               return zt_main(argc, argv, envp, test_suite);
           }

SEE ALSO

     ZT_CMP_BOOL(3), ZT_CMP_CSTR(3), ZT_CMP_INT(3), ZT_CMP_PTR(3), ZT_CMP_UINT(3), ZT_FALSE(3),
     ZT_NOT_NULL(3), ZT_NULL(3), ZT_TRUE(3)

HISTORY

     The zt_check() and the zt_assert() functions first appeared in libzt 0.1

AUTHORS

     Zygmunt Krynicki <me@zygoon.pl>