KTEST_RESULT_PASS(9F)

NAME
KT_PASS, KT_FAIL, KT_ERROR, KT_SKIP, KT_ASSERT, KT_ASSERT0, KT_ASSERT3S, KT_ASSERT3U, KT_ASSERT3P, KT_ASSERTG, KT_ASSERT0G, KT_ASSERT3SG, KT_ASSERT3UG, KT_ASSERT3PG, ktest_result_pass, ktest_result_fail, ktest_result_error, ktest_result_skip, ktest_msg_prepend, ktest_msg_clear - set test result, assert test conditions, add failure context

SYNOPSIS
#include <sys/ktest.h>
void
ktest_result_pass(ktest_ctx_hdl_t *ctx, int line);
void
ktest_result_fail(ktest_ctx_hdl_t *ctx, int line, const char *msg, ...);
void
ktest_result_error(ktest_ctx_hdl_t *ctx, int line, const char *msg, ...);
void
ktest_result_skip(ktest_ctx_hdl_t *ctx, int line, const char *msg, ...);
void
ktest_msg_prepend(ktest_ctx_hdl_t *ctx, const char *msg, ...);
void
ktest_msg_clear(ktest_ctx_hdl_t *ctx);
void
KT_PASS(ktest_ctx_hdl_t *ctx);
void
KT_FAIL(ktest_ctx_hdl_t *ctx, const char *msg, ...);
void
KT_ERROR(ktest_ctx_hdl_t *ctx, const char *msg, ...);
void
KT_SKIP(ktest_ctx_hdl_t *ctx, const char *msg, ...);
void
KT_ASSERT(exp, ktest_ctx_hdl_t *ctx);
void
KT_ASSERT0(exp, ktest_ctx_hdl_t *ctx);
void
KT_ASSERT3S(int64_t left, op, int64_t right, ktest_ctx_hdl_t *ctx);
void
KT_ASSERT3U(uint64_t left, op, uint64_t right, ktest_ctx_hdl_t *ctx);
void
KT_ASSERT3P(uintptr_t left, op, uintptr_t right, ktest_ctx_hdl_t *ctx);
void
KT_ASSERTG(exp, ktest_ctx_hdl_t *ctx, label);
void
KT_ASSERT0G(exp, ktest_ctx_hdl_t *ctx, label);
void
KT_ASSERT3SG(int64_t left, op, int64_t right, ktest_ctx_hdl_t *ctx, label);
void
KT_ASSERT3UG(uint64_t left, op, uint64_t right, ktest_ctx_hdl_t *ctx, label);
void
KT_ASSERT3PG(uintptr_t left, op, uintptr_t right, ktest_ctx_hdl_t *ctx, label);

INTERFACE LEVEL
Volatile - This interface is still evolving in illumos. API and ABI stability is not guaranteed.

PARAMETERS

ctx A handle to the test context. This handle is passed as argument to the test function by the ktest facility.

exp A test condition expression.

left
    The left side value of the test condition. This may be an expression.

right
    The right side value of the test condition. This may be an expression.

op  The operator used to compare the left and right side values.

label
    The source code label to jump to if the test condition is false.

line
    The source line number where the result is set. This should always be the __LINE__ macro.

msg A message giving additional context on why a test did not pass.

DESCRIPTION
These functions and macros are used to set the result of a test function.

  Result Macros
These are convenience macros for setting the test result, providing an alternative to the verbose result functions. In general, you should only need to use the KT_PASS() and KT_SKIP() macros. For most test assertions it's more convenient to use the "KTest ASSERT Macros" described below. These macros do not cause a return.

KT_PASS()
    Set a passing result.

KT_FAIL()
    Set a failure result along with the failure message.

KT_ERROR()
    Set an error result along with the error message.

KT_SKIP()
    Set a skip result along with the skip message.

  KTest ASSERT Macros
These macros evaluate their test condition expression and verify it's true. They take care of building a failure message based on the expression and calling the ktest_result_fail() function with the appropriate line number. They provide a convenient way to express test conditions and automatically build failure messages on the caller's behalf. They are essentially the same as the traditional ASSERT3 family of macros with three exceptions:

1.  They all require the additional ctx argument in order to set the failure result when the assert trips.

2.  They do not panic but instead build a failure message, call ktest_result_fail(), and cause an immediate return of the test function.

3.  The "goto" variations of these macros provide the ability to cleanup test state instead of returning immediately.

There are two variations of these macros.

KT_ASSERT*
    Essentially the same as the traditional ASSERT3 family of macros, with the exception that they all take the ctx as an additional argument. This assert returns from the test function.

KT_ASSERT*G
    Assert the condition or goto label.

  KTest Error ASSERT Macros
These macros are the same as the KT_ASSERT*() macros with the only exception being that they call the ktest_result_error() function to indicate an error condition. These macros use the same names as the KT_ASSERT*() macros but prefixed with the character 'E', like so: KT_EASSERT*(). This is a convenience for checking conditions which are indicative of a test error rather than failure. For example, for most tests a failure to acquire memory is considered an error, not a test failure. In that case one could use the following assert to raise a test error.

    	mblk_t *mp = allocb(len, 0);
    	KT_EASSERT(mp != NULL, ctx);

  Additional Message Context
Sometimes the failure message generated by the KT_ASSERT*() macros is not enough. You may find the need to prepend additional information to the message to disambiguate the reason for failure. For example, you might find yourself asserting an invariant against an array of values and in order to disambiguate the failure you need to know the index of the value which tripped the assert. The ktest_msg_prepend() function provides this ability.

ktest_msg_prepend
    Append the given format string to the failure message. This overwrites the prepended string of any previous call making it more convenient to use in a for loop.

ktest_msg_clear
    Clear the prepend buffer. This is equivalent to ktest_msg_prepend("").

  Multiple Results
Given the nature of ktest's design it is trivial to accidentally write a test that can produce multiple results for a given execution of its code. For example, placing the KT_PASS call in a cleanup label would overwrite a failure result with a pass result. This is the unavoidable nature of ktest's implementation: unlike typical testing frameworks we are executing in kernel context and it would be annoying if test failure was reported by way of host panic.

To avoid incorrect test results the ktest facility itself checks for this scenario. For each call to the result API, ktest first checks if a result has already been set. If no result is present, then it stores the result along with its line number. However, if a result already exists, it generates an error result describing the line number of the overriding result along with the line number of the original result.

EXAMPLES

  Test Without Cleanup
This example shows the basic skeleton of a contrived test for a fictional object_t type. As there is no allocation or resource acquisition, there is no need for cleanup.

    void
    no_cleanup_test(ktest_ctx_hdl_t *ctx)
    {
    	object_t obj;
    	obj.obj_value = 7777;
    	obj.obj_state = OBJ_STATE_FIRST;
    	if (!check_for_condition_x()) {
    		KT_SKIP(ctx, "condition X was not met");
    		return;
    	}
    	KT_ASSERT3U(obj.obj_state, ==, OBJ_STATE_FIRST, ctx);
    	next_state(&obj);
    	KT_ASSERT3U(obj.obj_state, ==, OBJ_STATE_SECOND, ctx);
    	<... more obj manipulation and assertions ...>
    	KT_PASS(ctx);
    }

  Test With Cleanup
It's more likely that your test will require some amount of allocation and thus will need to make use of the KT_ASSERTG*() macros. In this scenario KT_PASS() must come before the cleanup label. Calling it after the cleanup label produces a multiple-result bug when one of the assertions trips. The ktest facility automatically catches this type of bug as explained in the "Multiple Results" section.

    void
    test_with_cleanup(ktest_ctx_hdl_t *ctx)
    {
    	mblk_t *mp = allocb(74, 0);
    	/*
    	 * Failure to allocate is an error, not a test failure.
    	 */
    	KT_EASSERT(mp != NULL, ctx);
    	/*
    	 * If any of these assertions trips, a failure result is set
    	 * and execution jumps to the 'cleanup' label.
    	 */
    	KT_ASSERT3UG(msgsize(mp), ==, 0, ctx, cleanup);
    	KT_ASSERT3PG(mp->b_rptr, ==, mp->b_wptr, ctx, cleanup);
    	KT_ASSERT3PG(mp->b_next, ==, NULL, ctx, cleanup);
    	KT_ASSERT3PG(mp->b_cont, ==, NULL, ctx, cleanup);
    	/*
    	 * All assertions passed; mark the test a success and let
    	 * execution fall into the 'cleanup' label.
    	 */
    	KT_PASS(ctx);
    cleanup:
    	freeb(mp);
    }

  Additional Failure Context
This example shows how to prepend additional context to the failure message. The ktest_msg_clear() call after the loop is important; otherwise any subsequent assert failure would pick up the prepended message from the last iteration of the loop.

    for (uint_t i = 0; i < num_objs; i++) {
            obj_t *obj = &objs[i];
            ktest_msg_prepend(ctx, "objs[%d]: ", i);
            KT_ASSERT3U(obj->o_state, ==, EXPECTED_STATE, ctx);
    }
    ktest_msg_clear(ctx);