libcester Doc Reference Contribute Exotic Libraries Support

Helper Macros¶

All macros in the library starts with CESTER_.

CESTER_TEST¶

The macro for creating a test case. The macro takes care of initialization and declaration of the function and also takes care of the test case registration. The first parameter is the name of the test case, the second parameter is the TestInstance object to share data and command line arguments and the third is the test case body.

During the compile time code generation process the first time the macro is expanded it declare the test case function, in the second expansion it registered the test case function in the static array and in the final expansion the test case function is initialized.

For the test case below:

CESTER_TEST(test_case_name, test_instance,
    cester_assert_nothing();
)

First Expansion

static void cester_test_test_case_name(TestInstance* test_instance);

Second Expansion

static TestCase cester_test_cases[] = {
    { CESTER_RESULT_UNKNOWN, __LINE__, CESTER_RESULT_SUCCESS, 0.000, 0.000, (char*) "",
    (char*) "test_case_name", (cester_test_test_case_name), NULL, NULL, CESTER_NORMAL_TEST }
}

Final Expansion

static void cester_test_test_case_name(TestInstance* test_instance) {
    cester_assert_nothing();
}

Therefore after the final expansion the source code will have transformed to this

static void cester_test_test_case_name(TestInstance* test_instance);

static TestCase cester_test_cases[] = {
    { CESTER_RESULT_UNKNOWN, __LINE__, CESTER_RESULT_SUCCESS, 0.000, 0.000, (char*) "",
    (char*) #x, (cester_test_test_case_name), NULL, NULL, CESTER_NORMAL_TEST }
}

static void cester_test_test_case_name(TestInstance* test_instance) {
    cester_assert_nothing();
}

CESTER_TODO_TEST¶

Work the same as the CESTER_TEST macro but the test type is CESTER_NORMAL_TODO_TEST. Test case declared with this macro is not executed but it reported as todo test.

CESTER_TODO_TEST(a_test_to_implement, test_instance,

)

This macro is most useful for Test Driven Development (TDD). It create test cases for ops that has not been implemented yet.

CESTER_SKIP_TEST¶

Work the same as the CESTER_TEST macro but the test type is CESTER_NORMAL_SKIP_TEST. Test case declared with this macro is not executed but it reported as skipped test.

CESTER_SKIP_TEST(a_test_to_implement, test_instance,

)

There are various reason to creat a test with this macro, an example is running the test file in an environment where the resources needed by the test case is not available.

CESTER_BEFORE_ALL¶

The function to setup the test resources before running the test case. It accepts the TestInstance object as the first parameter. The TestInstance parameter can be used to share data and object between the test cases.

CESTER_BEFORE_ALL(test_instance,
    test_instance->arg = "beforeall";
)

CESTER_TEST(test_case, test_instance,
    cester_assert_str_equal((char*)(test_instance->arg), "beforeall");
)

Note

If you have any of CESTER_BEFORE_ALL, CESTER_BEFORE_EACH, CESTER_AFTER_ALL and CESTER_AFTER_EACH. Your test cases will be executed on a single process to allow shared objects.

CESTER_BEFORE_EACH¶

Use the macro to create a function that is invoked before each test case is executed. It accepts the TestInstance object as the first parameter, the current test name as the second parameter, the test case index as the third parameter.

CESTER_BEFORE_EACH(test_instance, test_name, index,
    if (test_name == "test_xml") {
        test_instance->arg = (void*) fopen("./result.xml", "r");

    } else if (test_name == "test_json") {
        test_instance->arg = (void*) fopen("./result.json", "r");
    }
)

This macro can be used to setup resources according to the test case.

Note

If you have any of CESTER_BEFORE_ALL, CESTER_BEFORE_EACH, CESTER_AFTER_ALL and CESTER_AFTER_EACH. Your test cases will be executed on a single process to allow shared objects.

CESTER_AFTER_EACH¶

Use the macro to create a function that is invoked after each test case is executed. It accepts the TestInstance object as the first parameter, the current test name as the second parameter, the test case index as the third parameter.

CESTER_AFTER_EACH(test_instance, test_name, index,
    if (test_name == "test_xml" || test_name == "test_json") {
        fclose((FILE*)(test_instance->arg));
    }
)

This macro can be used to tear down resources according to the test case.

Note

If you have any of CESTER_BEFORE_ALL, CESTER_BEFORE_EACH, CESTER_AFTER_ALL and CESTER_AFTER_EACH. Your test cases will be executed on a single process to allow shared objects.

CESTER_AFTER_ALL¶

The function to tear down the test resources after running the test case. It accepts the TestInstance object as the first parameter. This macro should be used to clean up shared object and close opened resources.

CESTER_AFTER_ALL(test_instance,
    free(test_instance->arg);
)

Note

If you have any of CESTER_BEFORE_ALL, CESTER_BEFORE_EACH, CESTER_AFTER_ALL and CESTER_AFTER_EACH. Your test cases will be executed on a single process to allow shared objects.

CESTER_OPTIONS¶

This macro should be used to set the options accepted by cester. The function is executed before any of the setup functions and the test case.

CESTER_OPTIONS(
    CESTER_NOCOLOR();
    CESTER_NO_ISOLATION();
    CESTER_OUTPUT_JUNITXML();
)

CESTER_COMMENT¶

A multiline comment macro everything in the macro is printed out at the beginning of the test. Comma in the content will cause issue in the macro expansion when the code is compiled with C version less than C99. It should not begin or end in quote, escape characters is expanded when printed out

CESTER_COMMENT(
    This is a multiline comment in \n
    the source code this text is printed out \n
    before any test cases is executed.
)

CESTER_REPORT_SUCCESS_REGARDLESS¶

Always mark the test as success even if the test cases failed or an error occur while running the test.

CESTER_OPTIONS(
    CESTER_REPORT_SUCCESS_REGARDLESS();
)

CESTER_REPORT_FAILURE_REGARDLESS¶

Always mark the test as failure even if the test cases passes and no error occur.

CESTER_OPTIONS(
    CESTER_REPORT_FAILURE_REGARDLESS();
)

CESTER_REGISTER_TEST¶

Manually register a test case. For a compiler that does not have the __BASE_FILE__ macro defined the test case won’t be registered at compile time, the test cases can be registered at runtime using this macro.

CESTER_TEST(test_case_name, test_instance,
    cester_assert_nothing();
)

CESTER_BODY(
int main(int argc, char** argv) {
    CESTER_REGISTER_TEST(test_case_name);
    return CESTER_RUN_ALL_TESTS(argc, argv);
}
)

CESTER_REGISTER_SKIP_TEST¶

Manually register a test case as a skip test which cases the test case not to run but it will be reported in result and logged under skipped tests.

CESTER_SKIP_TEST(test_case_name, test_instance,
    cester_assert_nothing();
)

CESTER_BODY(
int main(int argc, char** argv) {
    CESTER_REGISTER_SKIP_TEST(test_case_name);
    return CESTER_RUN_ALL_TESTS(argc, argv);
}
)

CESTER_REGISTER_TODO_TEST¶

Manually register a test case that is yet to be implemented so it will be skipped but it will be reported in result and logged under todo tests.

CESTER_TODO_TEST(test_case_name, test_instance,
    cester_assert_nothing();
)

CESTER_BODY(
int main(int argc, char** argv) {
    CESTER_REGISTER_TODO_TEST(test_case_name);
    return CESTER_RUN_ALL_TESTS(argc, argv);
}
)

CESTER_REGISTER_BEFORE_ALL¶

Manually notify cester to execute the CESTER_BEFORE_ALL function before all the test case are run.

CESTER_BODY(
int main(int argc, char** argv) {
    CESTER_REGISTER_BEFORE_ALL();
    return CESTER_RUN_ALL_TESTS(argc, argv);
}
)

Warning

The test cases registered at compile time are ignored if at least one test case is registered at run time with this macro.

CESTER_REGISTER_AFTER_ALL¶

Manually notify cester to execute the CESTER_AFTER_ALL function after all the test case are run.

CESTER_BODY(
int main(int argc, char** argv) {
    CESTER_REGISTER_AFTER_ALL();
    return CESTER_RUN_ALL_TESTS(argc, argv);
}
)

Warning

The test cases registered at compile time are ignored if at least one test case is registered at run time with this macro.

CESTER_REGISTER_BEFORE_EACH¶

Manually notify cester to execute the CESTER_BEFORE_EACH function before each of the test case are run.

CESTER_BODY(
int main(int argc, char** argv) {
    CESTER_REGISTER_BEFORE_EACH();
    return CESTER_RUN_ALL_TESTS(argc, argv);
}
)

Warning

The test cases registered at compile time are ignored if at least one test case is registered at run time with this macro.

CESTER_REGISTER_AFTER_EACH¶

Manually notify cester to execute the CESTER_AFTER_EACH function after each of the test case are run.

CESTER_BODY(
int main(int argc, char** argv) {
    CESTER_REGISTER_AFTER_EACH();
    return CESTER_RUN_ALL_TESTS(argc, argv);
}
)

Warning

The test cases registered at compile time are ignored if at least one test case is registered at run time with this macro.

CESTER_REGISTER_OPTIONS¶

Manually notify cester to execute the CESTER_OPTIONS function before running any test cases.

CESTER_BODY(
int main(int argc, char** argv) {
    CESTER_REGISTER_OPTIONS();
    return CESTER_RUN_ALL_TESTS(argc, argv);
}
)

Warning

The test cases registered at compile time are ignored if at least one test case is registered at run time with this macro.

CESTER_TEST_SHOULD¶

Set the expected result of a test case. It accept the test case name as the first paramater, it accepts the expected result as the second parameter. The expected result mush be one of the enum types

CESTER_RESULT_SUCCESS
CESTER_RESULT_FAILURE
CESTER_RESULT_TERMINATED
CESTER_RESULT_SEGFAULT
CESTER_RESULT_MEMORY_LEAK
CESTER_RESULT_UNRELEASED_STREAM

CESTER_TEST(test_case_name, test_instance,

)

CESTER_OPTIONS(
    CESTER_TEST_SHOULD(test_case_name, CESTER_RESULT_SUCCESS);
)

CESTER_TEST_SHOULD_SEGFAULT¶

Change the expected result of a test case to Segfault. If the test segfault then it passes. If it does not segfault it is marked as failed. It accept the test case name as paramater.

CESTER_TEST(test_case_name, test_instance,
    int *p = NULL;
    *p=0xdead;
)

CESTER_OPTIONS(
    CESTER_TEST_SHOULD_SEGFAULT(test_case_name);
)

CESTER_TEST_SHOULD_FAIL¶

Change the expected result of a test case to failure. If the test case passed then it marked as failure. If it failed then it consider as passed. It accept the test case name as paramater.

CESTER_TEST(test_case_name, test_instance,
    cester_assert_not_equal(NULL, ((void*)0));
)

CESTER_OPTIONS(
    CESTER_TEST_SHOULD_FAIL(test_case_name);
)

CESTER_TEST_SHOULD_BE_TERMINATED¶

Change the expected test case result. If the test case is terminated by user or another program then it passes ortherwise it fails. It accept the test case name as paramater.

CESTER_TEST(test_case_name, test_instance,
    while (1) {

    }
)

CESTER_OPTIONS(
    CESTER_TEST_SHOULD_BE_TERMINATED(test_case_name);
)

CESTER_TEST_SHOULD_LEAK_MEMORY¶

Change the expected test case result. If the test case does not leak any memory then the test case is marked as failure. It accept the test case name as paramater.

CESTER_TEST(test_case_name, test_instance,
    char* str = (char*) malloc(sizeof(char) * 12);
)

CESTER_OPTIONS(
    CESTER_TEST_SHOULD_LEAK_MEMORY(test_case_name);
)

Note

This macro is not available if the macro CESTER_NO_MEM_TEST is defined

CESTER_TEST_SHOULD_NOT_RELEASE_STREAM¶

Change the expected test case result. If the test case does not have any unreleased stream or no stream was captured the test case is marked as failure. It accept the test case name as paramater.

CESTER_TEST(test_stream_capture, test_instance,
    CESTER_CAPTURE_STREAM(stdout);
)

CESTER_OPTIONS(
    CESTER_TEST_SHOULD_NOT_RELEASE_STREAM(test_case_name);
)

Note

This macro is not available if the macro CESTER_NO_MEM_TEST is defined

#define CESTER_NO_MOCK¶

Define the macro CESTER_NO_MOCK to prevent mocking functions in the test. Even if mocked function are defined. This is not a predefined macro it has to be defined in the test source before including cester.h.

CESTER_MOCK_SIMPLE_FUNCTION¶

Mock a function that simply return a value. The macro accepts three parameters, the function identifier and parameters, the return type and the value to return when the function is invoked. For example mocking a function that return an integer:

int multiply_by() {
    return 2;
}

To function above returns 2, the macro CESTER_MOCK_SIMPLE_FUNCTION can mock this function to return 5 instead of two:

CESTER_MOCK_SIMPLE_FUNCTION(multiply_by(void), int, 5)

The macro above expands to the following code

//...
__attribute__((weak)) int multiply_by(); int __real_multiply_by();
//...
int __wrap_multiply_by() { return 5; }

CESTER_MOCK_FUNCTION¶

This macro is similar to the CESTER_MOCK_SIMPLE_FUNCTION macro but instead of return a single value it accepts function body as the third argument. It accepts three parameters, the first is the function name and parameters, the second is the return type and the thrid is the function body. For example the function below does not return the correct power of value of an integer:

int power_of(int* num1, int num2) {
    return *num1 * num2;
}

We then mock the function in the snippet below to properly calculate the power of an integer:

CESTER_MOCK_FUNCTION(power_of(int* num1, int num2), int,
    int return_val = *num1;
    while (num2-->1) {
        return_val *= *num1;
    }
    return return_val;
)

The macro above expands to the following code

//...
__attribute__((weak)) int power_of(int* num1, int num2); int __real_power_of(int* num1, int num2);
//...
int __wrap_power_of(int* num1, int num2) {
    int return_val = *num1;
    while (num2-->1) {
        return_val *= *num1;
    }
    return return_val;
}

CESTER_CAPTURE_STREAM¶

Use this macro to prepare a file stream to be captured by libcester, if a stream is not captured all assertion will fail for that stream. This simply make the stream address to point to another stream that is accessible and can be freely modified by cester.

CESTER_TEST(test_stream_capture, test_instance,
    CESTER_CAPTURE_STREAM(stdout);
    //...
    CESTER_RELEASE_STREAM(stdout);
)

If the stream that the output is written into (stdout by default) is captured if it not released at the end of the test case it will be forcefully released to libcester can continue writing the to the stream to see the test results.

Note