1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
|
Getting started
===============
Adding tests
------------
Adding tests is done using the ``Test`` macro:
.. doxygendefine:: Test
Example:
.. code-block:: c
#include <criterion/criterion.h>
Test(suite_name, test_name) {
// test contents
}
``suite_name`` and ``test_name`` are the identifiers of the test suite and
the test, respectively. These identifiers must follow the language
identifier format.
Tests are automatically sorted by suite, then by name using the alphabetical
order.
Asserting things
----------------
Assertions come in two kinds:
* ``cr_assert*`` are assertions that are fatal to the current test if failed;
in other words, if the condition evaluates to ``false``, the test is
marked as a failure and the execution of the function is aborted.
* ``cr_expect*`` are, in the other hand, assertions that are not fatal to the
test. Execution will continue even if the condition evaluates to
``false``, but the test will be marked as a failure.
``cr_assert()`` and ``cr_expect()`` are the most simple kinds of assertions
criterion has to offer. They both take a mandatory condition as a first
parameter, and an optional failure message:
.. code-block:: c
#include <string.h>
#include <criterion/criterion.h>
Test(sample, test) {
cr_expect(strlen("Test") == 4, "Expected \"Test\" to have a length of 4.");
cr_expect(strlen("Hello") == 4, "This will always fail, why did I add this?");
cr_assert(strlen("") == 0);
}
On top of those, more assertions are available for common operations. See
:ref:`assertions-ref` for a complete list.
Configuring tests
-----------------
Tests may receive optional configuration parameters to alter their behaviour
or provide additional metadata.
Fixtures
~~~~~~~~
Tests that need some setup and teardown can register functions that will
run before and after the test function:
.. code-block:: c
#include <stdio.h>
#include <criterion/criterion.h>
void setup(void) {
puts("Runs before the test");
}
void teardown(void) {
puts("Runs after the test");
}
Test(suite_name, test_name, .init = setup, .fini = teardown) {
// test contents
}
If a setup crashes, you will get a warning message, and the test will be aborted
and marked as a failure.
If a teardown crashes, you will get a warning message, and the test will keep
its result.
Testing signals
~~~~~~~~~~~~~~~
If a test receives a signal, it will by default be marked as a failure.
You can, however, expect a test to only pass if a special kind of signal
is received:
.. code-block:: c
#include <stddef.h>
#include <signal.h>
#include <criterion/criterion.h>
// This test will fail
Test(sample, failing) {
int *ptr = NULL;
*ptr = 42;
}
// This test will pass
Test(sample, passing, .signal = SIGSEGV) {
int *ptr = NULL;
*ptr = 42;
}
This feature will also work (to some extent) on Windows for the
following signals on some exceptions:
======== =====================================================================
Signal Triggered by
======== =====================================================================
SIGSEGV STATUS_ACCESS_VIOLATION, STATUS_DATATYPE_MISALIGNMENT,
STATUS_ARRAY_BOUNDS_EXCEEDED, STATUS_GUARD_PAGE_VIOLATION,
STATUS_IN_PAGE_ERROR, STATUS_NO_MEMORY, STATUS_INVALID_DISPOSITION,
STATUS_STACK_OVERFLOW
-------- ---------------------------------------------------------------------
SIGILL STATUS_ILLEGAL_INSTRUCTION, STATUS_PRIVILEGED_INSTRUCTION,
STATUS_NONCONTINUABLE_EXCEPTION
-------- ---------------------------------------------------------------------
SIGINT STATUS_CONTROL_C_EXIT
-------- ---------------------------------------------------------------------
SIGFPE STATUS_FLOAT_DENORMAL_OPERAND, STATUS_FLOAT_DIVIDE_BY_ZERO,
STATUS_FLOAT_INEXACT_RESULT, STATUS_FLOAT_INVALID_OPERATION,
STATUS_FLOAT_OVERFLOW, STATUS_FLOAT_STACK_CHECK,
STATUS_FLOAT_UNDERFLOW, STATUS_INTEGER_DIVIDE_BY_ZERO,
STATUS_INTEGER_OVERFLOW
-------- ---------------------------------------------------------------------
SIGALRM STATUS_TIMEOUT
======== =====================================================================
See the `windows exception reference`_ for more details on each exception.
.. _windows exception reference: https://msdn.microsoft.com/en-us/library/windows/desktop/ms679356(v=vs.85).aspx
.. _test-config-ref:
Configuration reference
~~~~~~~~~~~~~~~~~~~~~~~
Here is an exhaustive list of all possible configuration parameters you can
pass:
.. doxygenstruct:: criterion_test_extra_data
:members:
Setting up suite-wise configuration
-----------------------------------
Tests under the same suite can have a suite-wise configuration -- this is done
using the ``TestSuite`` macro:
.. doxygendefine:: TestSuite
Example:
.. code-block:: c
#include <criterion/criterion.h>
TestSuite(suite_name, [params...]);
Test(suite_name, test_1) {
}
Test(suite_name, test_2) {
}
Configuration parameters are the same as above, but applied to the suite itself.
Suite fixtures are run *along with* test fixtures.
|