**µTest — A small C testing library** * [Main](./mutest.md.html) ## Matchers _Matchers_ are functions passed to `mutest_expect()`. A matcher function takes a pointer to the expectation object, and a pointer to a value wrapper which containes the expected value. If the value contained in the expectation object matches the expected value, the the matcher is satisfied. If all matcher functions passed to `mutest_expect()` are satisfied, the expectation is satisfied. For instance, the following expectation: ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ const char *str = "hello, world"; mutest_expect ("the string to match a greeting", mutest_string_value (str), mutest_to_be, "hello, world", NULL); ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Contains a single matcher, `mutest_to_be()`. The `mutest_to_be()` matcher is satisfied if the value in `str` and wrapped by `mutest_string_value()` matches the function parameter, following `mutest_to_be()` in the expectation. In the following example: ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ const char *str = "hello, world"; mutest_expect ("the string to contain all parts of the greeting", mutest_string_value (str), mutest_to_start_with_string, "hello", mutest_to_contain_string, ",", mutest_to_end_with_string, "world", NULL); ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The expectation is composed of three separate matchers: - `mutest_to_start_with_string()`, which checks that the string value starts with the matcher parameter - `mutest_to_contain_string()`, which checks that the string value contains the matcher parameter - `mutest_to_end_with_string()`, which checks that the string value ends with the matcher parameter The expectation, in the case above, is only satisfied if all three matcher functions are satisfied. ### Includes ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ #include ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ### Functions ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ bool mutest_not (mutest_expect_t *e, mutest_expect_res_t *check); ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Negates the condition of the following matcher function. For instance: ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ mutest_expect ("a to not be true", mutest_bool_value (false), mutest_not, mutest_to_be, true, NULL); ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ e : the expectation object check : the matcher argument return value : `true` if the matcher is satisfied, and `false` otherwise ---- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ bool mutest_to_be (mutest_expect_t *e, mutest_expect_res_t *check); ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Matches the value in `e` to the value in `check` exactly. e : the expectation object check : the matcher argument return value : `true` if the matcher is satisfied, and `false` otherwise ---- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ bool mutest_to_be_close_to (mutest_expect_t *e, mutest_expect_res_t *check); ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Checks whether the value in `e` is within a given tolerance of the value wrapped by `check`. e : the expectation object check : the matcher argument return value : `true` if the matcher is satisfied, and `false` otherwise ---- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ bool mutest_to_be_nan (mutest_expect_t *e, mutest_expect_res_t *check); ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Checks whether the floating point value in `e` is NaN (Not a Number). e : the expectation object check : the matcher argument return value : `true` if the matcher is satisfied, and `false` otherwise ---- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ bool mutest_to_be_positive_infinity (mutest_expect_t *e, mutest_expect_res_t *check); ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Checks whether the floating point value in `e` is a positive infinity. e : the expectation object check : the matcher argument return value : `true` if the matcher is satisfied, and `false` otherwise ---- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ bool mutest_to_be_negative_infinity (mutest_expect_t *e, mutest_expect_res_t *check); ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Checks whether the floating point value in `e` is a negative infinity. e : the expectation object check : the matcher argument return value : `true` if the matcher is satisfied, and `false` otherwise ---- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ bool mutest_to_be_greater_than (mutest_expect_t *e, mutest_expect_res_t *check); ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Checks whether the numeric value in `e` is greater than the value in `check`. e : the expectation object check : the matcher argument return value : `true` if the matcher is satisfied, and `false` otherwise ---- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ bool mutest_to_be_greater_than_or_equal (mutest_expect_t *e, mutest_expect_res_t *check); ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Checks whether the numeric value in `e` is greater than, or equal to the value in `check`. e : the expectation object check : the matcher argument return value : `true` if the matcher is satisfied, and `false` otherwise ---- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ bool mutest_to_be_less_than_or_equal (mutest_expect_t *e, mutest_expect_res_t *check); ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Checks whether the numeric value in `e` is less than, or equal to the value in `check`. e : the expectation object check : the matcher argument return value : `true` if the matcher is satisfied, and `false` otherwise ---- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ bool mutest_to_be_less_than (mutest_expect_t *e, mutest_expect_res_t *check); ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Checks whether the numeric value in `e` is less than the value in `check`. e : the expectation object check : the matcher argument return value : `true` if the matcher is satisfied, and `false` otherwise ---- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ bool mutest_to_be_in_range (mutest_expect_t *e, mutest_expect_res_t *check); ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Checks if the numeric value in `e` is inside the range in `check`. e : the expectation object check : the matcher argument return value : `true` if the matcher is satisfied, and `false` otherwise ---- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ bool mutest_to_contain (mutest_expect_t *e, mutest_expect_res_t *check); ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Checks if the numeric range, or string, in `e` contains the numeric value, or string, in `check`. e : the expectation object check : the matcher argument return value : `true` if the matcher is satisfied, and `false` otherwise ---- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ bool mutest_to_start_with_string (mutest_expect_t *e, mutest_expect_res_t *check); ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Checks that the string in `e` starts with the string in `check`. e : the expectation object check : the matcher argument return value : `true` if the matcher is satisfied, and `false` otherwise ---- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ bool mutest_to_end_with_string (mutest_expect_t *e, mutest_expect_res_t *check); ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Checks that the string in `e` ends with the string in `check`. e : the expectation object check : the matcher argument return value : `true` if the matcher is satisfied, and `false` otherwise ---- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ bool mutest_to_be_true (mutest_expect_t *e, mutest_expect_res_t *check); ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Checks that the boolean value in `e` is true. e : the expectation object check : the matcher argument return value : `true` if the matcher is satisfied, and `false` otherwise ---- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ bool mutest_to_be_false (mutest_expect_t *e, mutest_expect_res_t *check); ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Checks that the boolean value in `e` is false. e : the expectation object check : the matcher argument return value : `true` if the matcher is satisfied, and `false` otherwise ---- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ bool mutest_to_be_null (mutest_expect_t *e, mutest_expect_res_t *check); ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Checks that the pointer value in `e` is `NULL`. e : the expectation object check : the matcher argument return value : `true` if the matcher is satisfied, and `false` otherwise ---- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ mutest_expect_res_t * mutest_expect_value (mutest_expect_t *expect); ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Retrieves the pointer to the value wrapper passed to `mutest_expect()` from the `mutest_expect_t` object. This function is typically used when implementing custom matchers. For instance: ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ static bool test_my_object_is_equal (mutest_expect_t *e, mutest_expect_res_t *check) { mutest_expect_res_t *value = mutest_expect_value (e); MyObject *a = mutest_get_pointer (value); MyObject *b = mutest_get_pointer (check); // Simple equality if (a == b) return true; // my_object_deep_equal() is defined elsewhere as a deep // equality of two MyObject instances return my_object_deep_equal (a, b); } ... // Custom matchers must use the explicit value wrappers, // as µTest doesn't know how to collect the values mutest_expect ("the objects to be equal", mutest_pointer (foo), test_my_object_is_equal, mutest_pointer (bar), NULL); ... ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ### Types ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ typedef bool (* mutest_matcher_func_t) (mutest_expect_t *e, mutest_expect_res_t *check); ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ e : the expectation object check : the matcher argument return value : `true` if the matcher is satisfied, and `false` otherwise The prototype of a matcher function to pass to `mutest_expect()`. ----