EzTest

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

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.

havardt / eztest Goto Github PK

eztest's Introduction

EzTest

Table of contents

Introduction

A simple test

A full test (Setup and Teardown)

Getting started

1. Write tests using the test macros

Argument 1: Suite

Argument 2: Test

2. Build/ Compile

Option I: CMake/Template

Option II: Manual build

3. Run

Asserts

Runner

Exit code

Options

Contribute

License

eztest's People

Contributors

Stargazers

Watchers

eztest's Issues

4 new equality asserts should be added:

Recommend Projects

Recommend Topics

Recommend Org