Loading...
Searching...
No Matches
▶️ Running Tests
📚 The CMocka API

Execute test suites with setup and teardown functions. More...

## Data Structures

struct | UnitTest
struct | GroupTest
struct | CMUnitTest

## Macros

#define | unit_test(f)
#define | unit_test_setup(test, setup)
#define | unit_test_teardown(test, teardown)
#define | group_test_setup(setup)
#define | group_test_teardown(teardown)
#define | unit_test_setup_teardown(test, setup, teardown)
#define | cmocka_unit_test(f)
#define | cmocka_unit_test_setup(f, setup)
#define | cmocka_unit_test_teardown(f, teardown)
#define | cmocka_unit_test_setup_teardown(f, setup, teardown)
#define | cmocka_unit_test_prestate(f, state)
#define | cmocka_unit_test_prestate_setup_teardown(f, setup, teardown, state)

## Typedefs

typedef void(* | UnitTestFunction) (void **state)
typedef enum UnitTestFunctionType | UnitTestFunctionType
typedef struct UnitTest | UnitTest
typedef struct GroupTest | GroupTest
typedef void(* | CMUnitTestFunction) (void **state)
typedef int(* | CMFixtureFunction) (void **state)

## Enumerations

enum | UnitTestFunctionType { UNIT_TEST_FUNCTION_TYPE_TEST = 0 , UNIT_TEST_FUNCTION_TYPE_SETUP , UNIT_TEST_FUNCTION_TYPE_TEARDOWN , UNIT_TEST_FUNCTION_TYPE_GROUP_SETUP , UNIT_TEST_FUNCTION_TYPE_GROUP_TEARDOWN }

## Functions

void | fail (void)
| Forces the test to fail immediately and quit.
void | skip (void)
| Forces the test to not be executed, but marked as skipped.
void | stop (void)
| Forces the test to be stopped immediately.
void | fail_msg (const char *msg,...)
| Forces the test to fail immediately and quit, printing the reason.
int | cmocka_run_group_tests (const struct CMUnitTest group_tests[], CMFixtureFunction group_setup, CMFixtureFunction group_teardown)
| Run tests specified by an array of CMUnitTest structures.
int | cmocka_run_group_tests_name (const char *group_name, const struct CMUnitTest group_tests[], CMFixtureFunction group_setup, CMFixtureFunction group_teardown)
| Run tests specified by an array of CMUnitTest structures and specify a name.

## Detailed Description

Execute test suites with setup and teardown functions.

Test execution framework and test runners.

This module provides the infrastructure for defining, organizing, and running tests, including support for setup/teardown functions (fixtures), test grouping, and multiple test runner macros.

The following example illustrates how to define and run tests with CMocka.

void Test0(void **state);
void Test1(void **state);
int main(void)
{
const struct CMUnitTest tests[] = {
cmocka_unit_test(Test0),
cmocka_unit_test(Test1),
};
return cmocka_run_group_tests(tests, NULL, NULL);
}
cmocka_unit_test
#define cmocka_unit_test(f)
Definition cmocka.h:5928
cmocka_run_group_tests
int cmocka_run_group_tests(const struct CMUnitTest group_tests[], CMFixtureFunction group_setup, CMFixtureFunction group_teardown)
Run tests specified by an array of CMUnitTest structures.
CMUnitTest
Definition cmocka.h:6481

## Macro Definition Documentation

## cmocka_unit_test

#define cmocka_unit_test | ( |  | f | ) |

Value:
{ #f, f, NULL, NULL, NULL }

Initializes a CMUnitTest structure.

## cmocka_unit_test_prestate

#define cmocka_unit_test_prestate | ( |  | f,
|  |  | state )

Value:
{ #f, f, NULL, NULL, state }

Initialize a CMUnitTest structure with given initial state. It will be passed to test function as an argument later. It can be used when test state does not need special initialization or was initialized already.

Note
  If the group setup function initialized the state already, it won't be overridden by the initial state defined here.

## cmocka_unit_test_prestate_setup_teardown

#define cmocka_unit_test_prestate_setup_teardown | ( |  | f,
|  |  | setup,
|  |  | teardown,
|  |  | state )

Value:
{ #f, f, setup, teardown, state }

Initialize a CMUnitTest structure with given initial state, setup and teardown function. Any of these values can be NULL. Initial state is passed later to setup function, or directly to test if none was given.

Note
  If the group setup function initialized the state already, it won't be overridden by the initial state defined here.

## cmocka_unit_test_setup

#define cmocka_unit_test_setup | ( |  | f,
|  |  | setup )

Value:
{ #f, f, setup, NULL, NULL }

Initializes a CMUnitTest structure with a setup function.

## cmocka_unit_test_setup_teardown

#define cmocka_unit_test_setup_teardown | ( |  | f,
|  |  | setup,
|  |  | teardown )

Value:
{ #f, f, setup, teardown, NULL }

Initialize an array of CMUnitTest structures with a setup function for a test and a teardown function. Either setup or teardown can be NULL.

## cmocka_unit_test_teardown

#define cmocka_unit_test_teardown | ( |  | f,
|  |  | teardown )

Value:
{ #f, f, NULL, teardown, NULL }

Initializes a CMUnitTest structure with a teardown function.

## group_test_setup

#define group_test_setup | ( |  | setup | ) |

Value:
(CMOCKA_DEPRECATION_WARNING( \
"group_test_setup: use cmocka_run_group_tests instead")(UnitTest){ \
"group_" #setup, setup, UNIT_TEST_FUNCTION_TYPE_GROUP_SETUP})
UnitTest
Definition cmocka.h:6448

Initializes a UnitTest structure for a group setup function.

Deprecated
  This function was deprecated in favor of cmocka_run_group_tests

## group_test_teardown

#define group_test_teardown | ( |  | teardown | ) |

Value:
(CMOCKA_DEPRECATION_WARNING( \
"group_test_teardown: use cmocka_run_group_tests instead")(UnitTest){ \
"group_" #teardown, teardown, UNIT_TEST_FUNCTION_TYPE_GROUP_TEARDOWN})

Initializes a UnitTest structure for a group teardown function.

Deprecated
  This function was deprecated in favor of cmocka_run_group_tests

## unit_test

#define unit_test | ( |  | f | ) |

Value:
(CMOCKA_DEPRECATION_WARNING("unit_test: use cmocka_unit_test instead")( \
UnitTest){#f, f, UNIT_TEST_FUNCTION_TYPE_TEST})

Initializes a UnitTest structure.

Deprecated
  This function was deprecated in favor of cmocka_unit_test

## unit_test_setup

#define unit_test_setup | ( |  | test,
|  |  | setup )

Value:
CMOCKA_DEPRECATION_WARNING( \
"unit_test_setup: use cmocka_unit_test_setup instead") \
_unit_test_setup(test, setup), unit_test(test), \
_unit_test_teardown(test, _unit_test_dummy)
unit_test
#define unit_test(f)
Definition cmocka.h:5862

Initializes a UnitTest structure with a setup function.

Deprecated
  This function was deprecated in favor of cmocka_unit_test_setup

## unit_test_setup_teardown

#define unit_test_setup_teardown | ( |  | test,
|  |  | setup,
|  |  | teardown )

Value:
CMOCKA_DEPRECATION_WARNING("unit_test_setup_teardown: use " \
"cmocka_unit_test_setup_teardown instead") \
_unit_test_setup(test, setup), unit_test(test), \
_unit_test_teardown(test, teardown)

Initialize an array of UnitTest structures with a setup function for a test and a teardown function. Either setup or teardown can be NULL.

Deprecated
  This function was deprecated in favor of cmocka_unit_test_setup_teardown

## unit_test_teardown

#define unit_test_teardown | ( |  | test,
|  |  | teardown )

Value:
CMOCKA_DEPRECATION_WARNING( \
"unit_test_teardown: use cmocka_unit_test_teardown instead") \
_unit_test_setup(test, _unit_test_dummy), unit_test(test), \
_unit_test_teardown(test, teardown)

Initializes a UnitTest structure with a teardown function.

Deprecated
  This function was deprecated in favor of cmocka_unit_test_teardown

## Typedef Documentation

## CMFixtureFunction

typedef int(* CMFixtureFunction) (void **state)

Function prototype for setup and teardown functions.

## CMUnitTestFunction

typedef void(* CMUnitTestFunction) (void **state)

Function prototype for test functions.

## UnitTest

typedef struct UnitTest UnitTest

Stores a unit test function with its name and type. NOTE: Every setup function must be paired with a teardown function. It's possible to specify NULL function pointers.

## UnitTestFunction

typedef void(* UnitTestFunction) (void **state)

Function prototype for setup, test and teardown functions.

## UnitTestFunctionType

typedef enum UnitTestFunctionType UnitTestFunctionType

Type of the unit test function.

## Enumeration Type Documentation

## UnitTestFunctionType

enum UnitTestFunctionType

Type of the unit test function.

## Function Documentation

## cmocka_run_group_tests()

int cmocka_run_group_tests | ( | const struct CMUnitTest | group_tests[],
|  | CMFixtureFunction | group_setup,
|  | CMFixtureFunction | group_teardown )

Run tests specified by an array of CMUnitTest structures.

Parameters

  [in] | group_tests[] | The array of unit tests to execute.
  [in] | group_setup | The setup function which should be called before all unit tests are executed.
  [in] | group_teardown | The teardown function to be called after all tests have finished.

Returns
  0 on success, or the number of failed tests.

static int setup(void **state) {
int *answer = malloc(sizeof(int));
if (answer == NULL) {
return -1;
}
*answer = 42;
*state = answer;
return 0;
}
static int teardown(void **state) {
free(*state);
return 0;
}
static void null_test_success(void **state) {
(void) state;
}
static void int_test_success(void **state) {
int *answer = *state;
assert_int_equal(*answer, 42);
}
int main(void) {
const struct CMUnitTest tests[] = {
cmocka_unit_test(null_test_success),
cmocka_unit_test_setup_teardown(int_test_success, setup, teardown),
};
return cmocka_run_group_tests(tests, NULL, NULL);
}
assert_int_equal
void assert_int_equal(intmax_t a, intmax_t b)
Assert that the two given integers are equal.
cmocka_unit_test_setup_teardown
#define cmocka_unit_test_setup_teardown(f, setup, teardown)
Definition cmocka.h:5940

See also
  cmocka_unit_test
  cmocka_unit_test_setup
  cmocka_unit_test_teardown
  cmocka_unit_test_setup_teardown

## cmocka_run_group_tests_name()

int cmocka_run_group_tests_name | ( | const char * | group_name,
|  | const struct CMUnitTest | group_tests[],
|  | CMFixtureFunction | group_setup,
|  | CMFixtureFunction | group_teardown )

Run tests specified by an array of CMUnitTest structures and specify a name.

Parameters

  [in] | group_name | The name of the group test.
  [in] | group_tests[] | The array of unit tests to execute.
  [in] | group_setup | The setup function which should be called before all unit tests are executed.
  [in] | group_teardown | The teardown function to be called after all tests have finished.

Returns
  0 on success, or the number of failed tests.

static int setup(void **state) {
int *answer = malloc(sizeof(int));
if (answer == NULL) {
return -1;
}
*answer = 42;
*state = answer;
return 0;
}
static int teardown(void **state) {
free(*state);
return 0;
}
static void null_test_success(void **state) {
(void) state;
}
static void int_test_success(void **state) {
int *answer = *state;
assert_int_equal(*answer, 42);
}
int main(void) {
const struct CMUnitTest tests[] = {
cmocka_unit_test(null_test_success),
cmocka_unit_test_setup_teardown(int_test_success, setup, teardown),
};
return cmocka_run_group_tests_name("success_test", tests, NULL, NULL);
}
cmocka_run_group_tests_name
int cmocka_run_group_tests_name(const char *group_name, const struct CMUnitTest group_tests[], CMFixtureFunction group_setup, CMFixtureFunction group_teardown)
Run tests specified by an array of CMUnitTest structures and specify a name.

See also
  cmocka_unit_test
  cmocka_unit_test_setup
  cmocka_unit_test_teardown
  cmocka_unit_test_setup_teardown

## fail_msg()

void fail_msg | ( | const char * | msg,
|  |  | ... )

Forces the test to fail immediately and quit, printing the reason.

fail_msg("This is some error message for test");
fail_msg
void fail_msg(const char *msg,...)
Forces the test to fail immediately and quit, printing the reason.

or

char *error_msg = "This is some error message for test";
fail_msg("%s", error_msg);

## stop()

void stop | ( | void |  | ) |

Forces the test to be stopped immediately.

Call stop() to stop a running test. The test is considered passed if there are no leftover values, otherwise a test failure is signaled. Calling stop() is especially useful in mocked functions that do not return, e.g reset the CPU.