Import of code from c-tap-harness
[openafs.git] / src / external / c-tap-harness / NEWS
1                     User-Visible C TAP Harness Changes
2
3 C TAP Harness 4.7 (2020-05-16)
4
5     Allow the package test suite to be run with C_TAP_VERBOSE without
6     breaking test results via inheritance of that setting.
7
8     Fix warnings with GCC 10.
9
10 C TAP Harness 4.6 (2020-01-07)
11
12     Reformat all C source using clang-format 10 and the formatting rules
13     specified in .clang-format.
14
15     Update to rra-c-util 8.1:
16
17     * Drop support for Perl versions prior to Perl 5.8.
18
19 C TAP Harness 4.5 (2019-08-31)
20
21     Add new bcalloc_type and breallocarray_type macros that take a type
22     instead of a size as their third argument and cast the return value to
23     a pointer to that type.  These are more friendly to C++ code than
24     C-style allocation functions returning void *.
25
26     The test harness and libtap C library can now alternatively be
27     compiled with a C++ compiler, making it easier to incorporate them
28     into a C++ project.  Thanks to Peter Paris for the initial report.
29
30 C TAP Harness 4.4 (2018-12-25)
31
32     Add test_cleanup_register_with_data to the C TAP library.  This is the
33     same as test_cleanup_register except takes a generic pointer, which is
34     then passed to the cleanup function as a third argument.  This should
35     have been the only API from the beginning, but test_cleanup_register
36     is preserved for backward compatibility.  Patch from Marc Dionne.
37
38     Fix error checking for malloc failure in bstrndup function (caught by
39     cppcheck).
40
41     Update to rra-c-util 8.0:
42
43     * Skip tests requiring Test::More if it isn't available.
44     * Check for pre-SPDX license grant strings.
45     * Improved test for obsolete strings in package source files.
46
47 C TAP Harness 4.3 (2018-05-06)
48
49     Add support for valgrind and libtool test options in test lists.  Test
50     lists now take a space-separated set of options after the test name.
51     If the valgrind option is present and C_TAP_VALGRIND is set in the
52     environment, the test will be run by passing it as an option to the
53     command given in C_TAP_VALGRIND.  If the libtool option is also set,
54     valgrind will be run via the libtool script set in C_TAP_LIBTOOL,
55     using --mode=execute, so that valgrind will run on the underlying
56     binary and not the libtool shell wrapper.
57
58     On test failures, report the values as left and right instead of
59     wanted and seen.  This idea is stolen from the Rust assert framework.
60     It avoids having to care about the order in which values are passed
61     into the test functions.
62
63     Fix is_string comparisons involving NULL pointers so that the string
64     "(null)" will no longer compare equal to NULL (although the diagnostic
65     output on test failure is still mildly confusing).
66
67     Add new check-cppcheck target that runs cppcheck on all source code,
68     and fix one unnecessary check for NULL that it uncovered.
69
70     Add SPDX-License-Identifier headers to all substantial source files,
71     and add a test to check for them.  This imports more supporting test
72     machinery whose canonical home is in rra-c-util.  If you want to use
73     files in tests/tap/perl, copy them from rra-c-util instead of this
74     package.
75
76     C TAP Harness now imports the Perl test modules from rra-c-util to
77     support some checks, so tests/docs/pod-spelling-t and tests/docs/pod-t
78     have been updated to the versions from rra-c-util.  Projects that were
79     previously copying those tests should be able to continue to use them,
80     but will now need the modules in tests/tap/perl (the canonical version
81     of which are maintained in rra-c-util).
82
83 C TAP Harness 4.2 (2017-12-30)
84
85     Add is_blob function to the C test library.  This tests whether two
86     regions of memory are identical, similar to ok(memcmp(...)) but
87     reporting where the regions differ.  Patch from Daniel Collins.
88
89     Avoid zero-length realloc allocations in breallocarray.
90
91     Fix new fall-through warning in GCC 7.
92
93     Switch to the compiler warning Autoconf macros and warning set from
94     rra-c-util with the addition of -ansi -pedantic for GCC and
95     -pedantic-errors for Clang.  Add some casts to fix warnings from
96     -Wconversion, and suppress some spurious warnings from Clang about
97     tests/tap/float.c.
98
99 C TAP Harness 4.1 (2016-12-23)
100
101     Add is_bool function to the C test library.  This compares its two
102     arguments only for their truthfulness.  is_bool(true, arg) is the same
103     as ok(arg), but there are times (such as when testing for a false
104     value) where this allows for clearer code or clearer output.
105
106 C TAP Harness 4.0 (2016-05-07)
107
108     When building runtests, one must now set the C_TAP_SOURCE and
109     C_TAP_BUILD C preprocessor symbols to the source and build
110     directories, instead of SOURCE and BUILD.  An updated Makefile.am
111     recipe is documented in README.
112
113     runtests now sets C_TAP_SOURCE and C_TAP_BUILD in the environment in
114     addition to SOURCE and BUILD.  All test programs using this harness
115     should switch to the new C_TAP_SOURCE and C_TAP_BUILD environment
116     variables.  SOURCE and BUILD are very generic and may conflict with
117     other programs and uses, and setting them will be removed in a later
118     version.
119
120     The TAP test libraries (C and shell) now use C_TAP_SOURCE and
121     C_TAP_BUILD environment variables instead of SOURCE and BUILD for the
122     test_file_path() and test_tmpdir() functions.  If you were using these
123     libraries with another test harness, you will need to set the new
124     environment variables.
125
126     Fix missing va_end() call in is_double(), which would have caused
127     compilation failures or other problems on some platforms.  Thanks,
128     Julien ÉLIE.
129
130     Rename the script to bootstrap from a Git checkout to bootstrap,
131     matching the emerging consensus in the Autoconf world.
132
133 C TAP Harness 3.4 (2015-08-18)
134
135     Fix segfault in runtests when given a test list containing only
136     comments and blank lines.  Thanks, aherbert.
137
138 C TAP Harness 3.3 (2015-04-26)
139
140     If runtests is given the -v option, or if the environment variable
141     C_TAP_VERBOSE is set, the complete output of each test program will be
142     shown instead of the summary of total and failing tests.  Based on
143     work by D. Brashear.
144
145     C TAP Harness now compiles cleanly with Clang with -Weverything
146     -Wno-padded -pedantic-errors, and automatically detects Clang and
147     switches warning flags for make warnings.
148
149 C TAP Harness 3.2 (2014-12-25)
150
151     The runtests harness now supports ignoring comments and blank lines in
152     the test list specified with -l.  Leading whitespace before the test
153     name is also ignored.
154
155 C TAP Harness 3.1 (2014-07-02)
156
157     ok, okv, and all is_* functions now return true if the test succeeds
158     and false if it fails, matching the return status of the corresponding
159     Perl Test::More functions.  This allows more succinct code when the
160     actions of a test program should vary based on the success or failure
161     of previous tests.  Based on a patch by Peter Pöschl.
162
163     diag and sysdiag now always return 1, making it easier to insert calls
164     into compound statements when debugging tests.  Based on a patch by
165     Peter Pöschl.
166
167     Add new breallocarray API that does the same as realloc but takes
168     calloc-style arguments to specify the size and checks internally for
169     integer overflow.  Inspired by the OpenBSD reallocarray function.
170
171     Check for integer overflows on memory allocation.  All the possible
172     issues for this code are rather theoretical, but one may as well
173     strive for correctness.
174
175     Replace all uses of sprintf with a simpler string concatenation
176     function that checks for allocation overflow.  (The standards
177     assumptions for this package don't permit assuming asprintf or a
178     sufficiently non-broken snprintf to simulate asprintf.)
179
180 C TAP Harness 3.0 (2014-01-28)
181
182     The test_cleanup_register API has changed in this release.  Cleanup
183     functions must now take two parameters, not one, and are called from
184     all test processes, not just the primary one.  The new second argument
185     indicates whether the cleanup function was called in the primary
186     process (the one in which plan or plan_lazy was called).  External
187     resources, such as files, should generally only be freed when the
188     cleanup function is called in the primary process, but tests may want
189     to free internal resources, like memory, in all processes to ease
190     analysis with tools like valgrind.
191
192     When running test programs from a list, reopen standard input for each
193     program to /dev/null, and be more careful about closing all duplicates
194     of file descriptors left behind after setting up standard output and
195     standard error so that extraneous file descriptors aren't leaked to
196     the child process.
197
198 C TAP Harness 2.4 (2013-12-25)
199
200     Add new diag_file_add and diag_file_remove APIs to the basic C TAP
201     library.  These functions manage a list of registered file that
202     contains supplemental diagnostic information.  Each registered file is
203     checked before each output function for any new lines, and any lines
204     are displayed as if they'd been passed to diag().  This can be useful
205     if, for example, the test involves a background daemon whose output
206     can be logged to a disk file.
207
208 C TAP Harness 2.3 (2013-11-13)
209
210     Add new test_cleanup_register API to the basic C TAP library.  This
211     registers a C callback function that's called during exit from the
212     test and passed in a boolean argument indicating whether the test
213     succeeded or failed.
214
215     Suppress lazy plans and the summary of tests at the end of a test
216     program if the program aborted with bail or sysbail.
217
218     Add warn_unused_result gcc attributes to the C TAP library functions
219     where ignoring the return value is almost certainly a bug (such as all
220     the malloc functions).
221
222     Add portability for warn_unsed_result attributes to tap/macros.h.
223
224 C TAP Harness 2.2 (2013-08-14)
225
226     bail and sysbail now exit with status 255 to match the behavior of
227     BAIL_OUT in Perl's Test::More.
228
229     Document that runtests handling of test cases that bail out differs
230     from the documented behavior of BAIL_OUT in Perl's Test::More and the
231     behavior of prove, and document why.
232
233 C TAP Harness 2.1 (2013-03-15)
234
235     When locating test programs, try a suffix (-t, .t, or no suffix) with
236     all bases before moving on to the next suffix.  The behavior in the
237     previous release was not backward-compatible: it would find the
238     unsuffixed helper program in the build directory instead of the actual
239     test in the source directory for some rra-c-util tests when the build
240     directory and the source directory weren't the same.
241
242     Document that TAP version directives in the TAP output are ignored.
243
244 C TAP Harness 2.0 (2013-03-14)
245
246     The default behavior of tests/runtests has changed to make it act more
247     like other test drivers.  Now, to provide a file containing a list of
248     tests, use the -l option.  Existing users should add -l to the command
249     line in front of the test list.  Otherwise, the command-line arguments
250     are taken as tests to run, as if they were all listed in a test list
251     file.
252
253     runtests now tries the test name without any extension if the test
254     name with either -t or .t was not found.  It also does not consider a
255     directory to be a valid test when searching for the executable, even
256     if the directory is executable.
257
258     Flush the harness output after each test.  This effectively implements
259     line buffering even when standard output is not a terminal and
260     therefore output isn't flushed after each line of test output.
261
262     When displaying partial status of tests with a deferred plan, show the
263     total number of tests as ? rather than the number of tests seen so
264     far.  This matches the behavior of Perl's prove utility.
265
266     More correctly handle backspacing over the test count in several abort
267     cases when reporting status to a terminal.
268
269     Add GCC annotations to some internal functions in runtests to help
270     clang --analyze better understand code correctness.  Remove a dead
271     store caught by clang --analyze.
272
273 C TAP Harness 1.12 (2012-05-11)
274
275     Fix additional uses of local in the shell TAP library for portability
276     to Solaris /bin/sh and document a bad interaction between backquotes
277     and double quotes for the puts, test_file_path, and test_tmpdir
278     functions.
279
280     In the C TAP library, if bail is called after plan_lazy but before any
281     tests are run, don't output the plan or the summary of test results.
282
283     Add the UNUSED macro (to mark possibly-usused variables for gcc) to
284     tests/tap/macros.h for use in the C TAP library.
285
286     Make the __attribute__ handling in tests/tap/macros.h more aware of
287     different versions and compilers.  All attributes are now suppressed
288     for GCC older than 2.96 (instead of 2.7), since __malloc__ became
289     available then.  __alloc_size__ is suppressed for GCC older than 4.3.
290     Warnings about unknown diagnostics are suppressed for LLVM and Clang,
291     which pretend to be GCC but don't support all the same attributes.
292
293 C TAP Harness 1.11 (2012-04-25)
294
295     Reorganize the source package so that runtests.c is in the tests
296     directory and the C and shell TAP libraries are in tests/tap.  Change
297     the include directives in the C TAP library source files accordingly.
298     This is somewhat confusing for the standalone package, but means that
299     the files are located in the same locations here as they would be in
300     packages into which they're copied, which simplifies instructions and
301     the build system.  This also removes the need to build the C TAP
302     library with -I flags at the cost of requiring that it be located in a
303     tests subdirectory, allowing easier use of additional supporting
304     headers without requiring that all tests be built with a -I directive.
305
306     Do not attempt to use feature-test macros unless compiled with gcc's
307     -ansi flag or PEDANTIC is defined.  Defining _XOPEN_SOURCE 600 on
308     Solaris 10, which is required for isinf() if feature-test macros are
309     in use, causes compilation to fail unless the compiler is run in C99
310     mode due to an ABI change.  The basic TAP library doesn't care about
311     this distinction and doesn't want to force specific compiler flags, so
312     avoiding feature-test macros is a better fix.  Thanks to Bob
313     Friesenhahn for the bug report.
314
315     Do not use local in the shell TAP library.  Solaris /bin/sh doesn't
316     support it, and the shell library is otherwise portable to that shell.
317     Instead, use a prefix of tap_ on all non-public variables.
318
319     Move the __attribute__ and BEGIN_DECLS/END_DECLS macros from
320     tests/tap/basic.h to a new tests/tap/macros.h header file so that they
321     can be more easily reused by any other TAP add-on.  Be sure to copy
322     tests/tap/macros.h into your source package and add it to the source
323     files for the libtap library when upgrading.
324
325     Move the is_double C TAP test function into a separate source file.
326     Including this function may require linking with libm on some
327     platforms, which is undesirable if the package otherwise doesn't use
328     math functions.  The new tests/tap/float.c and tests/tap/float.h files
329     need only be included in a package that wants to do floating point
330     tests.  Users of is_double will now need to include tests/tap/float.h
331     in addition to tests/tap/basic.h (and link all clients of the libtap
332     library with -lm).
333
334 C TAP Harness 1.10 (2012-02-29)
335
336     Add bstrndup to the basic C TAP library.  This is akin to strndup
337     (copying at most n characters of the string), but calls sysbail if
338     memory allocation fails.
339
340 C TAP Harness 1.9 (2011-12-24)
341
342     Add test_tmpdir and test_tmpdir_free functions to the basic C TAP
343     library and a test_tmpdir function to the shell TAP library.  These
344     functions create a temporary directory under the build tests directory
345     for tests to use for transient files.
346
347     runtests now frees all allocated resources on exit so that it can be
348     used to run test cases with valgrind memory allocation checking
349     without adding false positives.
350
351 C TAP Harness 1.8 (2011-09-02)
352
353     Add bmalloc, bcalloc, brealloc, and bstrdup functions to the basic C
354     TAP library.  These functions call sysbail if memory allocation fails.
355
356     If BUILD were not set when building runtests and the -b option was not
357     present, SOURCE and the -s option would be ignored when searching for
358     tests.  Fix runtests to still honor SOURCE and -s when searching for
359     tests even in that case.
360
361 C TAP Harness 1.7 (2011-04-28)
362
363     Add a more complete usage message to runtests and add support for a -h
364     command-line flag to display the usage message.
365
366 C TAP Harness 1.6 (2010-12-29)
367
368     is_double() now takes a third argument, an epsilon.  Two numbers are
369     considered equal if their absolute difference is less than epsilon.
370     is_double() also now treats wanted and seen values of NaN (not a
371     number) as equal.  Thanks to PICCA Frédéric-Emmanuel for the proposed
372     changes.
373
374     The ok_program function in the shell libtap.sh library no longer
375     strips text after a colon and a space from the program output if the
376     expected status is non-zero.  Instead, if program output may contain
377     system-specific error messages after a colon and a space, put the new
378     function strip_colon_error before the program to do this stripping.
379     Thanks to Carsten Hey for the idea.
380
381     strip_colon_error is now smarter about preserving an initial word
382     ending in a colon (which is generally the program name) while still
383     stripping error messages later in the line.
384
385     The test_file_path function in the shell libtap.sh library now always
386     returns the empty string, rather than possible absolute paths starting
387     at /, if $BUILD and $SOURCE are not set.
388
389     Flush standard error in the C TAP library before printing results for
390     more deterministic output.  Thanks to Carsten Hey for the idea.
391
392     All of C TAP Harness now compiles with gcc -ansi -pedantic and should
393     be fully C89-compatible.  Note that either C99 or SUSv3 is required to
394     build C TAP Harness.  (This should not be a problem on any modern
395     platform.)  Based on work by Carsten Hey.
396
397     Simplify and improve output formatting in the summary of failing tests
398     in some edge cases.
399
400     Add explicit license statements to the files meant to be copied into
401     other packages rather than referring to LICENSE.
402
403 C TAP Harness 1.5 (2010-08-25)
404
405     In ok_program in the shell TAP library, strip error output after the
406     second colon, not after the first.  This code helps comparing error
407     output that includes system error messages, but needs to skip past the
408     first colon, since it separates the program name from the error
409     message.
410
411     runtests.c now builds without warnings with gcc -Wswitch-enum.
412
413 C TAP Harness 1.4 (2010-07-07)
414
415     Add a test_file_path() function to the basic C and shell TAP
416     libraries, which searches the build and source directories for a
417     particular file and returns the full path.  This is a utility function
418     that can be used to find test data files.
419
420 C TAP Harness 1.3 (2010-06-09)
421
422     Add API documentation for the functions provided by the basic TAP C
423     library.  The documentation is in POD and *roff format in docs/api and
424     installed as man pages in the (generally unused) case of make install.
425
426     Add docs/writing-tests, which provides some basic instructions for how
427     to write TAP tests in Perl, C, and shell using the facilities provided
428     by C TAP Harness.  This document is suitable for inclusion in packages
429     that use C TAP Harness as instructions for contributors.
430
431     Add an okv() function to the C TAP library.  This is the same as ok()
432     but takes the test description as a va_list to make it easier to reuse
433     the reporting infrastructure in other tests.
434
435 C TAP Harness 1.2 (2010-04-13)
436
437     Support giving the plan at any point in the test output rather than
438     requiring it be first.  The TAP protocol permits giving the plan last
439     instead of first, but since it's just as easy to support providing the
440     plan in the middle of the test output, allow that as well.
441
442     Add support for lazy planning to the basic TAP library.  Instead of
443     calling plan at the start of the test, call plan_lazy instead, which
444     doesn't require specifying a test count.  Then, the plan will
445     automatically be printed based on the last test number at the end of
446     the program.  This is not the recommended approach for writing tests
447     since, should the test program exit in the middle for some reason,
448     everything will appear to succeed.  But it can save time in writing
449     tests quickly and allows for dynamic numbers of tests.
450
451     Add diag and sysdiag functions to the basic TAP library, which output
452     diagnostics to standard error preceded by the protocol-required #
453     character.
454
455     Clean up data types in the basic C TAP library.  Test numbers and
456     counts are now unsigned long, and ok_int compares longs.
457
458     Add the GCC nonnull attribute to the bail functions in the TAP
459     library.
460
461 C TAP Harness 1.1 (2009-08-15)
462
463     Set an exit handler in libtap that prints a summary of the test
464     results at the end of a test script, similar to Perl's Test::More.
465
466     When looking for 0..1 # skip plan lines indicating the whole test case
467     should be skipped, correctly compare "skip" case-insensitively.  This
468     fixes interoperability with Perl's Test::More.
469
470     Consume all output from the test case before closing its file
471     descriptor, even if the case is aborted due to bailing out or sending
472     an invalid test number.  This prevents tests from spuriously dying
473     with SIGPIPE.
474
475     Enable Automake silent rules.  For a quieter build, pass the
476     --enable-silent-rules option to configure or build with make V=0.
477
478 C TAP Harness 1.0 (2009-05-21)
479
480     Initial public release based on the version of runtests.c and the
481     libtest library that shipped with remctl 2.13.  The changes below are
482     relative to that version.
483
484     Set the SOURCE and BUILD environment variables when running tests to
485     the roots of the source and build test directories if set at compile
486     time or via the -s and -b command-line options to runtests.
487
488     Search for test programs first in the current directory and then in
489     the build and source directories, in that order, as specified by
490     SOURCE and BUILD or by the -s and -b options.  This allows some tests
491     to be compiled and some shipped with the package and merged together
492     at run time by runtests, even if the build directory is not the source
493     directory.
494
495     Support running a single test program with the -o command-line option.
496     This is mostly interesting to take advantage of the environment
497     variables and test searching algorithm described above.
498
499     Add support for 0..1 # skip <reason> plan lines, indicating that the
500     entire test case should be skipped.
501
502     Add support for aborting a test case with "Bail out!" and reporting
503     the reason given on that line.
504
505     Add support for omitting the test number from an "ok" or "not ok"
506     line, in which case the number is assumed to be one more than the
507     previous number.
508
509     Add support for todo tests, which are recorded as skipped if failing
510     and failed if they succeed unexpectedly.
511
512     Omitting the space after "ok" or "not ok" line is now supported, and a
513     test number of 0 now results in an error.
514
515     Recognize skip directives regardless of case.
516
517     Change the reporting of reasons to abort the test case to use ABORTED
518     and the abort reason in parentheses for more consistent output.
519
520     Rename test_init() to plan() and ok_int(), ok_double(), and
521     ok_string() to is_int(), is_double(), and is_string() in the C TAP
522     library to more closely match the function names in Perl's test
523     modules.
524
525     Add is_hex() C TAP library function to compare two unsigned longs and
526     print mismatches in hex.
527
528     Change all C library functions to take a test description
529     (printf-style) and to no longer take the test number.  Instead, keep a
530     static count of the current test number.
531
532     Add bail() and sysbail() C TAP library functions to bail out with the
533     right magic output string.
534
535     Add skip_all() C TAP library function to skip all tests and exit.
536
537     Stop exporting the printcount interface in the shell version of the
538     TAP library.  Instead, provide plan, skip_all, ok, skip, ok_block,
539     skip_block, ok_program, and bail shell functions, similar to the C
540     library interface, with the ok* functions taking a test description as
541     the first argument.
542
543     Show mismatch output from the is_*() functions before the "not ok"
544     line instead of after it.
545
546     Add the initial "1.." to plan() output for better TAP compliance.
547
548     Support either "-t" or ".t" as the ending of test cases.
549
550     Remove the dependency on both config.h and the general portability
551     framework and instead include the necessary C headers directly.  This
552     requires ANSI C.
553
554     Remove the functions from libtap that assume libutil from rra-c-util.
555     Those library functions will be provided by that package.