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
parameter.

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

```C
void run_tests(void (*)(TestState *));
```

Its only argument is a pointer to a function which is then
responsible for acuually 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:

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

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

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

```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.  This is useful for comparing an actual value to
an expected one, for instance comparing the actual output from a
function to an expected value.

The prototype for `run_test_compare()` follows:

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

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

### `test_context_with()`

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

```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 a
function 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 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()`

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