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>