ose_test_unit.h File Reference

provides unit testing functions for OSE/OSC bundles. More...

#include "ose_test_bundle_literal.h"
#include "ose_test_vm_literal.h"

Include dependency graph for ose_test_unit.h:

Go to the source code of this file.

Macros
#define	UNIT_TEST_FUNCTION(fn)   TEST_FUNCTION(ut_, fn)
	Run a unit test for a function.
#define	SKIP_UNIT_TEST_FUNCTION(fn)   SKIP_TEST_FUNCTION(fn)
	Skip a unit test function.
#define	OSE_TEST_MAX_FAILURES   200
	Execute a unit test.
#define	UNIT_TEST_IMPL(test, expected_result, desc, file, func, line)
#define	UNIT_TEST(test, expected_result, desc)
	Execute a unit test.
#define	UNIT_TEST_WITH_SIMPLE_BUNDLE(b, test, expected_result, desc)
	Execute a unit test that requires a bundle.
#define	UNIT_TEST_WITH_CONTEXT_BUNDLE_IMPL(testbndl, bundle_literal, bundle_literal_size, copy_offset, call_offset, test, expected_result, desc)
#define	UNIT_TEST_WITH_CONTEXT_BUNDLE(testbndl, test, expected_result, desc)
	Execute a unit test that requires a context bundle.
#define	UNIT_TEST_WITH_VM(testbndl, test, expected_result, desc)
	Execute a unit test that requires the VM.
#define	UNIT_TEST_BUNDLE_TRANSFORM(testfn, testbndl, resultbndl, desc)
	Execute a test that transforms the contents of a bundle.
#define	UNIT_TEST_BUNDLE_ERRNO(testfn, testbndl, errno, desc)
	Execute a test that calls testfn on a bundle and compares the errno it leaves with errno.
#define	UNIT_TEST_BUNDLE_TRANSFORM_ARGS(testfn, testbndl, resultbndl, desc, ...)
	Execute a test that transforms the contents of a bundle, where the test function takes one or more arguments in addition to a bundle.
#define	UNIT_TEST_BUNDLE_TRANSFORM_TRIGGER_ASSERTION(testfn, testbndl, desc)
	Execute a test that should fail with a triggered assertion.
#define	UNIT_TEST_BUNDLE_TRANSFORM_TRIGGER_ASSERTION_ARGS(testfn, testbndl, desc, ...)
	Execute a test that should fail with a triggered assertion.
#define	UNIT_TEST_VM_ERRNO(testfn, testbndl, errno, desc)
	Execute a test that runs the VM and results in a particular error code being set.
#define	UNIT_TEST_VM_STACK_COMPARE(testfn, testbndl, resultbndl, desc)
	Execute a test that runs the VM and compare the contents of the stack with a bundle.
#define	SKIP_UNIT_TEST_WITH_BUNDLE(b, test, expected_result)    SKIP_TEST(test, expected_result)
	Skip the execution of a unit test.
#define	SKIP_UNIT_TEST(test, expected_result)    SKIP_TEST(test, expected_result)
	Skip the execution of a unit test.

Functions
void	printb (const char *const b)
	Print each byte of a bundle.

Detailed Description

provides unit testing functions for OSE/OSC bundles.

Macro Definition Documentation

OSE_TEST_MAX_FAILURES

#define OSE_TEST_MAX_FAILURES   200

Execute a unit test.

This function executes a unit test, and prints the results. It is intended to be wrapped by another macro that provides the file name, function name, and line number (see UNIT_TEST).

Parameters

test	the test to execute
expected_result	the expected result
desc	a description of the test
file	the name of the file in which the test is taking place
func	the test function
line	the line number of the test

See also

UNIT_TEST

UNIT_TEST_WITH_SIMPLE_BUNDLE

SKIP_UNIT_TEST

#define SKIP_UNIT_TEST	(		test,
			expected_result
	)		SKIP_TEST(test, expected_result)

Skip the execution of a unit test.

Parameters

test	the test to be skipped
expected_result	the expected result

SKIP_UNIT_TEST_FUNCTION

#define SKIP_UNIT_TEST_FUNCTION

(

fn

)

SKIP_TEST_FUNCTION(fn)

Skip a unit test function.

This allows a test function to be skipped by simply prepending SKIP_ to the UNIT_TEST_FUNCTION macro. Additionally, all skipped functions will be counted and reported as such.

Parameters

fn	the function under test that is being skipped

SKIP_UNIT_TEST_WITH_BUNDLE

#define SKIP_UNIT_TEST_WITH_BUNDLE	(		b,
			test,
			expected_result
	)		SKIP_TEST(test, expected_result)

Skip the execution of a unit test.

Parameters

b	the bundle
test	the test to be skipped
expected_result	the expected reselt

UNIT_TEST

#define UNIT_TEST	(		test,
			expected_result,
			desc
	)

Value:

    UNIT_TEST_IMPL(test, expected_result, desc,     \
                   __FILE__, __func__, __LINE__);

Execute a unit test.

This is the basic unit test macro. It executes test and compares the result with expected_result and prints the result.

Parameters

test	the test to execute
expected_result	the expected result
desc	a description of the test

UNIT_TEST_BUNDLE_ERRNO

#define UNIT_TEST_BUNDLE_ERRNO	(		testfn,
			testbndl,
			errno,
			desc
	)

Value:

    UNIT_TEST_WITH_CONTEXT_BUNDLE(                          \
        testbndl,                                           \
        (testfn(bundle),                                    \
         ose_errno_get(bundle)),                            \
        errno,                                              \
        desc);

Execute a test that calls testfn on a bundle and compares the errno it leaves with errno.

The sibling of UNIT_TEST_BUNDLE_TRANSFORM, for the other half of what a stackop does: the value it computes, and the errno it sets when it refuses to. A refusal is not visible in the bundle – the whole point of most of them is that the bundle is left alone – so a transform test cannot tell "refused correctly" from "did nothing at all", and both must be asserted separately.

The status word lives at OSE_CONTEXT_STATUS_OFFSET, sixteen bytes below the bundle pointer, which is inside the buffer this fixture zeroes. So the errno read here is this bundle's own, and starts at OSE_ERR_NONE.

NOT UNIT_TEST_VM_ERRNO, which looks like it does this and does not. That one copies the test bundle to the VM's STACK and then calls testfn on the WORKING bundle, so a stackop under it operates on an empty bundle and reports a type error whatever it was given: a perfectly good 10 / 2 comes back OSE_ERR_ITEM_TYPE. Measured 2026-09-14, while writing the first tests for ose_div(). It had no callers in the tree, which is why nothing had noticed. It is presumably meant for osevm_* functions, which do take the whole VM – but nothing calls it with one of those either.

Parameters

testfn	the function to test
testbndl	an OSC bundle that will be copied into a fresh ose_bundle called bundle
errno	the ose_errno testfn is expected to leave
desc	a description of the test

UNIT_TEST_BUNDLE_TRANSFORM

#define UNIT_TEST_BUNDLE_TRANSFORM	(		testfn,
			testbndl,
			resultbndl,
			desc
	)

Value:

    if(verbose){                                            \
        printf("test bundle = ");                           \
        printb(testbndl);                                   \
        printf("\n");                                       \
        printf("expected result = ");                       \
        printb(resultbndl);                                 \
        printf("\n");                                       \
    }                                                       \
    UNIT_TEST_WITH_CONTEXT_BUNDLE(                          \
        testbndl,                                           \
        (testfn(bundle),                                    \
         COMPARE_BUNDLES(resultbndl,                        \
                         ose_getBundlePtr(bundle) - 4)),    \
        0,                                                  \
        desc);

Execute a test that transforms the contents of a bundle.

This macro executes a test that transforms the contents of an ose_bundle called bundle.

Parameters

testfn	the function to test
testbndl	an OSC bundle that will be copied into a fresh ose_bundle called bundle
resultbndl	an OSC bundle that testbndl will be compared to after testfn has been called on it
desc	a description of the test

UNIT_TEST_BUNDLE_TRANSFORM_ARGS

#define UNIT_TEST_BUNDLE_TRANSFORM_ARGS	(		testfn,
			testbndl,
			resultbndl,
			desc,
			...
	)

Value:

    UNIT_TEST_WITH_CONTEXT_BUNDLE(                          \
        testbndl,                                           \
        (testfn(bundle, __VA_ARGS__),                       \
         COMPARE_BUNDLES(resultbndl,                        \
                         ose_getBundlePtr(bundle) - 4)),    \
        0,                                                  \
        desc);

Execute a test that transforms the contents of a bundle, where the test function takes one or more arguments in addition to a bundle.

This macro is identical to UNIT_TEST_BUNDLE_TRANSFORM, except that testfn takes one or more arguments in addition to an ose_bundle.

Parameters

testfn	the function to test
testbndl	an OSC bundle that will be copied into a fresh ose_bundle called bundle
resultbndl	an OSC bundle that testbndl will be compared to after testfn has been called on it
desc	a description of the test
...	additional arguments to pass to testfn

UNIT_TEST_BUNDLE_TRANSFORM_TRIGGER_ASSERTION

#define UNIT_TEST_BUNDLE_TRANSFORM_TRIGGER_ASSERTION	(		testfn,
			testbndl,
			desc
	)

Value:

    UNIT_TEST_WITH_CONTEXT_BUNDLE(testbndl,                     \
                                  (testfn(bundle), 0),          \
                                  ASSERTION_FAILED,             \
                                  desc);

Execute a test that should fail with a triggered assertion.

This macro is similar to UNIT_TEST_BUNDLE_TRANSFORM and UNIT_TEST_BUNDLE_TRANSFORM_ARGS, except that it expects an assertion to fail, and thus does not take a resultbndl parameter, since no transformation of testbndl is actually performed.

Parameters

testfn	the function to test
testbndl	an OSC bundle that will be copied into a fresh ose_bundle called bundle
desc	a description of the test

UNIT_TEST_BUNDLE_TRANSFORM_TRIGGER_ASSERTION_ARGS

#define UNIT_TEST_BUNDLE_TRANSFORM_TRIGGER_ASSERTION_ARGS	(		testfn,
			testbndl,
			desc,
			...
	)

Value:

    UNIT_TEST_WITH_CONTEXT_BUNDLE(testbndl,                         \
                                  (testfn(bundle, __VA_ARGS__), 0), \
                                  ASSERTION_FAILED,                 \
                                  desc);

Execute a test that should fail with a triggered assertion.

This macro is similar to UNIT_TEST_BUNDLE_TRANSFORM and UNIT_TEST_BUNDLE_TRANSFORM_ARGS, except that it expects an assertion to fail, and thus does not take a resultbndl parameter, since no transformation of testbndl is actually performed.

Parameters

testfn	the function to test
testbndl	an OSC bundle that will be copied into a fresh ose_bundle called bundle
desc	a description of the test
...	additional arguments to be passed to testfn

UNIT_TEST_FUNCTION

#define UNIT_TEST_FUNCTION

(

fn

)

TEST_FUNCTION(ut_, fn)

Run a unit test for a function.

This is the basic macro that executes a unit test function. fn is the function under test, and this macro will execute a function with the name of fn with the prefix ut_ prepended to it.

Parameters

fn	the function under test

UNIT_TEST_VM_ERRNO

#define UNIT_TEST_VM_ERRNO	(		testfn,
			testbndl,
			errno,
			desc
	)

Value:

    UNIT_TEST_WITH_VM(testbndl,                 \
                      (testfn(bundle),          \
                       ose_errno_get(bundle)),  \
                      errno,                    \
                      desc)

Execute a test that runs the VM and results in a particular error code being set.

This function creates a fresh VM and places the contents of testbndl on the stack, then calls testfn and checks the error code of the VM, which should be the same as errno.

Parameters

testfn	the function under test
testbndl	the bundle that will be placed on the stack of a fresh VM
errno	the error code that should be set
desc	a description of the test

UNIT_TEST_VM_STACK_COMPARE

#define UNIT_TEST_VM_STACK_COMPARE	(		testfn,
			testbndl,
			resultbndl,
			desc
	)

Value:

    UNIT_TEST_WITH_VM(testbndl,                                         \
                      (testfn(bundle),                                  \
        ose_errno_get(bundle) == OSE_ERR_NONE \
                       && !COMPARE_BUNDLES(resultbndl,                   \
                                          buf + OSE_TEST_VM_STACK_BUNDLE_OFFSET - 4)), \
                      1,                                                \
                      desc)

Execute a test that runs the VM and compare the contents of the stack with a bundle.

This function creates a fresh VM and copies the contents of testbndl onto the stack. It then runs testfn and compares the stack to resultbndl, which should be the same.

Parameters

testfn	the function under test
testbndl	the bundle that will be placed on the stack of a fresh VM
resultbndl	the expected result bundle
desc	a description of the test

UNIT_TEST_WITH_CONTEXT_BUNDLE

#define UNIT_TEST_WITH_CONTEXT_BUNDLE	(		testbndl,
			test,
			expected_result,
			desc
	)

Value:

    UNIT_TEST_WITH_CONTEXT_BUNDLE_IMPL(testbndl,                        \
                                       ose_test_bundle_bytes,           \
                                       OSE_TEST_BUNDLE_TOTAL_SIZE - 4,  \
                                       OSE_TEST_BUNDLE_WORKING_OFFSET,  \
                                       OSE_TEST_BUNDLE_WORKING_OFFSET,  \
                                       test,                            \
                                       expected_result,                 \
                                       desc)

Execute a unit test that requires a context bundle.

This macro executes a unit test that can refer to a context bundle present in an ose_bundle called bundle.

Parameters

testbndl	an OSC bundle whose contents will be copied into a context bundle inside a fresh ose_bundle
test	the test to execute
expected_result	the expected result
desc	a description of the test

UNIT_TEST_WITH_SIMPLE_BUNDLE

#define UNIT_TEST_WITH_SIMPLE_BUNDLE	(		b,
			test,
			expected_result,
			desc
	)

Value:

    {                                                           \
        char buf[MAX_BNDLSIZE] __attribute__ ((aligned (16)));  \
        char *p = NULL;                                         \
        ose_bundle bundle;                                      \
        if(b){                                                  \
            p = buf;                                            \
            memcpy(p, b, sizeof(b));                            \
            bundle = ose_makeBundle(p + 4);                     \
        }else{                                                  \
            /* for testing NULL pointer input */                \
            bundle = ose_makeBundle(p);                         \
        }                                                       \
        if(verbose){                                            \
            printf("bundle = ");                                \
            printb(b);                                          \
            printf("\n");                                       \
        }                                                       \
        UNIT_TEST(test, expected_result, desc);                 \
    }

Execute a unit test that requires a bundle.

This macro executes test, which may include reference to an ose_bundle called bundle.

Parameters

b	an OSC bundle whose contents will be copied into a fresh ose_bundle.
test	the test to execute
expected_result	the expected result
desc	a description of the test

UNIT_TEST_WITH_VM

#define UNIT_TEST_WITH_VM	(		testbndl,
			test,
			expected_result,
			desc
	)

Value:

    UNIT_TEST_WITH_CONTEXT_BUNDLE_IMPL(testbndl,                        \
                                       ose_test_vm_bytes,               \
                                       OSE_TEST_VM_TOTAL_SIZE - 4,      \
                                       OSE_TEST_VM_STACK_BUNDLE_OFFSET, \
                                       OSE_TEST_VM_WORKING_BUNDLE_OFFSET, \
                                       test,                            \
                                       expected_result,                 \
                                       desc)

Execute a unit test that requires the VM.

This macro executes a test that may refer to a VM called bundle. The contents of testbndl will be copied onto the stack of a freshly created VM.

Parameters

testbndl	the OSC bundle that will be copied onto the stack of a VM.
test	the test to execute
expected_result	the expected result
desc	a description of the test

Execute a test against a whole VM.

The fixture is ose_test_vm_literal.h – generated, validated against ose_context.h, and regenerable. It replaced the hand-written ose_test_vm in ose_test_bundleLiteral.h, which had gone stale: the context layout changed underneath it and nothing noticed, because no test included the file.

Safe with code that touches the context cache, unlike UNIT_TEST_WITH_CONTEXT_BUNDLE – see the note there. The working bundle sits 680 bytes into this literal and the cache is 292 below it, so the cache slots are inside the allocation.

Parameters

testbndl	an OSC bundle that becomes the contents of /_s
test	the expression to evaluate
expected_result	what it should evaluate to
desc	a description of the test

Function Documentation

printb()

void printb

(

const char *const

b

)

Print each byte of a bundle.

This is a utility function that prints each byte of a bundle, using hex representation for unprintable characters.

Parameters

b	the bundle to print