1ATF-C++-API(3)           BSD Library Functions Manual           ATF-C++-API(3)
2

NAME

4     atf-c++-api, ATF_ADD_TEST_CASE, ATF_CHECK_ERRNO, ATF_FAIL,
5     ATF_INIT_TEST_CASES, ATF_PASS, ATF_REQUIRE, ATF_REQUIRE_EQ,
6     ATF_REQUIRE_ERRNO, ATF_REQUIRE_IN, ATF_REQUIRE_MATCH, ATF_REQUIRE_NOT_IN,
7     ATF_REQUIRE_THROW, ATF_REQUIRE_THROW_RE, ATF_SKIP, ATF_TEST_CASE,
8     ATF_TEST_CASE_BODY, ATF_TEST_CASE_CLEANUP, ATF_TEST_CASE_HEAD,
9     ATF_TEST_CASE_NAME, ATF_TEST_CASE_USE, ATF_TEST_CASE_WITH_CLEANUP,
10     ATF_TEST_CASE_WITHOUT_HEAD, atf::utils::cat_file,
11     atf::utils::compare_file, atf::utils::copy_file, atf::utils::create_file,
12     atf::utils::file_exists, atf::utils::fork, atf::utils::grep_collection,
13     atf::utils::grep_file, atf::utils::grep_string, atf::utils::redirect,
14     atf::utils::wait — C++ API to write ATF-based test programs
15

SYNOPSIS

17     #include <atf-c++.hpp>
18
19     ATF_ADD_TEST_CASE(tcs, name);
20
21     ATF_CHECK_ERRNO(exp_errno, bool_expression);
22
23     ATF_FAIL(reason);
24
25     ATF_INIT_TEST_CASES(tcs);
26
27     ATF_PASS();
28
29     ATF_REQUIRE(expression);
30
31     ATF_REQUIRE_EQ(expression_1, expression_2);
32
33     ATF_REQUIRE_ERRNO(exp_errno, bool_expression);
34
35     ATF_REQUIRE_IN(element, collection);
36
37     ATF_REQUIRE_MATCH(regexp, string_expression);
38
39     ATF_REQUIRE_NOT_IN(element, collection);
40
41     ATF_REQUIRE_THROW(expected_exception, statement);
42
43     ATF_REQUIRE_THROW_RE(expected_exception, regexp, statement);
44
45     ATF_SKIP(reason);
46
47     ATF_TEST_CASE(name);
48
49     ATF_TEST_CASE_BODY(name);
50
51     ATF_TEST_CASE_CLEANUP(name);
52
53     ATF_TEST_CASE_HEAD(name);
54
55     ATF_TEST_CASE_NAME(name);
56
57     ATF_TEST_CASE_USE(name);
58
59     ATF_TEST_CASE_WITH_CLEANUP(name);
60
61     ATF_TEST_CASE_WITHOUT_HEAD(name);
62
63     void
64     atf::utils::cat_file(const std::string& path, const std::string& prefix);
65
66     bool
67     atf::utils::compare_file(const std::string& path,
68         const std::string& contents);
69
70     void
71     atf::utils::copy_file(const std::string& source,
72         const std::string& destination);
73
74     void
75     atf::utils::create_file(const std::string& path,
76         const std::string& contents);
77
78     void
79     atf::utils::file_exists(const std::string& path);
80
81     pid_t
82     atf::utils::fork(void);
83
84     bool
85     atf::utils::grep_collection(const std::string& regexp,
86         const Collection& collection);
87
88     bool
89     atf::utils::grep_file(const std::string& regexp,
90         const std::string& path);
91
92     bool
93     atf::utils::grep_string(const std::string& regexp,
94         const std::string& path);
95
96     void
97     atf::utils::redirect(const int fd, const std::string& path);
98
99     void
100     atf::utils::wait(const pid_t pid, const int expected_exit_status,
101         const std::string& expected_stdout,
102         const std::string& expected_stderr);
103

DESCRIPTION

105     ATF provides a C++ programming interface to implement test programs.
106     C++-based test programs follow this template:
107
108           extern "C" {
109           ... C-specific includes go here ...
110           }
111
112           ... C++-specific includes go here ...
113
114           #include <atf-c++.hpp>
115
116           ATF_TEST_CASE(tc1);
117           ATF_TEST_CASE_HEAD(tc1)
118           {
119               ... first test case's header ...
120           }
121           ATF_TEST_CASE_BODY(tc1)
122           {
123               ... first test case's body ...
124           }
125
126           ATF_TEST_CASE_WITH_CLEANUP(tc2);
127           ATF_TEST_CASE_HEAD(tc2)
128           {
129               ... second test case's header ...
130           }
131           ATF_TEST_CASE_BODY(tc2)
132           {
133               ... second test case's body ...
134           }
135           ATF_TEST_CASE_CLEANUP(tc2)
136           {
137               ... second test case's cleanup ...
138           }
139
140           ATF_TEST_CASE(tc3);
141           ATF_TEST_CASE_BODY(tc3)
142           {
143               ... third test case's body ...
144           }
145
146           ... additional test cases ...
147
148           ATF_INIT_TEST_CASES(tcs)
149           {
150               ATF_ADD_TEST_CASE(tcs, tc1);
151               ATF_ADD_TEST_CASE(tcs, tc2);
152               ATF_ADD_TEST_CASE(tcs, tc3);
153               ... add additional test cases ...
154           }
155
156   Definition of test cases
157     Test cases have an identifier and are composed of three different parts:
158     the header, the body and an optional cleanup routine, all of which are
159     described in atf-test-case(4).  To define test cases, one can use the
160     ATF_TEST_CASE(), ATF_TEST_CASE_WITH_CLEANUP() or the
161     ATF_TEST_CASE_WITHOUT_HEAD() macros, which take a single parameter speci‐
162     fiying the test case's name.  ATF_TEST_CASE(), requires to define a head
163     and a body for the test case, ATF_TEST_CASE_WITH_CLEANUP() requires to
164     define a head, a body and a cleanup for the test case and
165     ATF_TEST_CASE_WITHOUT_HEAD() requires only a body for the test case.  It
166     is important to note that these do not set the test case up for execution
167     when the program is run.  In order to do so, a later registration is
168     needed through the ATF_ADD_TEST_CASE() macro detailed in Program
169     initialization.
170
171     Later on, one must define the three parts of the body by means of three
172     functions.  Their headers are given by the ATF_TEST_CASE_HEAD(),
173     ATF_TEST_CASE_BODY() and ATF_TEST_CASE_CLEANUP() macros, all of which
174     take the test case's name.  Following each of these, a block of code is
175     expected, surrounded by the opening and closing brackets.
176
177     Additionally, the ATF_TEST_CASE_NAME() macro can be used to obtain the
178     name of the class corresponding to a particular test case, as the name is
179     internally manged by the library to prevent clashes with other user iden‐
180     tifiers.  Similarly, the ATF_TEST_CASE_USE() macro can be executed on a
181     particular test case to mark it as "used" and thus prevent compiler warn‐
182     ings regarding unused symbols.  Note that you should never have to use
183     these macros during regular operation.
184
185   Program initialization
186     The library provides a way to easily define the test program's main()
187     function.  You should never define one on your own, but rely on the
188     library to do it for you.  This is done by using the
189     ATF_INIT_TEST_CASES() macro, which is passed the name of the list that
190     will hold the test cases.  This name can be whatever you want as long as
191     it is a valid variable value.
192
193     After the macro, you are supposed to provide the body of a function,
194     which should only use the ATF_ADD_TEST_CASE() macro to register the test
195     cases the test program will execute.  The first parameter of this macro
196     matches the name you provided in the former call.
197
198   Header definitions
199     The test case's header can define the meta-data by using the set_md_var()
200     method, which takes two parameters: the first one specifies the meta-data
201     variable to be set and the second one specifies its value.  Both of them
202     are strings.
203
204   Configuration variables
205     The test case has read-only access to the current configuration variables
206     by means of the bool has_config_var() and the std::string
207     get_config_var() methods, which can be called in any of the three parts
208     of a test case.
209
210   Access to the source directory
211     It is possible to get the path to the test case's source directory from
212     any of its three components by querying the ‘srcdir’ configuration vari‐
213     able.
214
215   Requiring programs
216     Aside from the require.progs meta-data variable available in the header
217     only, one can also check for additional programs in the test case's body
218     by using the require_prog() function, which takes the base name or full
219     path of a single binary.  Relative paths are forbidden.  If it is not
220     found, the test case will be automatically skipped.
221
222   Test case finalization
223     The test case finalizes either when the body reaches its end, at which
224     point the test is assumed to have passed, or at any explicit call to
225     ATF_PASS(), ATF_FAIL() or ATF_SKIP().  These three macros terminate the
226     execution of the test case immediately.  The cleanup routine will be pro‐
227     cessed afterwards in a completely automated way, regardless of the test
228     case's termination reason.
229
230     ATF_PASS() does not take any parameters.  ATF_FAIL() and ATF_SKIP() take
231     a single string that describes why the test case failed or was skipped,
232     respectively.  It is very important to provide a clear error message in
233     both cases so that the user can quickly know why the test did not pass.
234
235   Expectations
236     Everything explained in the previous section changes when the test case
237     expectations are redefined by the programmer.
238
239     Each test case has an internal state called ‘expect’ that describes what
240     the test case expectations are at any point in time.  The value of this
241     property can change during execution by any of:
242
243     expect_death(reason)
244             Expects the test case to exit prematurely regardless of the
245             nature of the exit.
246
247     expect_exit(exitcode, reason)
248             Expects the test case to exit cleanly.  If exitcode is not ‘-1’,
249             atf-run(1) will validate that the exit code of the test case
250             matches the one provided in this call.  Otherwise, the exact
251             value will be ignored.
252
253     expect_fail(reason)
254             Any failure (be it fatal or non-fatal) raised in this mode is
255             recorded.  However, such failures do not report the test case as
256             failed; instead, the test case finalizes cleanly and is reported
257             as ‘expected failure’; this report includes the provided reason
258             as part of it.  If no error is raised while running in this mode,
259             then the test case is reported as ‘failed’.
260
261             This mode is useful to reproduce actual known bugs in tests.
262             Whenever the developer fixes the bug later on, the test case will
263             start reporting a failure, signaling the developer that the test
264             case must be adjusted to the new conditions.  In this situation,
265             it is useful, for example, to set reason as the bug number for
266             tracking purposes.
267
268     expect_pass()
269             This is the normal mode of execution.  In this mode, any failure
270             is reported as such to the user and the test case is marked as
271             ‘failed’.
272
273     expect_race(reason)
274             Any failure or timeout during the execution of the test case will
275             be considered as if a race condition has been triggered and
276             reported as such.  If no problems arise, the test will continue
277             execution as usual.
278
279     expect_signal(signo, reason)
280             Expects the test case to terminate due to the reception of a sig‐
281             nal.  If signo is not ‘-1’, atf-run(1) will validate that the
282             signal that terminated the test case matches the one provided in
283             this call.  Otherwise, the exact value will be ignored.
284
285     expect_timeout(reason)
286             Expects the test case to execute for longer than its timeout.
287
288   Helper macros for common checks
289     The library provides several macros that are very handy in multiple situ‐
290     ations.  These basically check some condition after executing a given
291     statement or processing a given expression and, if the condition is not
292     met, they automatically call ATF_FAIL() with an appropriate error mes‐
293     sage.
294
295     ATF_REQUIRE() takes an expression and raises a failure if it evaluates to
296     false.
297
298     ATF_REQUIRE_EQ() takes two expressions and raises a failure if the two do
299     not evaluate to the same exact value.
300
301     ATF_REQUIRE_IN() takes an element and a collection and validates that the
302     element is present in the collection.
303
304     ATF_REQUIRE_MATCH() takes a regular expression and a string and raises a
305     failure if the regular expression does not match the string.
306
307     ATF_REQUIRE_NOT_IN() takes an element and a collection and validates that
308     the element is not present in the collection.
309
310     ATF_REQUIRE_THROW() takes the name of an exception and a statement and
311     raises a failure if the statement does not throw the specified exception.
312     ATF_REQUIRE_THROW_RE() takes the name of an exception, a regular expre‐
313     sion and a statement and raises a failure if the statement does not throw
314     the specified exception and if the message of the exception does not
315     match the regular expression.
316
317     ATF_CHECK_ERRNO() and ATF_REQUIRE_ERRNO() take, first, the error code
318     that the check is expecting to find in the errno variable and, second, a
319     boolean expression that, if evaluates to true, means that a call failed
320     and errno has to be checked against the first value.
321
322   Utility functions
323     The following functions are provided as part of the atf-c++-api API to
324     simplify the creation of a variety of tests.  In particular, these are
325     useful to write tests for command-line interfaces.
326
327     void atf::utils::cat_file(const std::string& path,
328     const std::string& prefix)
329
330           Prints the contents of path to the standard output, prefixing every
331           line with the string in prefix.
332
333     bool atf::utils::compare_file(const std::string& path,
334     const std::string& contents)
335
336           Returns true if the given path matches exactly the expected inlined
337           contents.
338
339     void atf::utils::copy_file(const std::string& source,
340     const std::string& destination)
341
342           Copies the file source to destination.  The permissions of the file
343           are preserved during the code.
344
345     void atf::utils::create_file(const std::string& path,
346     const std::string& contents)
347
348           Creates file with the text given in contents.
349
350     void atf::utils::file_exists(const std::string& path)
351
352           Checks if path exists.
353
354     pid_t atf::utils::fork(void)
355
356           Forks a process and redirects the standard output and standard
357           error of the child to files for later validation with
358           atf::utils::wait().  Fails the test case if the fork fails, so this
359           does not return an error.
360
361     bool atf::utils::grep_collection(const std::string& regexp,
362     const Collection& collection)
363
364           Searches for the regular expression regexp in any of the strings
365           contained in the collection.  This is a template that accepts any
366           one-dimensional container of strings.
367
368     bool atf::utils::grep_file(const std::string& regexp,
369     const std::string& path)
370
371           Searches for the regular expression regexp in the file path.  The
372           variable arguments are used to construct the regular expression.
373
374     bool atf::utils::grep_string(const std::string& regexp,
375     const std::string& str)
376
377           Searches for the regular expression regexp in the string str.
378     void atf::utils::redirect(const int fd, const std::string& path)
379
380           Redirects the given file descriptor fd to the file path.  This
381           function exits the process in case of an error and does not prop‐
382           erly mark the test case as failed.  As a result, it should only be
383           used in subprocesses of the test case; specially those spawned by
384           atf::utils::fork().
385
386     void atf::utils::wait(const pid_t pid, const int expected_exit_status,
387     const std::string& expected_stdout, const std::string& expected_stderr)
388
389           Waits and validates the result of a subprocess spawned with
390           atf::utils::wait().  The validation involves checking that the sub‐
391           process exited cleanly and returned the code specified in
392           expected_exit_status and that its standard output and standard
393           error match the strings given in expected_stdout and
394           expected_stderr.
395
396           If any of the expected_stdout or expected_stderr strings are pre‐
397           fixed with ‘save:’, then they specify the name of the file into
398           which to store the stdout or stderr of the subprocess, and no com‐
399           parison is performed.
400

EXAMPLES

402     The following shows a complete test program with a single test case that
403     validates the addition operator:
404
405           #include <atf-c++.hpp>
406
407           ATF_TEST_CASE(addition);
408           ATF_TEST_CASE_HEAD(addition)
409           {
410               set_md_var("descr", "Sample tests for the addition operator");
411           }
412           ATF_TEST_CASE_BODY(addition)
413           {
414               ATF_REQUIRE_EQ(0 + 0, 0);
415               ATF_REQUIRE_EQ(0 + 1, 1);
416               ATF_REQUIRE_EQ(1 + 0, 1);
417
418               ATF_REQUIRE_EQ(1 + 1, 2);
419
420               ATF_REQUIRE_EQ(100 + 200, 300);
421           }
422
423           ATF_TEST_CASE(open_failure);
424           ATF_TEST_CASE_HEAD(open_failure)
425           {
426               set_md_var("descr", "Sample tests for the open function");
427           }
428           ATF_TEST_CASE_BODY(open_failure)
429           {
430               ATF_REQUIRE_ERRNO(ENOENT, open("non-existent", O_RDONLY) == -1);
431           }
432
433           ATF_TEST_CASE(known_bug);
434           ATF_TEST_CASE_HEAD(known_bug)
435           {
436               set_md_var("descr", "Reproduces a known bug");
437           }
438           ATF_TEST_CASE_BODY(known_bug)
439           {
440               expect_fail("See bug number foo/bar");
441               ATF_REQUIRE_EQ(3, 1 + 1);
442               expect_pass();
443               ATF_REQUIRE_EQ(3, 1 + 2);
444           }
445
446           ATF_INIT_TEST_CASES(tcs)
447           {
448               ATF_ADD_TEST_CASE(tcs, addition);
449               ATF_ADD_TEST_CASE(tcs, open_failure);
450               ATF_ADD_TEST_CASE(tcs, known_bug);
451           }
452

SEE ALSO

454     atf-test-program(1), atf-test-case(4), atf(7)
455
456BSD                            November 15, 2013                           BSD
Impressum