Test Library

Used to write tests, create test environments and mock objects. More...

Macros
#define	CM_EXPECT(test_driver, expr)   cmExpect(test_driver, __FILE__, __LINE__, #expr, (expr))
#define	CM_EXPECT_STRING_EQ(test_driver, a, b)   cmExpectStringEq(test_driver, __FILE__, __LINE__, a, #a, b, #b)

Typedefs
typedef void(*	cmDiagnosticChecker) (struct cmTestDriver *test_driver, const struct cmDiagnostic *diagnostic)
typedef void(*	cmMessageChecker) (struct cmTestDriver *test_driver, const struct cmMessage *message)

Enumerations
enum	cmTestDriverVerbosity {   CM_HIGH_VERBOSITY,   CM_LOW_VERBOSITY }
enum	cmLogType {   CM_STATUS_LOG,   CM_START_LOG,   CM_DONE_LOG,   CM_FAIL_LOG,   CM_INFO_LOG }

Functions
void *	cmMalloc (size_t size)
void *	cmRealloc (void *addr, size_t size)
void	cmFree (void *addr)
struct cmTestDriver *	cmNewTestDriver (void)
void	cmReleaseTestDriver (struct cmTestDriver *test_driver)
void	cmSetTestDriverVerbosity (struct cmTestDriver *test_driver, enum cmTestDriverVerbosity verbosity)
void	cmLog (struct cmTestDriver *test_driver, enum cmLogType log_type, const char *fmt,...) cmLog_ATTRIBUTES
int	cmGetTestDriverResult (const struct cmTestDriver *test_driver)
void	cmExpect (struct cmTestDriver *test_driver, const char *filename, unsigned int line, const char *expr_string, int expr_result)
void	cmExpectStringEq (struct cmTestDriver *test_driver, const char *filename, unsigned int line, const char *a, const char *a_source, const char *b, const char *b_source)
struct cmTestEnvironment *	cmNewTestEnvironment (struct cmTestDriver *test_driver, const char *filename, unsigned int line, const char *name)
void	cmReleaseTestEnvironment (struct cmTestEnvironment *test_environment)
struct cmHost *	cmGetTestEnvironmentHost (struct cmTestEnvironment *test_environment)
void	cmAddTestFile (struct cmTestEnvironment *test_environment, const char *filename, const char *content)
void	cmDefineTestVariable (struct cmTestEnvironment *test_environment, const char *name, const char *value)
void	cmSetMaxAllocations (struct cmTestEnvironment *test_environment, size_t count)
void	cmIgnoreOOMDiagnostics (struct cmTestEnvironment *test_environment)
void	cmAddBinaryTestFile (struct cmTestEnvironment *test_environment, const char *filename, const char *content, size_t content_size)
int	cmParseTestOptionString (struct cmTestEnvironment *test_environment, const char *option_string) CM_WARN_UNUSED_RESULT
void	cmExpectDiagnostic (struct cmTestEnvironment *test_environment, cmDiagnosticChecker diagnostic_checker)
void	cmExpectMessage (struct cmTestEnvironment *test_environment, cmMessageChecker message_checker)
int	cmOpenTestScript (struct cmTestEnvironment *test_environment, const char *filename)
int	cmRunTestEnvironment (struct cmTestEnvironment *test_environment)

Detailed Description

Used to write tests, create test environments and mock objects.

Macro Definition Documentation

CM_EXPECT

#define CM_EXPECT	(		test_driver,
			expr
	)		cmExpect(test_driver, __FILE__, __LINE__, #expr, (expr))

Simplifies calls to cmExpect

CM_EXPECT_STRING_EQ

#define CM_EXPECT_STRING_EQ	(		test_driver,
			a,
			b
	)		cmExpectStringEq(test_driver, __FILE__, __LINE__, a, #a, b, #b)

Simplifies calls to cmExpectStringEq.

Typedef Documentation

cmDiagnosticChecker

typedef void(* cmDiagnosticChecker) (struct cmTestDriver *test_driver, const struct cmDiagnostic *diagnostic)

This is the type definition for a function that checks diagnostics.

cmMessageChecker

typedef void(* cmMessageChecker) (struct cmTestDriver *test_driver, const struct cmMessage *message)

This is the type definition for a function that checks messages.

Enumeration Type Documentation

cmLogType

enum cmLogType

Enumerates the several types of log messages.

Enumerator
CM_STATUS_LOG	This is just a status message. It is usually only used to verify the execution paths of a test.
CM_START_LOG	This notifies the start of a test.
CM_DONE_LOG	This notifies a completion of a test.
CM_FAIL_LOG	This notifies of a test failure.
CM_INFO_LOG	This gives extra information about a test failure.

cmTestDriverVerbosity

enum cmTestDriverVerbosity

Enumerates the levels of verbosity that the test driver can have.

Enumerator
CM_HIGH_VERBOSITY	The verbosity is high. Everything is reported.
CM_LOW_VERBOSITY	The verbosity is low. Only test failures are reported.

Function Documentation

cmAddBinaryTestFile()

void cmAddBinaryTestFile	(	struct cmTestEnvironment *	test_environment,
		const char *	filename,
		const char *	content,
		size_t	content_size
	)

Adds a binary file to the test environment.

Parameters

test_environment	The test environment to add the file to.
filename	The name to give the file.
content	The content of the file.
content_size	The number of bytes in this file.

cmAddTestFile()

void cmAddTestFile	(	struct cmTestEnvironment *	test_environment,
		const char *	filename,
		const char *	content
	)

Adds a file to the test environment.

Parameters

test_environment	The test environment to add the file to.
filename	The name to give the file.
content	The content of the file. This string must be null terminated.

cmDefineTestVariable()

void cmDefineTestVariable	(	struct cmTestEnvironment *	test_environment,
		const char *	name,
		const char *	value
	)

Defines a test variable.

Parameters

test_environment	The test environment to define the variable in.
name	The name to give the variable.
value	The value to give the variable.

cmExpect()

void cmExpect	(	struct cmTestDriver *	test_driver,
		const char *	filename,
		unsigned int	line,
		const char *	expr_string,
		int	expr_result
	)

Makes an expectation. An expectation is similar to an assertion but the program is not aborted if the expectation fails.

Parameters

test_driver	The test driver to make the expectation with.
filename	The filename that the expectation was made at.
line	The line that the expectation was made at.
expr_string	A string expression of the expectation.
expr_result	The result of the expression.

cmExpectDiagnostic()

void cmExpectDiagnostic	(	struct cmTestEnvironment *	test_environment,
		cmDiagnosticChecker	diagnostic_checker
	)

Notifies the test environment that it should expect a diagnostic.

Parameters

test_environment	The test environment to receive the diagnostic.
diagnostic_checker	The function used to inspect the diagnostic. If this parameter is null, then the diagnostic is received but not inspected.

cmExpectMessage()

void cmExpectMessage	(	struct cmTestEnvironment *	test_environment,
		cmMessageChecker	message_checker
	)

Notifies the test environment that is should expect a message.

Parameters

test_environment	The environment to expect a message in.
message_checker	The message checker to inspect the message with. This parameter may be a null pointer, in which case the message contents are not checked.

cmExpectStringEq()

void cmExpectStringEq	(	struct cmTestDriver *	test_driver,
		const char *	filename,
		unsigned int	line,
		const char *	a,
		const char *	a_source,
		const char *	b,
		const char *	b_source
	)

Checks for equality of two strings.

Parameters

test_driver	The test driver to log the possible failure to.
filename	The filename from FILE
line	The line from LINE
a	The primary string.
a_source	The source code that evaluates to a
b	The secondary string.
b_source	The source code that evaluates to b

cmFree()

void cmFree

(

void *

addr

)

Releases a block of memory.

Parameters

addr	The address of the memory to release.

cmGetTestDriverResult()

int cmGetTestDriverResult

(

const struct cmTestDriver *

test_driver

)

Gets the result of the test driver.

Parameters

test_driver

The test driver to get the result of.

Returns

The result of the test driver. If there were errors found in the tests, then non-zero is returned. If there weren't any errors returned, then zero is returned. This value may be used when returning from main.

cmGetTestEnvironmentHost()

struct cmHost* cmGetTestEnvironmentHost

(

struct cmTestEnvironment *

test_environment

)

Accesses the host interface for the test environment.

Parameters

test_environment

The test environment to get the host interface to.

Returns

A pointer to the test environment's host interface.

cmIgnoreOOMDiagnostics()

void cmIgnoreOOMDiagnostics

(

struct cmTestEnvironment *

test_environment

)

Ignores out of memory conditions. This is useful for testing the graceful exit of malloc failures.

Parameters

test_environment

The test environment to ignore OOM conditions.

cmLog()

void cmLog	(	struct cmTestDriver *	test_driver,
		enum cmLogType	log_type,
		const char *	fmt,
			...
	)

Makes a log entry from a test.

Parameters

test_driver	The test driver to make the log with.
log_type	The type of log message.
fmt	The format specification string.

cmMalloc()

void* cmMalloc

(

size_t

size

)

Allocates memory of a specified size. If memory allocation fails, the program is aborted.

Parameters

size	The number of bytes to allocate.

Returns

The address of the newly allocated memory.

cmNewTestDriver()

struct cmTestDriver* cmNewTestDriver

(

void

)

Creates a new test driver.

Returns

A pointer to a new test driver.

cmNewTestEnvironment()

struct cmTestEnvironment* cmNewTestEnvironment	(	struct cmTestDriver *	test_driver,
		const char *	filename,
		unsigned int	line,
		const char *	name
	)

Creates a new test environment.

Parameters

test_driver	A pointer to the test driver.
name	The name to give the test.
filename	The filename that the environment is declared in.
line	The lien within the file that the environment is declared in.

Returns

A pointer to the new test environment.

cmOpenTestScript()

int cmOpenTestScript	(	struct cmTestEnvironment *	test_environment,
		const char *	filename
	)

Opens up a test script to be executed.

Parameters

test_environment	The test environment to open the script in.
filename	The name of the file to open. This should have been created already with cmAddTestFile

Returns

Zero on success, a non-zero error code on failure.

cmParseTestOptionString()

int cmParseTestOptionString	(	struct cmTestEnvironment *	test_environment,
		const char *	option_string
	)

Parses test options.

Parameters

test_environment	The test environment to parse the options in.
option_string	The option string to parse.

Returns

Zero on success, a non-zero error code on failure.

cmRealloc()

void* cmRealloc	(	void *	addr,
		size_t	size
	)

Reallocates a block of memory. If the allocation fails, the program is aborted.

Parameters

addr	The memory block to resize. This parameter may be a null pointer, in which case a new memory block is allocated.
size	The number of bytes to resize the block to.

Returns

The address of the newly allocated memory.

cmReleaseTestDriver()

void cmReleaseTestDriver

(

struct cmTestDriver *

test_driver

)

Releases memory allocated by a test driver.

Parameters

test_driver

The test driver to release memory for.

cmReleaseTestEnvironment()

void cmReleaseTestEnvironment

(

struct cmTestEnvironment *

test_environment

)

Releases the memory allocated by a test environment.

Parameters

test_environment

The test environment to release the memory for.

cmRunTestEnvironment()

int cmRunTestEnvironment

(

struct cmTestEnvironment *

test_environment

)

Runs the test environment.

Parameters

test_environment

The test environment to run.

Returns

Zero on success, a non-zero error code on failure.

cmSetMaxAllocations()

void cmSetMaxAllocations	(	struct cmTestEnvironment *	test_environment,
		size_t	count
	)

Sets the maximum number of memory allocations.

Parameters

test_environment	The test environment to set the max allocation count of.
count	The max number of allocations to give this test environment.

cmSetTestDriverVerbosity()

void cmSetTestDriverVerbosity	(	struct cmTestDriver *	test_driver,
		enum cmTestDriverVerbosity	verbosity
	)

Assigns the verbosity of the test drive.r

Parameters

test_driver	The test driver to assign the verbosity for.
verbosity	The verbosity to set.