From 0ffc08fc41e4918a431c29f22e9252fff397c3a8 Mon Sep 17 00:00:00 2001 From: jlamothe Date: Wed, 22 Nov 2023 01:04:59 +0000 Subject: [PATCH] started writing documentation --- README.md | 103 +++++++++++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 95 insertions(+), 8 deletions(-) diff --git a/README.md b/README.md index 0ec49f3..0dbf97e 100644 --- a/README.md +++ b/README.md @@ -1,16 +1,103 @@ # 9unit Copyright (C) 2023 Jonathan Lamothe -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 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. +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 . - -## WARNING - -This library is experimental and should be considered subject to change at any time. +You should have received a copy of the GNU Lesser General Public +License along with this program. If not, see +. ## Summary -A simple C testing framework for Plan9 +A simple unit testing framework for C programs in Plan9 + +This provides the library file `9unit.a` and the header `9unit.h`. +The header file 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 a `TestState` value as their first parameter. + +## `run_tests()` + +This will typically be the first function you call in your tests. 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 failed, it will cause the test +program to exit with status of `"test(s) failed"`. Its prototype +follows: + +```C +void run_test(void (*tests)(TestState *)) +``` + +The `tests` parameter is a pointer to a function which then is +responsible for running the actual 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 them to the `run_test()` +function, which has the following prototype: + +```C +void run_test( + TestState *s, + TestResult (*test)(TestState *) +) +``` + +This function will run the provided test and update the provided +`TestState` to reflect the result of the 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()`. 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. \ No newline at end of file