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, reporting errors, setting
10 * up the TAP output format, or finding things in the test environment.
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, 2011, 2012 Russ Allbery <eagle@eyrie.org>
16 * Copyright 2001, 2002, 2004, 2005, 2006, 2007, 2008, 2011, 2012, 2013
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.
46 # include <sys/stat.h>
48 #include <sys/types.h>
51 #include <tests/tap/basic.h>
53 /* Windows provides mkdir and rmdir under different names. */
55 # define mkdir(p, m) _mkdir(p)
56 # define rmdir(p) _rmdir(p)
60 * The test count. Always contains the number that will be used for the next
63 unsigned long testnum = 1;
66 * Status information stored so that we can give a test summary at the end of
67 * the test case. We store the planned final test and the count of failures.
68 * We can get the highest test count from testnum.
70 * We also store the PID of the process that called plan() and only summarize
71 * results when that process exits, so as to not misreport results in forked
74 * If _lazy is true, we're doing lazy planning and will print out the plan
75 * based on the last test number at the end of testing.
77 static unsigned long _planned = 0;
78 static unsigned long _failed = 0;
79 static pid_t _process = 0;
84 * Our exit handler. Called on completion of the test to report a summary of
85 * results provided we're still in the original process. This also handles
86 * printing out the plan if we used plan_lazy(), although that's suppressed if
87 * we never ran a test (due to an early bail, for example).
92 unsigned long highest = testnum - 1;
94 if (_planned == 0 && !_lazy)
97 if (_process != 0 && getpid() == _process) {
98 if (_lazy && highest > 0) {
99 printf("1..%lu\n", highest);
102 if (_planned > highest)
103 printf("# Looks like you planned %lu test%s but only ran %lu\n",
104 _planned, (_planned > 1 ? "s" : ""), highest);
105 else if (_planned < highest)
106 printf("# Looks like you planned %lu test%s but ran %lu extra\n",
107 _planned, (_planned > 1 ? "s" : ""), highest - _planned);
108 else if (_failed > 0)
109 printf("# Looks like you failed %lu test%s of %lu\n", _failed,
110 (_failed > 1 ? "s" : ""), _planned);
111 else if (_planned > 1)
112 printf("# All %lu tests successful or skipped\n", _planned);
114 printf("# %lu test successful or skipped\n", _planned);
120 * Initialize things. Turns on line buffering on stdout and then prints out
121 * the number of tests in the test suite.
124 plan(unsigned long count)
126 if (setvbuf(stdout, NULL, _IOLBF, BUFSIZ) != 0)
127 fprintf(stderr, "# cannot set stdout to line buffered: %s\n",
130 printf("1..%lu\n", count);
139 * Initialize things for lazy planning, where we'll automatically print out a
140 * plan at the end of the program. Turns on line buffering on stdout as well.
145 if (setvbuf(stdout, NULL, _IOLBF, BUFSIZ) != 0)
146 fprintf(stderr, "# cannot set stdout to line buffered: %s\n",
156 * Skip the entire test suite and exits. Should be called instead of plan(),
157 * not after it, since it prints out a special plan line.
160 skip_all(const char *format, ...)
163 printf("1..0 # skip");
164 if (format != NULL) {
168 va_start(args, format);
169 vprintf(format, args);
178 * Print the test description.
181 print_desc(const char *format, va_list args)
184 vprintf(format, args);
189 * Takes a boolean success value and assumes the test passes if that value
190 * is true and fails if that value is false.
193 ok(int success, const char *format, ...)
196 printf("%sok %lu", success ? "" : "not ", testnum++);
199 if (format != NULL) {
202 va_start(args, format);
203 print_desc(format, args);
211 * Same as ok(), but takes the format arguments as a va_list.
214 okv(int success, const char *format, va_list args)
217 printf("%sok %lu", success ? "" : "not ", testnum++);
221 print_desc(format, args);
230 skip(const char *reason, ...)
233 printf("ok %lu # skip", testnum++);
234 if (reason != NULL) {
237 va_start(args, reason);
239 vprintf(reason, args);
247 * Report the same status on the next count tests.
250 ok_block(unsigned long count, int status, const char *format, ...)
255 for (i = 0; i < count; i++) {
256 printf("%sok %lu", status ? "" : "not ", testnum++);
259 if (format != NULL) {
262 va_start(args, format);
263 print_desc(format, args);
272 * Skip the next count tests.
275 skip_block(unsigned long count, const char *reason, ...)
280 for (i = 0; i < count; i++) {
281 printf("ok %lu # skip", testnum++);
282 if (reason != NULL) {
285 va_start(args, reason);
287 vprintf(reason, args);
296 * Takes an expected integer and a seen integer and assumes the test passes
297 * if those two numbers match.
300 is_int(long wanted, long seen, const char *format, ...)
304 printf("ok %lu", testnum++);
306 printf("# wanted: %ld\n# seen: %ld\n", wanted, seen);
307 printf("not ok %lu", testnum++);
310 if (format != NULL) {
313 va_start(args, format);
314 print_desc(format, args);
322 * Takes a string and what the string should be, and assumes the test passes
323 * if those strings match (using strcmp).
326 is_string(const char *wanted, const char *seen, const char *format, ...)
333 if (strcmp(wanted, seen) == 0)
334 printf("ok %lu", testnum++);
336 printf("# wanted: %s\n# seen: %s\n", wanted, seen);
337 printf("not ok %lu", testnum++);
340 if (format != NULL) {
343 va_start(args, format);
344 print_desc(format, args);
352 * Takes an expected unsigned long and a seen unsigned long and assumes the
353 * test passes if the two numbers match. Otherwise, reports them in hex.
356 is_hex(unsigned long wanted, unsigned long seen, const char *format, ...)
360 printf("ok %lu", testnum++);
362 printf("# wanted: %lx\n# seen: %lx\n", (unsigned long) wanted,
363 (unsigned long) seen);
364 printf("not ok %lu", testnum++);
367 if (format != NULL) {
370 va_start(args, format);
371 print_desc(format, args);
379 * Bail out with an error.
382 bail(const char *format, ...)
388 printf("Bail out! ");
389 va_start(args, format);
390 vprintf(format, args);
398 * Bail out with an error, appending strerror(errno).
401 sysbail(const char *format, ...)
408 printf("Bail out! ");
409 va_start(args, format);
410 vprintf(format, args);
412 printf(": %s\n", strerror(oerrno));
418 * Report a diagnostic to stderr.
421 diag(const char *format, ...)
428 va_start(args, format);
429 vprintf(format, args);
436 * Report a diagnostic to stderr, appending strerror(errno).
439 sysdiag(const char *format, ...)
447 va_start(args, format);
448 vprintf(format, args);
450 printf(": %s\n", strerror(oerrno));
455 * Allocate cleared memory, reporting a fatal error with bail on failure.
458 bcalloc(size_t n, size_t size)
464 sysbail("failed to calloc %lu", (unsigned long)(n * size));
470 * Allocate memory, reporting a fatal error with bail on failure.
479 sysbail("failed to malloc %lu", (unsigned long) size);
485 * Reallocate memory, reporting a fatal error with bail on failure.
488 brealloc(void *p, size_t size)
490 p = realloc(p, size);
492 sysbail("failed to realloc %lu bytes", (unsigned long) size);
498 * Copy a string, reporting a fatal error with bail on failure.
501 bstrdup(const char *s)
509 sysbail("failed to strdup %lu bytes", (unsigned long) len);
516 * Copy up to n characters of a string, reporting a fatal error with bail on
517 * failure. Don't use the system strndup function, since it may not exist and
518 * the TAP library doesn't assume any portability support.
521 bstrndup(const char *s, size_t n)
527 /* Don't assume that the source string is nul-terminated. */
528 for (p = s; (size_t) (p - s) < n && *p != '\0'; p++)
531 copy = malloc(length + 1);
533 sysbail("failed to strndup %lu bytes", (unsigned long) length);
534 memcpy(copy, s, length);
541 * Locate a test file. Given the partial path to a file, look under BUILD and
542 * then SOURCE for the file and return the full path to the file. Returns
543 * NULL if the file doesn't exist. A non-NULL return should be freed with
544 * test_file_path_free().
546 * This function uses sprintf because it attempts to be independent of all
547 * other portability layers. The use immediately after a memory allocation
548 * should be safe without using snprintf or strlcpy/strlcat.
551 test_file_path(const char *file)
556 const char *envs[] = { "BUILD", "SOURCE", NULL };
559 for (i = 0; envs[i] != NULL; i++) {
560 base = getenv(envs[i]);
563 length = strlen(base) + 1 + strlen(file) + 1;
564 path = bmalloc(length);
565 sprintf(path, "%s/%s", base, file);
566 if (access(path, R_OK) == 0)
576 * Free a path returned from test_file_path(). This function exists primarily
577 * for Windows, where memory must be freed from the same library domain that
578 * it was allocated from.
581 test_file_path_free(char *path)
589 * Create a temporary directory, tmp, under BUILD if set and the current
590 * directory if it does not. Returns the path to the temporary directory in
591 * newly allocated memory, and calls bail on any failure. The return value
592 * should be freed with test_tmpdir_free.
594 * This function uses sprintf because it attempts to be independent of all
595 * other portability layers. The use immediately after a memory allocation
596 * should be safe without using snprintf or strlcpy/strlcat.
605 build = getenv("BUILD");
608 length = strlen(build) + strlen("/tmp") + 1;
609 path = bmalloc(length);
610 sprintf(path, "%s/tmp", build);
611 if (access(path, X_OK) < 0)
612 if (mkdir(path, 0777) < 0)
613 sysbail("error creating temporary directory %s", path);
619 * Free a path returned from test_tmpdir() and attempt to remove the
620 * directory. If we can't delete the directory, don't worry; something else
621 * that hasn't yet cleaned up may still be using it.
624 test_tmpdir_free(char *path)