9unit/README.md

9unit

Copyright (C) 2023 Jonathan Lamothe jonathan@jlamothe.net

This program is free software: you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public License along with this program. If not, see http://www.gnu.org/licenses/.

Summary

A simple unit testing framework for C programs in Plan9

This provides the library file 9unit.a and the header 9unit.h. The header is relatively well commented and can provide a fairly comprehensive breakdown of the API. This document will however provide a basic overview below.

This library is used to test itself, consequently the test directory contains a relitively decent real-world (if somewhat confusing) example of how it can be used.

TestState

The entire testing framework is centred around the TestState data structure. As its name would imply, it contains the current state of the tests in progress, however it should almost never be necessary to interact with it directly. With the exception of run_tests() (described below), all functions provided by the library will take take a pointer to the current TestState value as their first argument.

run_tests()

This will typically be the first function called. It creates an initial TestState value, runs the tests, and displays a test log and summary at the end. If any of the tests fail, it will cause the test process to exit with a status of "test(s) failed". Its prototype follows:

void run_tests(void (*)(TestState *));

Its only argument is a pointer to a function which is then responsible for actually running the tests. A pointer to the newly created TestState value will be passed to this function.

Simple Tests

The simplest form of test can be represented by a function resembling the follwoing:

TestResult my_test(TestState *s)
{
	// test code goes here...
}

This function should return a TestResult value representing (perhaps unsurprisingly) the result of the test. The options are as follows:

• test_success: the test was completed successfully
• test_failure: the test failed
• test_pending: the test is pending, and should be ignored for now

Tests of this type can be run by passing a pointer to them to the run_test() function which has the following prototype:

void run_test(
	TestState *,
	TestResult (*)(TestState *)
)

This function will call the provided test function, and update the provided TestState to reflect the result. Thus, the above hypothetical test could by run as follows:

void
tests(TestState *s)
{
	run_test(s, my_test);
}

void
main()
{
	run_tests(tests);
	exits(0);
}

Passing a null TestState pointer will cause nothing to happen. This is true of all functions in this library. (This behaviour might be reconsidered later, so don't count on it.) Passing a null function pointer to run_test() is interpreted as a pending test.

Passing Values to Tests

Since C supports neither lambdas nor closures, this would leave one with little choice but to come up with a unique name for each individual test function. This, while possible, would definitely be rather inconvenient. To combat this shortcoming, it is helpful to be able to pass data into a generic test function so that it can be reused multiple times.

The ptr Value

The TestState struct has a value called ptr which is a void pointer that can be set prior to calling run_test() (or any other function, really). This value can then be referenced by the test function, giving you the ability to essentially pass in (or out) any type of data you may need. While not ideal, it's a solution.

The library does not perform any kind of validation or automatic memory management on the ptr value (this is C after all), so the responsibility for this falls to the programmer implementing the tests.

Convenience Functions

As the test suite becomes more and more complex, managing a single ptr value can become increasingly burdensome. For this reason, there are a few convenience functions that provide an alternate mechanism for passing data into a function without altering the ptr value. (They actually do alter it internally, but they restore the original value before passing the state on.) Two such functions are: run_test_with(), and run_test_compare().

run_test_with() has the following prototype:

void run_test_with(
	TestState *,
	TestResult (*)(TestState *, void *),
	void *
);

The first argument points to the current test state. The second points to a test function much like the simple test function described above, but that takes a void pointer as a second argument. Finally, the third argument is the pointer that gets passed into the test function.

run_test_compare() is similar, but it allows two pointers to be passed into the test function. This is useful for comparing the actual output of a function to an expected value, for instance.

The prototype for run_test_compare() follows:

void run_test_compare(
	TestState *,
	TestResult (*)(TestState *, void *, void *),
	void *,
	void *
);

The pointers will be passed into the test function in the same order they are passed into run_test_compare().

Test Contexts

It is useful to document what your tests are doing. This can be achieved using contexts. Contexts are essentially labelled collections of related tests. Contexts can be nested to create hierarchies. This is useful both for organization purposes as well as creating reusable test code. There are several functions written for managing these contexts. Each of these functions takes as its first two arguments: a pointer to the current TestState, and a pointer to a string describing the context it defines. If the pointer to the string is null, the tests are run as a part of the existing context.

test_context()

void test_context(
	TestState *,
	const char *,
	void (*)(TestState *)
);

This function takes a pointer to the current TestState, a string describing the context, and a function pointer that is used the same way as the one passed to run_tests(). This function will be called and its tests will be run within the newly defined context. Nothing prevents this function from being called again in a different context.

test_context_with()

void test_context_with(
	TestState *,
	const char *,
	void (*)(TestState *, void *),
	void *
);

This funciton works similarly to test_context(), but allows for the passing of a void pointer into the test function in much the same way as the run_test_with() function. Its arguments are (in order), a pointer to the current state, the context description, a pointer to the test function, and the pointer to be passed into that function.

test_context_compare()

void test_context_compare(
	TestState *,
	const char *,
	void (*)(TestState *, void *, void *),
	void *,
	void *
);

This funciton allows the passing to two void pointers into a context in a manner similar to run_test_compare().

single_test_context()

void single_test_context(
	TestState *,
	const char *,
	TestState (*)(TestState *)
);

This function applies the context label to a single test. The function passed in is expected to operate in the same way as the one passed to run_test().

single_test_context_with()

void single_test_context_with(
	TestState *,
	const char *,
	TestState (*)(TestState *, void *),
	void *
);

This is similar to single_test_context() but allows a void pointer to be passed as in run_test_with().

single_test_context_compare()

void single_test_context_compare(
	TestState *,
	const char *,
	TestResult (*)(TestState *, void *, void *),
	void *,
	void *
);

I assume you get the idea at this point.

Logging

When run_tests() finishes running the tests, it displays a log and summary. The summary is simply a tally of the number of tests run, passed, failed, and pending. While this is useful (and probably all you need to know when all the tests pass) it is likely desirable to have more detail when something goes wrong. To facilitate this, tests can append to the test log, which is automatically displayed just before the summary. There are two functions for doing this.

append_test_log()

void append_test_log(
	TestState *,
	const char *
);

This appends an arbitrary string to the end of the test log. The contents of the string are copied into the log, so the value pointed to by the second argument does not need to persist in memory beyond the end of the call to the function. Log entries are expected to be single lines. No trailing newline should be present (but the trailing NUL character should (obviously)).

log_test_context()

void log_test_context(TestState *);

This function appends an entry to the log indicating the test's current full context. If no context is defined, the log entry will be "<no context>". If the test is inside of a context labeled "foo" which is inside of another context labeled "bar", the resulting log entry will read "bar: foo".