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 the library itself, consequently, the test directory contains a relitively decent real-world 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 you call. It sets up the testing framework, creates an initial TestState value, runs the tests provided to it, and displays a log and summary at the end. If any of the provided tests fail, it will cause the test program 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 as a function resembling the follwoing:

TestResult my_test(TestState *s)
{
	// ...
}

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 run the provided test and update the state to reflect the result of the test. 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. Passing a null function pointer to run_test() will be interpreted as a pending test.

Passing Values to Tests

Since C supports neither lambdas nor closures, this leaves one with little choice but to come up with a unique name for each test function. This, while possible, would definitely be rather inconvenient. To combat this, it is helpful to be able to pass data into a generic test 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 read by the test function, giving you the ability to essentially pass in 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 tests become 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 of passing data into a function, without altering the ptr value. (They actually do 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. 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 *
);

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 into 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 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 pointer passed to run_tests().

test_context_with()

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

This funciton 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 being 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 a function 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 count 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) you probably want 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".