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>

libzt 0.3.1                                     January 12, 2020                                     ZT_CHECK(3)