9unit/9unit.h

/*

	9unit
	Copyright (C) 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/>.

*/

// Types & Structs

// The following structures will typically be maintained by the
// testing framework.  You shouldn't need to concern yourself with
// them.

// Possible results of running a single test
typedef enum TestResult
{
	test_success, // the test succeeded
	test_failure, // the test failed
	test_pending // the test is pending
} TestResult;

typedef struct TestState TestState;
typedef struct TestLogEntry TestLogEntry;

// Tracks information about the tests being run.
struct TestState
{
	int run; // number of tests run
	int passed; // number of successful tests
	int failed; // number of failed tests
	int pending; // number of pending tests
	TestLogEntry *first_log; // the first log entry
	TestLogEntry *last_log; //the last log entry
	void *ptr; // used for passing data between tests
	const char *context; // immediate context of current test
	const char *full_context; // full context of current test
	int depth; // how many tests "deep" are we?
	void (*report)(const char *); // prints a string immediately
};

// Defines a log entry in a TestState struct
struct TestLogEntry
{
	char *text; // the entry text
	TestLogEntry *next; // points to the next entry
};

// Functions

// Creates an initial TestState, passes it to the supplied function,
// and displays the resulting log and summary
extern void run_tests(void (*)(TestState *));

// Adds an entry to the log that is displayed after the tests have
// completed
extern void append_test_log(
	TestState *, // the current state
	const char * // the message to append
);

// notes the current full context in the log
extern void log_test_context(TestState *);

// Runs a single test
extern void run_test(
	TestState *, // the TestState data
	TestResult (*)(TestState *) // the test to run
);

// Runs a single test with an arbitrary input
extern void run_test_with(
	TestState *, // the state
	TestResult (*)(TestState *, void *), // the test
	void * // the value to pass in
);

// Runs a single test passing in two values to be compared
extern void run_test_compare(
	TestState *, // the current state

	// the test to be run
	TestResult (*test)(
		TestState *, // the current state
		void *, // the first value
		void * // the second value
	),

	void *, // the first value
	void * // the second value
);

// Gives additional context for a test
extern void test_context(
	TestState *, // the current state
	const char *, // a description of the context
	void (*)(TestState *) // the actual test
);

// Runs a test with a context and an additional input
extern void test_context_with(
	TestState *, // the current state
	const char *, // a description of the context
	void (*)(TestState *, void *), // the test function
	void * // the value being passed in
);

// Passes two values into a test context
void test_context_compare(
	TestState *, // the current state
	const char *, // the context label

	// test function
	void (*)(
		TestState *, // the current state
		void *, // the first value
		void * // the second value
	),

	void *, // the first value
	void * // the second value
);

// Runs a single test with a context label
extern void single_test_context(
	TestState *, // the current state
	const char *, // a description of the context
	TestResult (*)(TestState *) // the actual test
);

// Runs a single test with a context and input
extern void single_test_context_with(
	TestState *, // the state
	const char *, // the context

	// the test
	TestResult (*)(
		TestState *, // the state
		void * // the value being passed
	),

	void * // the value being passed
);

// Runs a single test with a context, passing it two values to be
// compared
extern void single_test_context_compare(
	TestState *, // the state
	const char *, // the context

	// the test function
	TestResult (*)(
		TestState *, // the state
		void *, // the first value
		void * // the second value
	),

	void *, // the first value
	void * // the second value
);

//jl