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:

```C
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:

```C
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:

```C
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:

```C
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:

```C
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:

```C
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()`

```C
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()`

```C
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()`

```C
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()`

```C
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()`

```C
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()`

```C
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()`

```C
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()`

```C
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"`.