2 * Some utility routines for writing tests.
4 * Here are a variety of utility routines for writing tests compatible with
5 * the TAP protocol. All routines of the form ok() or is*() take a test
6 * number and some number of appropriate arguments, check to be sure the
7 * results match the expected output using the arguments, and print out
8 * something appropriate for that test number. Other utility routines help in
9 * constructing more complex tests, skipping tests, or setting up the TAP
12 * This file is part of C TAP Harness. The current version plus supporting
13 * documentation is at <http://www.eyrie.org/~eagle/software/c-tap-harness/>.
15 * Copyright 2009, 2010 Russ Allbery <rra@stanford.edu>
16 * Copyright 2001, 2002, 2004, 2005, 2006, 2007, 2008
17 * The Board of Trustees of the Leland Stanford Junior University
19 * Permission is hereby granted, free of charge, to any person obtaining a
20 * copy of this software and associated documentation files (the "Software"),
21 * to deal in the Software without restriction, including without limitation
22 * the rights to use, copy, modify, merge, publish, distribute, sublicense,
23 * and/or sell copies of the Software, and to permit persons to whom the
24 * Software is furnished to do so, subject to the following conditions:
26 * The above copyright notice and this permission notice shall be included in
27 * all copies or substantial portions of the Software.
29 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
30 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
31 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
32 * THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
33 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
34 * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
35 * DEALINGS IN THE SOFTWARE.
38 /* Required for isnan() and isinf(). */
40 # define _XOPEN_SOURCE 600
49 #include <sys/types.h>
54 #include <tap/basic.h>
57 * The test count. Always contains the number that will be used for the next
60 unsigned long testnum = 1;
63 * Status information stored so that we can give a test summary at the end of
64 * the test case. We store the planned final test and the count of failures.
65 * We can get the highest test count from testnum.
67 * We also store the PID of the process that called plan() and only summarize
68 * results when that process exits, so as to not misreport results in forked
71 * If _lazy is true, we're doing lazy planning and will print out the plan
72 * based on the last test number at the end of testing.
74 static unsigned long _planned = 0;
75 static unsigned long _failed = 0;
76 static pid_t _process = 0;
81 * Our exit handler. Called on completion of the test to report a summary of
82 * results provided we're still in the original process.
87 unsigned long highest = testnum - 1;
89 if (_planned == 0 && !_lazy)
92 if (_process != 0 && getpid() == _process) {
94 printf("1..%lu\n", highest);
97 if (_planned > highest)
98 printf("# Looks like you planned %lu test%s but only ran %lu\n",
99 _planned, (_planned > 1 ? "s" : ""), highest);
100 else if (_planned < highest)
101 printf("# Looks like you planned %lu test%s but ran %lu extra\n",
102 _planned, (_planned > 1 ? "s" : ""), highest - _planned);
103 else if (_failed > 0)
104 printf("# Looks like you failed %lu test%s of %lu\n", _failed,
105 (_failed > 1 ? "s" : ""), _planned);
106 else if (_planned > 1)
107 printf("# All %lu tests successful or skipped\n", _planned);
109 printf("# %lu test successful or skipped\n", _planned);
115 * Initialize things. Turns on line buffering on stdout and then prints out
116 * the number of tests in the test suite.
119 plan(unsigned long count)
121 if (setvbuf(stdout, NULL, _IOLBF, BUFSIZ) != 0)
122 fprintf(stderr, "# cannot set stdout to line buffered: %s\n",
125 printf("1..%lu\n", count);
134 * Initialize things for lazy planning, where we'll automatically print out a
135 * plan at the end of the program. Turns on line buffering on stdout as well.
140 if (setvbuf(stdout, NULL, _IOLBF, BUFSIZ) != 0)
141 fprintf(stderr, "# cannot set stdout to line buffered: %s\n",
151 * Skip the entire test suite and exits. Should be called instead of plan(),
152 * not after it, since it prints out a special plan line.
155 skip_all(const char *format, ...)
158 printf("1..0 # skip");
159 if (format != NULL) {
163 va_start(args, format);
164 vprintf(format, args);
173 * Print the test description.
176 print_desc(const char *format, va_list args)
179 vprintf(format, args);
184 * Takes a boolean success value and assumes the test passes if that value
185 * is true and fails if that value is false.
188 ok(int success, const char *format, ...)
191 printf("%sok %lu", success ? "" : "not ", testnum++);
194 if (format != NULL) {
197 va_start(args, format);
198 print_desc(format, args);
206 * Same as ok(), but takes the format arguments as a va_list.
209 okv(int success, const char *format, va_list args)
212 printf("%sok %lu", success ? "" : "not ", testnum++);
216 print_desc(format, args);
225 skip(const char *reason, ...)
228 printf("ok %lu # skip", testnum++);
229 if (reason != NULL) {
232 va_start(args, reason);
234 vprintf(reason, args);
242 * Report the same status on the next count tests.
245 ok_block(unsigned long count, int status, const char *format, ...)
250 for (i = 0; i < count; i++) {
251 printf("%sok %lu", status ? "" : "not ", testnum++);
254 if (format != NULL) {
257 va_start(args, format);
258 print_desc(format, args);
267 * Skip the next count tests.
270 skip_block(unsigned long count, const char *reason, ...)
275 for (i = 0; i < count; i++) {
276 printf("ok %lu # skip", testnum++);
277 if (reason != NULL) {
280 va_start(args, reason);
282 vprintf(reason, args);
291 * Takes an expected integer and a seen integer and assumes the test passes
292 * if those two numbers match.
295 is_int(long wanted, long seen, const char *format, ...)
299 printf("ok %lu", testnum++);
301 printf("# wanted: %ld\n# seen: %ld\n", wanted, seen);
302 printf("not ok %lu", testnum++);
305 if (format != NULL) {
308 va_start(args, format);
309 print_desc(format, args);
317 * Takes a string and what the string should be, and assumes the test passes
318 * if those strings match (using strcmp).
321 is_string(const char *wanted, const char *seen, const char *format, ...)
328 if (strcmp(wanted, seen) == 0)
329 printf("ok %lu", testnum++);
331 printf("# wanted: %s\n# seen: %s\n", wanted, seen);
332 printf("not ok %lu", testnum++);
335 if (format != NULL) {
338 va_start(args, format);
339 print_desc(format, args);
347 * Takes an expected double and a seen double and assumes the test passes if
348 * those two numbers are within delta of each other.
351 is_double(double wanted, double seen, double epsilon, const char *format, ...)
354 if ((isnan(wanted) && isnan(seen))
355 || (isinf(wanted) && isinf(seen) && wanted == seen)
356 || fabs(wanted - seen) <= epsilon)
357 printf("ok %lu", testnum++);
359 printf("# wanted: %g\n# seen: %g\n", wanted, seen);
360 printf("not ok %lu", testnum++);
363 if (format != NULL) {
366 va_start(args, format);
367 print_desc(format, args);
375 * Takes an expected unsigned long and a seen unsigned long and assumes the
376 * test passes if the two numbers match. Otherwise, reports them in hex.
379 is_hex(unsigned long wanted, unsigned long seen, const char *format, ...)
383 printf("ok %lu", testnum++);
385 printf("# wanted: %lx\n# seen: %lx\n", (unsigned long) wanted,
386 (unsigned long) seen);
387 printf("not ok %lu", testnum++);
390 if (format != NULL) {
393 va_start(args, format);
394 print_desc(format, args);
402 * Bail out with an error.
405 bail(const char *format, ...)
411 printf("Bail out! ");
412 va_start(args, format);
413 vprintf(format, args);
421 * Bail out with an error, appending strerror(errno).
424 sysbail(const char *format, ...)
431 printf("Bail out! ");
432 va_start(args, format);
433 vprintf(format, args);
435 printf(": %s\n", strerror(oerrno));
441 * Report a diagnostic to stderr.
444 diag(const char *format, ...)
451 va_start(args, format);
452 vprintf(format, args);
459 * Report a diagnostic to stderr, appending strerror(errno).
462 sysdiag(const char *format, ...)
470 va_start(args, format);
471 vprintf(format, args);
473 printf(": %s\n", strerror(oerrno));
478 * Locate a test file. Given the partial path to a file, look under BUILD and
479 * then SOURCE for the file and return the full path to the file. Returns
480 * NULL if the file doesn't exist. A non-NULL return should be freed with
481 * test_file_path_free().
483 * This function uses sprintf because it attempts to be independent of all
484 * other portability layers. The use immediately after a memory allocation
485 * should be safe without using snprintf or strlcpy/strlcat.
488 test_file_path(const char *file)
493 const char *envs[] = { "BUILD", "SOURCE", NULL };
496 for (i = 0; envs[i] != NULL; i++) {
497 base = getenv(envs[i]);
500 length = strlen(base) + 1 + strlen(file) + 1;
501 path = malloc(length);
503 sysbail("cannot allocate memory");
504 sprintf(path, "%s/%s", base, file);
505 if (access(path, R_OK) == 0)
515 * Free a path returned from test_file_path(). This function exists primarily
516 * for Windows, where memory must be freed from the same library domain that
517 * it was allocated from.
520 test_file_path_free(char *path)