**µTest — A small C testing library** * [Main](./mutest.md.html) ## Matchers _Matchers_ are functions passed to [`mutest_expect()`](mutest-general.md.html#//functions/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()`](mutest-general.md.html#//functions/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()`](#/matchers/functions/mutest_to_be). The [`mutest_to_be()`](#//functions/mutest_to_be) matcher is satisfied if the value in `str` and wrapped by [`mutest_string_value()`](mutest-wrappers.md.html#/valuewrappers/functions/mutest_string_value) matches the function parameter, following [`mutest_to_be()`](#/matchers/functions/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, ",", mutest_to_end_with_string, "world", NULL); ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The expectation is composed of three separate matchers: - [`mutest_to_start_with_string()`](#/matchers/functions/mutest_to_start_with_string), which checks that the string value starts with the matcher parameter - [`mutest_to_contain()`](#/matchers/functions/mutest_to_contain), which checks that the string value contains the matcher parameter - [`mutest_to_end_with_string()`](#/matchers/functions/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. !!! Note Matcher functions provided by µTest can automatically collect the expected values from the variadic arguments list passed to [`mutest_expect()`](mutest-general.md.html#//functions/mutest_expect) without explicitly wrapping them with a `mutest_expect_res_t`. Custom matchers, on the other hand, require an explicit value wrapper. ### Includes ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ #include ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ### Functions #### `mutest_not` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ bool mutest_not (mutest_expect_t *e, mutest_expect_res_t *check); ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ A special matcher function that 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 ---- #### `mutest_to_be` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ bool mutest_to_be (mutest_expect_t *e, mutest_expect_res_t *check); ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Matches the value in `e` to the value in `check` exactly. This matcher collects a value that matches the type of the value passed to `mutest_expect()`. e : the expectation object check : the matcher argument return value : `true` if the matcher is satisfied, and `false` otherwise ---- #### `mutest_to_be_close_to` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 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`. This matcher collects two values: - the numeric value to be used in the comparison - the numeric value to be used as a tolerance e.g. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ mutest_expect ("angle to be close to π", mutest_float_value (angle), mutest_to_be_close_to, M_PI, 0.0001, NULL); ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ e : the expectation object check : the matcher argument return value : `true` if the matcher is satisfied, and `false` otherwise ---- #### `mutest_to_be_nan` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 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). This matcher collects the numeric value to be used in the comparison. e : the expectation object check : the matcher argument return value : `true` if the matcher is satisfied, and `false` otherwise ---- #### `mutest_to_be_positive_infinity` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 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. This matcher collects the numeric value to be used in the comparison. e : the expectation object check : the matcher argument return value : `true` if the matcher is satisfied, and `false` otherwise ---- #### `mutest_to_be_negative_infinity` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 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. This matcher collects the numeric value to be used in the comparison. e : the expectation object check : the matcher argument return value : `true` if the matcher is satisfied, and `false` otherwise ---- #### `mutest_to_be_greater_than` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 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`. This matcher collects the numeric value to be used in the comparison. e : the expectation object check : the matcher argument return value : `true` if the matcher is satisfied, and `false` otherwise ---- #### `mutest_to_be_greater_than_or_equal` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 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`. This matcher collects the numeric value to be used in the comparison. e : the expectation object check : the matcher argument return value : `true` if the matcher is satisfied, and `false` otherwise ---- #### `mutest_to_be_less_than_or_equal` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 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`. This matcher collects the numeric value to be used in the comparison. e : the expectation object check : the matcher argument return value : `true` if the matcher is satisfied, and `false` otherwise ---- #### `mutest_to_be_less_than` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 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`. This matcher collects the numeric value to be used in the comparison. e : the expectation object check : the matcher argument return value : `true` if the matcher is satisfied, and `false` otherwise ---- #### `mutest_to_be_in_range` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 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`. This matcher collects the numeric range as two values, e.g. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ mutest_expect ("number to be between 0 and 100", mutest_int_value (random_number), mutest_to_be_in_range, 0, 100, NULL); ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ e : the expectation object check : the matcher argument return value : `true` if the matcher is satisfied, and `false` otherwise ---- #### `mutest_to_contain` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 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`. This matcher collects the numeric or string value that should be contained in the numeric range or string value passed to `mutest_expect()`. e : the expectation object check : the matcher argument return value : `true` if the matcher is satisfied, and `false` otherwise ---- #### `mutest_to_start_with_string` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 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`. This matcher collects the expected string that should be at the beginning of the string value passed to `mutest_expect()`. e : the expectation object check : the matcher argument return value : `true` if the matcher is satisfied, and `false` otherwise ---- #### `mutest_to_end_with_string` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 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`. This matcher collects the expected string that should be at the end of the string value passed to `mutest_expect()`. e : the expectation object check : the matcher argument return value : `true` if the matcher is satisfied, and `false` otherwise ---- #### `mutest_to_be_true` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ bool mutest_to_be_true (mutest_expect_t *e, mutest_expect_res_t *check); ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Checks that the boolean value in `e` is true. This matcher does not collect any value. e : the expectation object check : the matcher argument return value : `true` if the matcher is satisfied, and `false` otherwise ---- #### `mutest_to_be_false` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ bool mutest_to_be_false (mutest_expect_t *e, mutest_expect_res_t *check); ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Checks that the boolean value in `e` is false. This matcher does not collect any value. e : the expectation object check : the matcher argument return value : `true` if the matcher is satisfied, and `false` otherwise ---- #### `mutest_to_be_null` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ bool mutest_to_be_null (mutest_expect_t *e, mutest_expect_res_t *check); ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Checks that the pointer value in `e` is `NULL`. This matcher does not collect any value. e : the expectation object check : the matcher argument return value : `true` if the matcher is satisfied, and `false` otherwise ---- #### `mutest_skip` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ bool mutest_skip (mutest_expect_t *e, mutest_expect_res_t *check); ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ A special matcher function that will cause the expectation to be marked as skipped. This matcher collects a string that contains a human readable reason for the expectation to be skipped. You should use this matcher as the only one in an expectation. e : the expectation object check : the matcher argument return value : `true` if the matcher is satisfied, and `false` otherwise ---- #### `mutest_expect_value` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 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()`. ----