EzTest

An easy to use unit testing framework written in, and created for, the C language.

Table of contents

• Introduction
• Getting started
• Asserts
• Runner
• How to contribute
• License info

Introduction

A simple test

TEST(Math, AddingTwoOnTwoShouldEqualFour)
{
    const int expected = 4;
    const int actual = math_add(2, 2);
    
    ASSERT_ARE_EQUAL(expected, actual); // or ASSERT_EQ(expected, actual); using the shorthand.
}

The asserts are created using the power of the C11 macro _Generic. As seen in the above example, this means that the user doesn't have to provide any prefix or suffix to represent the data type.

A full test (Setup and Teardown)

EzTest also provides the option of setup and teardown functions. The setup function is a function that runs before every test within a test suite. The teardown function has similar behaviour, but runs after the test. A test utilizing setup and teardown functions is defined by using the TEST_FULL(suite, name) macro. A setup and teardown function must also be defined for the test suite when using the full test macro. This is done with the SETUP(suite) and TEARDOWN(suite) macros.

SETUP(Math)
{
    // Code to run before every test in the Math suite.
}

TEST_FULL(Math, AddingTwoOnTwoShouldEqualFour)
{
    // Test code placed here.
}

TEARDOWN(Math)
{
    // This code runs after every test in the Math suite.
}

See the next section for information on how to get started with EzTest.

Getting started

EzTest was created to make unit testing quick and easy in C. The fastest way to get started with EzTest is by using the template. The template provides a default project layout for C projects using EzTest. After getting the template or creating your own project structure, you are ready to start.

1. Write tests using the test macros

Before having access to the test macros you need to include the eztest header file: #include "eztest.h". There are two macros for creating tests: TEST(suite, test) and TEST_FULL(suite, test). The first is for simple unit tests while the second is for tests with a setup and teardown function. Both of these macros take the same arguments.

Argument 1: Suite

This is the name of the test suite that the test will be associated with. The name must follow the rules for variable names in C and must be unique through out your tests. The suite name can be used to group multiple tests providing a better overview for the tester.

Argument 2: Test

This is the name of the test. The name must follow the rules for variable names in C and must be unique within the test suite.

Example usage of both TEST(suite, test) and TEST_FULL(suite, test) can be found in the usage section.

2. Build/ Compile

Option I: CMake/Template

The perhaps simplest way to build your tests is to use CMake. If you are using CMake and/or the template, then follow the build instructions given here.

Option II: Manual build

To build the EzTest runner, compile using a C11 compatible C compiler by providing the runner.c source file along with your test files.
Example compile: $ gcc -o ezrunner runner.c <test-files>

3. Run

Run the executable to run your tests. The test runner can take multiple optional arguments to customize your test experience. Learn more about the test runner here.

Asserts

Macro	Shorthand	Description	Details
ASSERT_IS_NULL		Tests whether the provided pointer is null.	Documentation
ASSERT_IS_NOT_NULL		Tests whether the provided pointer is non-null.	Documentation
ASSERT_IS_TRUE		Tests whether the condition is true.	Documentation
ASSERT_IS_FALSE		Tests whether the condition is false.	Documentation
ASSERT_ARE_SAME		Tests whether the two pointers refer to the same memory location.	Documentation
ASSERT_ARE_NOT_SAME		Tests whether the two pointers refer to different memory locations.	Documentation
ASSERT_IS_NAN		Tests whether the provided float is NaN.	Documentation
ASSERT_ARE_EQUAL	ASSERT_EQ	Tests whether the two values are equal.	Documentation
ASSERT_ARE_EQUAL_PRECISION	ASSERT_EQ_PRECISION	Tests whether two floating point numbers are equal using a user provided epsilon.	Documentation
ASSERT_ARE_EQUAL_MEM	ASSERT_EQ_MEM	Tests whether the two values are equal by comparing each byte at the given memory locations.	Documentation
ASSERT_ARE_EQUAL_CMP	ASSERT_EQ_CMP	Tests whether the two values are equal by using the passed comparator function.	Documentation
ASSERT_ARE_NOT_EQUAL	ASSERT_NE	Tests whether the two values are different.	Documentation
ASSERT_ARE_NOT_EQUAL_PRECISION	ASSERT_NE_PRECISION	Tests whether two floating point numbers are different using a user provided epsilon.	Documentation
ASSERT_ARE_NOT_EQUAL_MEM	ASSERT_NE_MEM	Tests whether the two values are different by comparing each byte at the given memory locations.	Documentation
ASSERT_ARE_NOT_EQUAL_CMP	ASSERT_NE_CMP	Tests whether the two values are different by using the passed comparator function.	Documentation
ASSERT_GREATER	ASSERT_GT	Tests whether the first value is greater than the second value.
ASSERT_GREATER_PRECISION	ASSERT_GT_PRECISION	Tests whether the first floating point value is greater than the second floating point value using a user provided epsilon.
ASSERT_GREATER_MEM	ASSERT_GT_MEM	Tests whether the first n bytes at the first memory location is greater than the n first bytes at the second memory location.
ASSERT_GREATER_CMP	ASSERT_GT_CMP	Tests whether the first value is greater than the second value by using the passed comparator function.
ASSERT_GREATER_EQUAL	ASSERT_GE	Tests whether the first value is greater than or equal to the second value.
ASSERT_GREATER_EQUAL_PRECISION	ASSERT_GE_PRECISION	Tests whether the first floating point value is greater than or equal to the second floating point value using a user provided epsilon.
ASSERT_GREATER_EQUAL_MEM	ASSERT_GE_MEM	Tests whether the first n bytes at the first memory location is greater than or equal to the n first bytes at the second memory location.
ASSERT_GREATER_EQUAL_CMP	ASSERT_GE_CMP	Tests whether the first value is greater than or equal to the second value by using the passed comparator function.
ASSERT_LESS	ASSERT_LT	Tests whether the first value is lesser than the second value.
ASSERT_LESS_PRECISION	ASSERT_LT_PRECISION	Tests whether the first floating point value is lesser than the second floating point value using a user provided epsilon.
ASSERT_LESS_MEM	ASSERT_LT_MEM	Tests whether the first n bytes at the first memory location is lesser than the n first bytes at the second memory location.
ASSERT_LESS_CMP	ASSERT_LT_CMP	Tests whether the first value is lesser than the second value by using the passed comparator function.
ASSERT_LESS_EQUAL	ASSERT_LE	Tests whether the first value is lesser than or equal to the second value.
ASSERT_LESS_EQUAL_PRECISION	ASSERT_LE_PRECISION	Tests whether the first floating point value is lesser than or equal to the second floating point value using a user provided epsilon.
ASSERT_LESS_EQUAL_MEM	ASSERT_LE_MEM	Tests whether the first n bytes at the first memory location is lesser than or equal to the n first bytes at the second memory location.
ASSERT_LESS_EQUAL_CMP	ASSERT_LE_CMP	Tests whether the first value is lesser than or equal to the second value by using the passed comparator function.

Runner

The runner is the program that executes the tests.

Exit code

The exit code is EXIT_SUCCESS (0) if all tests passed and EXIT_FAILURE (non-zero) if one or more tests failed.

Options

Short	Long	Description
-v	--version	Prints the version number.
-h	--help	Prints help/ usage information.
-c	--no-color	Don't use any color when printing.
-t	--timer	Display execution time for each test.
-q	--quiet	No output.
-s	--skip	Skips all tests in the passed list of test suits. The argument for this option should be a comma separated list of case-sensitive test suit names that you want to skip.
-f	--SIGSEGV	Segmentation fault is handled like other test failures.

Contribute

We welcome all contributions, please see the contribution guidelines.

License

This project is licensed under the MIT License - see LICENSE.md for details.