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>