Debian Codegraph @

storage/maria/libmarias3/docs/contributors/test_cases.rst

raw
1 Writing Test Cases
2 ==================
3
4 libMariaS3 uses DDM4's YATL library to create unit tests, this provides macros to test if the outcomes are as expected.
5
6 Adding a Test Case
7 ------------------
8
9 Test cases are basic C applications in the ``tests/`` directory. To add a test case to the suite. To add a test edit the ``include.am`` and add the following (replacing *mytest* with whatever the test is called):
10
11 .. code-block:: makefile
12
13 t_mytest_SOURCES= tests/mytest.c
14 t_mytest_LDADD= src/libmarias3.la
15 check_PROGRAMS+= t/mytest
16 noinst_PROGRAMS+= t/mytest
17
18
19 Using YATL
20 ----------
21
22 YATL is needed to make sure conditions within the test program are met. To include it in your test application, add the following:
23
24 .. code-block:: c
25
26 #include <yatl/lite.h>
27
28 A test skip can be added if certain conditions aren't met:
29
30 .. code-block:: c
31
32 SKIP_IF_(!is_connected, "Cannot connected to a database server")
33
34 There are many types of assert provided as can be seen in the next section, they can be used as follows:
35
36 .. code-block:: c
37
38 ASSERT_EQ_(3, column, "Column count unexpected)
39 ASSERT_FALSE_(false_condition, "False condition is not false")
40 ASSERT_STREQ_("test", some_data, "Unexpected data")
41
42 YATL Library
43 ------------
44
45 Parameter Definitions
46 ^^^^^^^^^^^^^^^^^^^^^
47
48 .. c:type:: __expression
49
50 An expression typically used in an ``if`` statement.
51
52 .. c:type:: __expected
53
54 An expected variable or expression
55
56 .. c:type:: __actual
57
58 The actual variable or expression
59
60 .. c:type:: __expected_str
61
62 The expected string
63
64 .. c:type:: __actual_str
65
66 The actual string to compare with
67
68 .. c:type:: __length
69
70 The length of a string for comparison
71
72 Function Definitions
73 ^^^^^^^^^^^^^^^^^^^^
74
75 .. c:macro:: SKIP_IF(__expression)
76
77 Skips the test if the expression is true
78
79 .. c:macro:: SKIP_IF_(__expression, ...)
80
81 Skips the test if the expression is true and uses a printf style format message
82
83 .. c:macro:: ASSERT_TRUE(__expression)
84
85 Make sure the expression is true, test will fail if it is false
86
87 .. c:macro:: ASSERT_FALSE(__expression)
88
89 Make sure the expression is false, test will fail if it is true
90
91 .. c:macro:: ASSERT_FALSE_(__expression, ...)
92
93 Make sure the expression is false and use a printf style format message to fail if it is true.
94
95 .. c:macro:: ASSERT_NULL_(__expression, ...)
96
97 Make sure the expression is :c:type:`NULL` and use a printf style format message to fail if it isn't.
98
99 .. c:macro:: ASSERT_NOT_NULL(__expression)
100
101 Make sure the expression is not :c:type:`NULL`, test will fail if it is :c:type:`NULL`.
102
103 .. c:macro:: ASSERT_NOT_NULL_(__expression, ...)
104
105 Make sure the expression is not :c:type:`NULL` and use a printf style format message to fail if it is.
106
107 .. c:macro:: ASSERT_TRUE_(__expression, ...)
108
109 Make sure the expression is ``true`` and use a printf style format message to fail if it is not.
110
111 .. c:macro:: ASSERT_EQ(__expected, __actual)
112
113 Make sure that one condition or variable matches another one.
114
115 .. note::
116 Not suitable for string matching
117
118 .. c:macro:: ASSERT_EQ_(__expected, __actual, ...)
119
120 Make sure that one condition or variable matches another one and use a printf style format message to fail if the do not match.
121
122 .. note::
123 Not suitable for string matching
124
125 .. c:macro:: ASSERT_NEQ(__expected, __actual)
126
127 Make sure that one condition or variable does not match another one.
128
129 .. note::
130 Not suitable for string matching
131
132 .. c:macro:: ASSERT_NEQ_(__expected, __actual, ...)
133
134 Make sure that one condition or variable does not match another one and use a printf style format message to fail if they do match.
135
136 .. note::
137 Not suitable for string matching
138
139 .. c:macro:: ASSERT_STREQ(__expected_str, __actual_str)
140
141 Compare one ``NUL`` terminated string with another one and fail if they do not match.
142
143 .. c:macro:: ASSERT_STREQ_(__expected_str, __actual_str, ...)
144
145 Compare one ``NUL`` terminated string with another one and use a printf style format message to fail if they do not match.
146
147 .. c:macro:: ASSERT_STREQL_(__expected_str, __actual_str, __length, ...)
148
149 Compare a string of :c:type:`__length` to another one and use a printf style format message to fail if they do not match.
150
151 .. note::
152 This is designed for use with non-NUL-terminated strings.
153
154 .. c:macro:: ASSERT_STRNE(__expected_str, __actual_str)
155
156 Compare one ``NUL`` terminated string with another one and fail if they match.
157
158 .. c:macro:: ASSERT_STRNE_(__expected_str, __actual_str, ...)
159
160 Compare one ``NUL`` terminated string with another one and use a printf style format message to fail if they match.
161
162