**µ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()`.
----