]>
jfr.im git - solanum.git/blob - tests/tap/basic.h
2 * Basic utility routines for the TAP protocol.
4 * This file is part of C TAP Harness. The current version plus supporting
5 * documentation is at <https://www.eyrie.org/~eagle/software/c-tap-harness/>.
7 * Copyright 2009, 2010, 2011, 2012, 2013, 2014, 2015, 2016
8 * Russ Allbery <eagle@eyrie.org>
9 * Copyright 2001, 2002, 2004, 2005, 2006, 2007, 2008, 2011, 2012, 2014
10 * The Board of Trustees of the Leland Stanford Junior University
12 * Permission is hereby granted, free of charge, to any person obtaining a
13 * copy of this software and associated documentation files (the "Software"),
14 * to deal in the Software without restriction, including without limitation
15 * the rights to use, copy, modify, merge, publish, distribute, sublicense,
16 * and/or sell copies of the Software, and to permit persons to whom the
17 * Software is furnished to do so, subject to the following conditions:
19 * The above copyright notice and this permission notice shall be included in
20 * all copies or substantial portions of the Software.
22 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
23 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
24 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
25 * THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
26 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
27 * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
28 * DEALINGS IN THE SOFTWARE.
34 #include <tests/tap/macros.h>
35 #include <stdarg.h> /* va_list */
36 #include <stddef.h> /* size_t */
39 * Used for iterating through arrays. ARRAY_SIZE returns the number of
40 * elements in the array (useful for a < upper bound in a for loop) and
41 * ARRAY_END returns a pointer to the element past the end (ISO C99 makes it
42 * legal to refer to such a pointer as long as it's never dereferenced).
44 #define ARRAY_SIZE(array) (sizeof(array) / sizeof((array)[0]))
45 #define ARRAY_END(array) (&(array)[ARRAY_SIZE(array)])
50 * The test count. Always contains the number that will be used for the next
53 extern unsigned long testnum
;
55 /* Print out the number of tests and set standard output to line buffered. */
56 void plan(unsigned long count
);
59 * Prepare for lazy planning, in which the plan will be printed automatically
60 * at the end of the test program.
64 /* Skip the entire test suite. Call instead of plan. */
65 void skip_all(const char *format
, ...)
66 __attribute__((__noreturn__
, __format__(printf
, 1, 2)));
69 * Basic reporting functions. The okv() function is the same as ok() but
70 * takes the test description as a va_list to make it easier to reuse the
71 * reporting infrastructure when writing new tests. ok() and okv() return the
72 * value of the success argument.
74 int ok(int success
, const char *format
, ...)
75 __attribute__((__format__(printf
, 2, 3)));
76 int okv(int success
, const char *format
, va_list args
)
77 __attribute__((__format__(printf
, 2, 0)));
78 void skip(const char *reason
, ...)
79 __attribute__((__format__(printf
, 1, 2)));
82 * Report the same status on, or skip, the next count tests. ok_block()
83 * returns the value of the success argument.
85 int ok_block(unsigned long count
, int success
, const char *format
, ...)
86 __attribute__((__format__(printf
, 3, 4)));
87 void skip_block(unsigned long count
, const char *reason
, ...)
88 __attribute__((__format__(printf
, 2, 3)));
91 * Check an expected value against a seen value. Returns true if the test
92 * passes and false if it fails. is_bool takes an int since the bool type
93 * isn't fully portable yet, but interprets both arguments for their truth
94 * value, not for their numeric value.
96 int is_bool(int wanted
, int seen
, const char *format
, ...)
97 __attribute__((__format__(printf
, 3, 4)));
98 int is_int(long wanted
, long seen
, const char *format
, ...)
99 __attribute__((__format__(printf
, 3, 4)));
100 int is_string(const char *wanted
, const char *seen
, const char *format
, ...)
101 __attribute__((__format__(printf
, 3, 4)));
102 int is_hex(unsigned long wanted
, unsigned long seen
, const char *format
, ...)
103 __attribute__((__format__(printf
, 3, 4)));
105 /* Bail out with an error. sysbail appends strerror(errno). */
106 void bail(const char *format
, ...)
107 __attribute__((__noreturn__
, __nonnull__
, __format__(printf
, 1, 2)));
108 void sysbail(const char *format
, ...)
109 __attribute__((__noreturn__
, __nonnull__
, __format__(printf
, 1, 2)));
111 /* Report a diagnostic to stderr prefixed with #. */
112 int diag(const char *format
, ...)
113 __attribute__((__nonnull__
, __format__(printf
, 1, 2)));
114 int sysdiag(const char *format
, ...)
115 __attribute__((__nonnull__
, __format__(printf
, 1, 2)));
118 * Register or unregister a file that contains supplementary diagnostics.
119 * Before any other output, all registered files will be read, line by line,
120 * and each line will be reported as a diagnostic as if it were passed to
121 * diag(). Nul characters are not supported in these files and will result in
124 void diag_file_add(const char *file
)
125 __attribute__((__nonnull__
));
126 void diag_file_remove(const char *file
)
127 __attribute__((__nonnull__
));
129 /* Allocate memory, reporting a fatal error with bail on failure. */
130 void *bcalloc(size_t, size_t)
131 __attribute__((__alloc_size__(1, 2), __malloc__
, __warn_unused_result__
));
132 void *bmalloc(size_t)
133 __attribute__((__alloc_size__(1), __malloc__
, __warn_unused_result__
));
134 void *breallocarray(void *, size_t, size_t)
135 __attribute__((__alloc_size__(2, 3), __malloc__
, __warn_unused_result__
));
136 void *brealloc(void *, size_t)
137 __attribute__((__alloc_size__(2), __malloc__
, __warn_unused_result__
));
138 char *bstrdup(const char *)
139 __attribute__((__malloc__
, __nonnull__
, __warn_unused_result__
));
140 char *bstrndup(const char *, size_t)
141 __attribute__((__malloc__
, __nonnull__
, __warn_unused_result__
));
144 * Find a test file under C_TAP_BUILD or C_TAP_SOURCE, returning the full
145 * path. The returned path should be freed with test_file_path_free().
147 char *test_file_path(const char *file
)
148 __attribute__((__malloc__
, __nonnull__
, __warn_unused_result__
));
149 void test_file_path_free(char *path
);
152 * Create a temporary directory relative to C_TAP_BUILD and return the path.
153 * The returned path should be freed with test_tmpdir_free().
155 char *test_tmpdir(void)
156 __attribute__((__malloc__
, __warn_unused_result__
));
157 void test_tmpdir_free(char *path
);
160 * Register a cleanup function that is called when testing ends. All such
161 * registered functions will be run during atexit handling (and are therefore
162 * subject to all the same constraints and caveats as atexit functions).
164 * The function must return void and will be passed two arguments: an int that
165 * will be true if the test completed successfully and false otherwise, and an
166 * int that will be true if the cleanup function is run in the primary process
167 * (the one that called plan or plan_lazy) and false otherwise.
169 typedef void (*test_cleanup_func
)(int, int);
170 void test_cleanup_register(test_cleanup_func
)
171 __attribute__((__nonnull__
));
175 #endif /* TAP_BASIC_H */