# CTest
 
## Overview

`CTest` is a `C` test harness. It provides a test runner and a set of assert macros that can be used to write tests.

`CTest` is designed to:

- Only use C for writing tests in order to minimize mixing C and C++ (sometimes the mix is just not desired)
- Maximize portability, thus trying to avoid at any costs compiler implementation specific features.
Using CTest
The following steps are required in order to use CTest:
- Include ctest.h in a .c file
- Write the tests in the .c file as part of a test suite
- Link the test runner in your executable
- As part of main (or any other function), execute the test suite

## The first test

The below example shows a simple test written by using CTest:

```c
#include "CTest.h"
#include "SomeUnitUnderTest.h"

CTEST_BEGIN_TEST_SUITE(SimpleTestSuiteOneTest)

CTEST_FUNCTION(Test1)
{
    // arrange

    // act
    int x = SomeFunction();

    // assert
    CTEST_ASSERT_ARE_EQUAL(int, 42, x);
}

CTEST_END_TEST_SUITE(SimpleTestSuiteOneTest)
```

In order to run the suite, the main function would contain:

```c
#include "CTest.h"

int main(int argc, char* argv[])
{
    CTEST_RUN_TEST_SUITE(SimpleTestSuiteOneTest);

    return 0;
}
```

The results would look like:

![](img/ctest_results.png)
 
## Test suites

One test suite is supported per translation unit.

The beginning of a test suite is marked by the macro `CTEST_BEGIN_TEST_SUITE(suiteName)`.
The end of a test suite is marked by the macro `CTEST_END_TEST_SUITE(suiteName)`.

To run all the tests in a test suite the following macro can be used:

```c
CTEST_RUN_TEST_SUITE(suiteName{,failedTestCount});
```

The execution order of the tests in a test suite is not guaranteed. Tests are executed sequentially.

The `failedTestCount` argument for `CTEST_RUN_TEST_SUITE` is optional. If specified, the number of failed tests will be summed up in the `failedTestCount` variable, that is passed as argument.

## Fixtures

### CTEST_SUITE_INITIALIZE

This special fixture is executed before all the tests in the test suite. All resources allocated in `CTEST_SUITE_INITIALIZE` should be freed in `CTEST_SUITE_CLEANUP`.

```c
CTEST_SUITE_INITIALIZE()
{
    /* Some init code */
}
```

### CTEST_SUITE_CLEANUP

This special fixture is executed after all the tests in the test suite.

```c
CTEST_SUITE_CLEANUP()
{
    /* Free resources allocated in CTEST_SUITE_INITIALIZE */
}
```

### CTEST_FUNCTION_INITIALIZE

This special fixture is executed before calling each test function in the test suite. All resources allocated in `CTEST_FUNCTION_INITIALIZE` should be freed in `CTEST_FUNCTION_CLEANUP`.

```c
CTEST_FUNCTION_INITIALIZE()
{
    /* Initialize specific things for each test function */
}
```

### CTEST_FUNCTION_CLEANUP

This special fixture is executed after each test in the test suite.

```c
CTEST_FUNCTION_CLEANUP()
{
    /* Free resources allocated in CTEST_FUNCTION_INITIALIZE */
}
```

## Assert macros

Assert macros allow asserting various results and failing the tests if the asserted values/expressions fail.
By default if no assert macro fails a test, the test is reported as successful.

The following assert macros are supported by CTEST:

### CTEST_ASSERT_FAIL(message);

This macro fails the test and displays the message argument.

### CTEST_ASSERT_ARE_EQUAL(type, expected, actual, [format, …]);

This macro compares the expected and actual values, assuming they are of type “type” and fails the test if the values are different.

```c
CTEST_FUNCTION(Assert_Are_Equal_2_Ints_Fails)
{
    // arrange

    // act
    int x = SomeFunction();

    // assert
    CTEST_ASSERT_ARE_EQUAL(int, 42, x);
}
```

### CTEST_ASSERT_ARE_NOT_EQUAL(type, expected, actual, [format, …]);

This macro compares the expected and actual values, assuming they are of type `type` and fails the test if the values are equal.

```c
CTEST_FUNCTION(Assert_Are_Not_Equal_2_Ints_Fails)
{
    // arrange

    // act
    int x = SomeFunction();

    // assert
    CTEST_ASSERT_ARE_NOT_EQUAL(int, 0, x);
}
```

When using the `[format, …]` optional arguments to specify an assert message:

```c
CTEST_FUNCTION(Assert_Are_Not_Equal_2_Ints_Fails)
{
    // arrange

    // act
    int x = SomeFunction();

    // assert
    CTEST_ASSERT_ARE_NOT_EQUAL(int, 0, x, "{ Message with int: %d }", 42);
}
```

### CTEST_ASSERT_IS_NULL(value, [format, …]);

This macro fails the test if the value argument is not NULL.

```c
CTEST_FUNCTION(Assert_Is_NULL)
{
    // arrange

    // act
    void* x = SomeFunction();

    // assert
    CTEST_ASSERT_IS_NULL(x);
}
```

### CTEST_ASSERT_IS_NOT_NULL(value, [format, …]);

This macro fails the test if the value argument is NULL.

```c
CTEST_FUNCTION(Assert_Is_Not_NULL)
{
    // arrange

    // act
    void* x = SomeFunction();

    // assert
    CTEST_ASSERT_IS_NOT_NULL(x);
}
```

### CTEST_ASSERT_IS_TRUE(expression, [format, …]);

This macro fails the test if expression evaluates to zero.

```c
CTEST_FUNCTION(Assert_Is_True)
{
    // arrange

    // act
    int x = SomeFunction();

    // assert
    CTEST_ASSERT_IS_TRUE(x == 4);
}
```

### CTEST_ASSERT_IS_FALSE(value, [format, …]);

This macro fails the test if expression evaluates to something different than zero.

```c
CTEST_FUNCTION(Assert_Is_False)
{
    // arrange

    // act
    int x = SomeFunction();

    // assert
    CTEST_ASSERT_IS_FALSE(x != 4);
}
```

## Specialized comparer and string conversion function

### CTEST_COMPARE(niceType, type)

In order to allow comparing of specialized types (i.e. structures, etc.), the `CTEST_COMPARE` macro can be used:

```c
typedef struct mystruct_tag
{
    unsigned char x;
} mystruct;

CTEST_COMPARE(mystruct_ptr, mystruct*)
{
    return (left->x != right->x)
}
```

A comparer is responsible for comparing 2 values (passed as arguments): left and right.

`left` and `right`, are of the type “type”. The comparer function should return a value different than zero if the `left` and `right` values are different; otherwise, if the values are equal it should return zero.

The `niceType` is a `typedef` (cannot contain any invalid characters like space, *, etc).

### CTEST_TOSTRING(niceType, type, string, bufferSize, value)

```c
CTEST_TOSTRING(mystruct_ptr, mystruct*, string, bufferSize, value)
{
    (void)snprintf(string, bufferSize, "{ %d }", (int)value->x);
}
```

The function should print in `dst` the desired representation of value, where `value` is of type `type`, and `dst` is of type `char*`.

The `niceType` is a `typedef` (cannot contain any invalid characters like space, *, etc).

### Out of the box supported types

The `CTest` harness supports out of the box string formatting and comparers for the following types:

- `int`
- `char`
- `short`
- `long`
- `uint8_t`
- `int8_t`
- `uint16_t`
- `int16_t`
- `uint32_t`
- `int32_t`
- `uint64_t`
- `int64_t`
- `size_t`
- `float`
- `double`
- `long double`
- `char*` (`char_ptr`)

### CTEST_DEFINE_ENUM_TYPE

`CTEST_DEFINE_ENUM_TYPE` can be used with an enum defined by using the macro utils feature `MU_DEFINE_ENUM` in order to generate the needed `_ToString` and `_Compare` functions.

Example:

```c
#define TEST_ENUM_VALUES \
    TEST_VALUE_A, \
    TEST_VALUE_B

MU_DEFINE_ENUM(TEST_ENUM, TEST_ENUM_VALUES)
MU_DEFINE_ENUM_STRINGS(TEST_ENUM, TEST_ENUM_VALUES)
CTEST_DEFINE_ENUM_TYPE(TEST_ENUM, TEST_ENUM_VALUES)
```

### CTEST_DEFINE_ENUM_2_TYPE

`CTEST_DEFINE_ENUM_2_TYPE` can be used with an enum defined by using the macro utils feature `MU_DEFINE_ENUM_2` in order to generate the needed `_ToString` and `_Compare` functions.

Example:

```c
#define TEST_ENUM_VALUES \
    TEST_VALUE_A, 0 \
    TEST_VALUE_B, 1

MU_DEFINE_ENUM_2(TEST_ENUM, TEST_ENUM_VALUES)
MU_DEFINE_ENUM_STRINGS_2(TEST_ENUM, TEST_ENUM_VALUES)
CTEST_DEFINE_ENUM_2_TYPE(TEST_ENUM, TEST_ENUM_VALUES)
```