Import of code from c-tap-harness
[openafs.git] / src / external / c-tap-harness / README
1                             C TAP Harness 4.7
2                (C harness for running TAP-compliant tests)
3                Maintained by Russ Allbery <eagle@eyrie.org>
4
5   Copyright 2000-2001, 2004, 2006-2020 Russ Allbery <eagle@eyrie.org>.
6   Copyright 2006-2009, 2011-2013 The Board of Trustees of the Leland
7   Stanford Junior University.  This software is distributed under a
8   BSD-style license.  Please see the section LICENSE below for more
9   information.
10
11 BLURB
12
13   C TAP Harness is a pure-C implementation of TAP, the Test Anything
14   Protocol.  TAP is the text-based protocol used by Perl's test suite.
15   This package provides a harness similar to Perl's Test::Harness for
16   running tests, with some additional features useful for test suites in
17   packages that use Autoconf and Automake, and C and shell libraries to
18   make writing TAP-compliant test programs easier.
19
20 DESCRIPTION
21
22   This package started as the runtests program I wrote for INN in 2000 to
23   serve as the basis for a new test suite using a test protocol similar to
24   that used for Perl modules.  When I started maintaining additional C
25   packages, I adopted runtests for the test suite driver of those as well,
26   resulting in further improvements but also separate copies of the same
27   program in different distributions.  The C TAP Harness distribution
28   merges all the various versions into a single code base that all my
29   packages can pull from.
30
31   C TAP Harness provides a full TAP specification driver (apart from a few
32   possible edge cases) and has additional special features for supporting
33   builds outside the source directory.  It's mostly useful for packages
34   using Autoconf and Automake and because it doesn't assume or require
35   Perl.
36
37   The runtests program can be built with knowledge of the source and build
38   directory and pass that knowledge on to test scripts, and will search
39   for test scripts in both the source and build directory.  This makes it
40   easier for packages using Autoconf and Automake and supporting
41   out-of-tree builds to build some test programs, ship others, and run
42   them all regardless of what tree they're in.  It also makes it easier
43   for test cases to find their supporting files when they run.
44
45   Also included in this package are C and shell libraries that provide
46   utility functions for writing test scripts that use TAP to report
47   results.  The C library also provides a variety of utility functions
48   useful for test programs running as part of an Automake-built package:
49   finding test data files, creating temporary files, reporting output from
50   external programs running in the background, and similar common
51   problems.
52
53 REQUIREMENTS
54
55   C TAP Harness requires a C compiler to build.  Any ISO C89 or later C
56   compiler on a system supporting the Single UNIX Specification, version 3
57   (SUSv3) should be sufficient.  This should not be a problem on any
58   modern system.  The test suite and shell library require a
59   Bourne-compatible shell.  Outside of the test suite, C TAP Harness has
60   no other prerequisites or requirements.
61
62   C TAP Harness can also be built with a C++ compiler and should be
63   similarly portable to any recent C++ compiler, although it is only
64   tested with g++.
65
66   To bootstrap from a Git checkout, or if you change the Automake files
67   and need to regenerate Makefile.in, you will need Automake 1.11 or
68   later.  For bootstrap or if you change configure.ac or any of the m4
69   files it includes and need to regenerate configure or config.h.in, you
70   will need Autoconf 2.64 or later.  Perl is also required to generate
71   manual pages from a fresh Git checkout.
72
73 BUILDING
74
75   You can build C TAP Harness with the standard commands:
76
77       ./configure
78       make
79
80   If you are building from a Git clone, first run ./bootstrap in the
81   source directory to generate the build files.  Building outside of the
82   source directory is also supported, if you wish, by creating an empty
83   directory and then running configure with the correct relative path.
84
85   Pass --enable-silent-rules to configure for a quieter build (similar to
86   the Linux kernel).  Use make warnings instead of make to build with full
87   compiler warnings (requires either GCC or Clang and may require a
88   relatively current version of the compiler).
89
90   Installing C TAP Harness is not normally done.  Instead, see the section
91   on using the harness below.
92
93 TESTING
94
95   C TAP Harness comes with a comprehensive test suite, which you can run
96   after building with:
97
98       make check
99
100   If a test fails, you can run a single test with verbose output via:
101
102       tests/runtests -b $(pwd)/tests -s $(pwd)/tests -o <name-of-test>
103
104   Do this instead of running the test program directly since it will
105   ensure that necessary environment variables are set up.  You may need to
106   change the -s option argument if you build with a separate build
107   directory from the source directory.
108
109   To run the test suite, you will need Perl 5.8 or later.  The following
110   additional Perl modules will be used by the test suite if present:
111
112   * Test::Pod
113   * Test::Spelling
114
115   All are available on CPAN.  Those tests will be skipped if the modules
116   are not available.
117
118   To enable tests that don't detect functionality problems but are used to
119   sanity-check the release, set the environment variable RELEASE_TESTING
120   to a true value.  To enable tests that may be sensitive to the local
121   environment or that produce a lot of false positives without uncovering
122   many problems, set the environment variable AUTHOR_TESTING to a true
123   value.
124
125 USING THE HARNESS
126
127   While there is an install target that installs runtests in the default
128   binary directory (/usr/local/bin by default) and installs the man pages,
129   one normally wouldn't install anything from this package.  Instead, the
130   code is intended to be copied into your package and refreshed from the
131   latest release of C TAP Harness for each release.
132
133   You can obviously copy the code and integrate it however works best for
134   your package and your build system.  Here's how I do it for my packages
135   as an example:
136
137   * Create a tests directory and copy tests/runtests.c into it.  Create a
138     tests/tap subdirectory and copy the portions of the TAP library (from
139     tests/tap) that I need for that package into it.  The TAP library is
140     designed to let you drop in additional source and header files for
141     additional utility functions that are useful in your package.
142
143   * Add code to my top-level Makefile.am (I always use a non-recursive
144     Makefile with subdir-objects set) to build runtests and the test
145     library:
146
147         check_PROGRAMS = tests/runtests
148         tests_runtests_CPPFLAGS = -DC_TAP_SOURCE='"$(abs_top_srcdir)/tests"' \
149                 -DC_TAP_BUILD='"$(abs_top_builddir)/tests"'
150         check_LIBRARIES = tests/tap/libtap.a
151         tests_tap_libtap_a_CPPFLAGS = -I$(abs_top_srcdir)/tests
152         tests_tap_libtap_a_SOURCES = tests/tap/basic.c tests/tap/basic.h \
153                 tests/tap/float.c tests/tap/float.h tests/tap/macros.h
154
155     Omit float.c and float.h from the last line if your package doesn't
156     need the is_double function.  Building the build and source
157     directories into runtests will let tests/runtests -o <test> work for
158     users without requiring that they set any other variables, even if
159     they're doing an out-of-source build.
160
161     Add additional source files and headers that should go into the TAP
162     library if you added extra utility functions for your package.
163
164   * Add code to Makefile.am to run the test suite:
165
166         check-local: $(check_PROGRAMS)
167               cd tests && ./runtests -l $(abs_top_srcdir)/tests/TESTS
168
169     See the Makefile.am in this package for an example.
170
171   * List the test programs in the tests/TESTS file.  This should have the
172     name of the test executable with the trailing "-t" or ".t" (you can
173     use either extension as you prefer) omitted.
174
175     Test programs must be executable.
176
177     For any test programs that need to be compiled, add build rules for
178     them in Makefile.am, similar to:
179
180         tests_libtap_c_basic_LDADD = tests/tap/libtap.a
181
182     and add them to check_PROGRAMS.  If you include the float.c add-on in
183     your libtap library, you will need to add -lm to the _LDADD setting
184     for all test programs linked against it.
185
186     A more complex example from the remctl package that needs additional
187     libraries:
188
189         tests_client_open_t_LDFLAGS = $(GSSAPI_LDFLAGS)
190         tests_client_open_t_LDADD = client/libremctl.la tests/tap/libtap.a \
191                 util/libutil.la $(GSSAPI_LIBS)
192
193     If the test program doesn't need to be compiled, add it to EXTRA_DIST
194     so that it will be included in the distribution.
195
196   * If you have test programs written in shell, copy tests/tap/libtap.sh
197     the tap subdirectory of your tests directory and add it to EXTRA_DIST.
198     Shell programs should start with:
199
200         . "${C_TAP_SOURCE}/tap/libtap.sh"
201
202     and can then use the functions defined in the library.
203
204   * Optionally copy docs/writing-tests into your package somewhere, such
205     as tests/README, as instructions to contributors on how to write tests
206     for this framework.
207
208   If you have configuration files that the user must create to enable some
209   of the tests, conventionally they go into tests/config.
210
211   If you have data files that your test cases use, conventionally they go
212   into tests/data.  You can then find the data directory relative to the
213   C_TAP_SOURCE environment variable (set by runtests) in your test
214   program.  If you have data that's compiled or generated by Autoconf, it
215   will be relative to the BUILD environment variable.  Don't forget to add
216   test data to EXTRA_DIST as necessary.
217
218   For more TAP library add-ons, generally ones that rely on additional
219   portability code not shipped in this package or with narrower uses, see
220   the rra-c-util package [1].  There are several additional TAP library
221   add-ons in the tests/tap directory in that package.  It's also an
222   example of how to use this test harness in another package.
223
224   [1] https://www.eyrie.org/~eagle/software/rra-c-util/
225
226 SUPPORT
227
228   The C TAP Harness web page at:
229
230       https://www.eyrie.org/~eagle/software/c-tap-harness/
231
232   will always have the current version of this package, the current
233   documentation, and pointers to any additional resources.
234
235   For bug tracking, use the issue tracker on GitHub:
236
237       https://github.com/rra/c-tap-harness/issues
238
239   However, please be aware that I tend to be extremely busy and work
240   projects often take priority.  I'll save your report and get to it as
241   soon as I can, but it may take me a couple of months.
242
243 SOURCE REPOSITORY
244
245   C TAP Harness is maintained using Git.  You can access the current
246   source on GitHub at:
247
248       https://github.com/rra/c-tap-harness
249
250   or by cloning the repository at:
251
252       https://git.eyrie.org/git/devel/c-tap-harness.git
253
254   or view the repository via the web at:
255
256       https://git.eyrie.org/?p=devel/c-tap-harness.git
257
258   The eyrie.org repository is the canonical one, maintained by the author,
259   but using GitHub is probably more convenient for most purposes.  Pull
260   requests are gratefully reviewed and normally accepted.
261
262 LICENSE
263
264   The C TAP Harness package as a whole is covered by the following
265   copyright statement and license:
266
267     Copyright 2000-2001, 2004, 2006-2020 Russ Allbery <eagle@eyrie.org>
268     Copyright 2006-2009, 2011-2013
269         The Board of Trustees of the Leland Stanford Junior University
270
271     Permission is hereby granted, free of charge, to any person obtaining
272     a copy of this software and associated documentation files (the
273     "Software"), to deal in the Software without restriction, including
274     without limitation the rights to use, copy, modify, merge, publish,
275     distribute, sublicense, and/or sell copies of the Software, and to
276     permit persons to whom the Software is furnished to do so, subject to
277     the following conditions:
278
279     The above copyright notice and this permission notice shall be
280     included in all copies or substantial portions of the Software.
281
282     THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
283     EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
284     MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
285     IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
286     CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
287     TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
288     SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
289
290   Some files in this distribution are individually released under
291   different licenses, all of which are compatible with the above general
292   package license but which may require preservation of additional
293   notices.  All required notices, and detailed information about the
294   licensing of each file, are recorded in the LICENSE file.
295
296   Files covered by a license with an assigned SPDX License Identifier
297   include SPDX-License-Identifier tags to enable automated processing of
298   license information.  See https://spdx.org/licenses/ for more
299   information.
300
301   For any copyright range specified by files in this package as YYYY-ZZZZ,
302   the range specifies every single year in that closed interval.