Blame libarchive/test/README

Packit 08bd4c
$FreeBSD: src/lib/libarchive/test/README,v 1.3 2008/01/01 22:28:04 kientzle Exp $
Packit 08bd4c
Packit 08bd4c
This is the test harness for libarchive.
Packit 08bd4c
Packit 08bd4c
It compiles into a single program "libarchive_test" that is intended
Packit 08bd4c
to exercise as much of the library as possible.  It is, of course,
Packit 08bd4c
very much a work in progress.
Packit 08bd4c
Packit 08bd4c
Each test is a function named test_foo in a file named test_foo.c.
Packit 08bd4c
Note that the file name is the same as the function name.
Packit 08bd4c
Each file must start with this line:
Packit 08bd4c
Packit 08bd4c
  #include "test.h"
Packit 08bd4c
Packit 08bd4c
The test function must be declared with a line of this form
Packit 08bd4c
Packit 08bd4c
  DEFINE_TEST(test_foo)
Packit 08bd4c
Packit 08bd4c
Nothing else should appear on that line.
Packit 08bd4c
Packit 08bd4c
When you add a test, please update the top-level Makefile.am and the
Packit 08bd4c
CMakeLists.txt in this directory to add your file to the list of
Packit 08bd4c
tests.  The Makefile and main.c use various macro trickery to
Packit 08bd4c
automatically collect a list of test functions to be invoked.
Packit 08bd4c
Packit 08bd4c
Each test function can rely on the following:
Packit 08bd4c
Packit 08bd4c
  * The current directory will be a freshly-created empty directory
Packit 08bd4c
    suitable for that test.  (The top-level main() creates a
Packit 08bd4c
    directory for each separate test and chdir()s to that directory
Packit 08bd4c
    before running the test.)
Packit 08bd4c
Packit 08bd4c
  * The test function should use assert(), assertA() and similar macros
Packit 08bd4c
    defined in test.h.  If you need to add new macros of this form, feel
Packit 08bd4c
    free to do so.  The current macro set includes assertEqualInt() and
Packit 08bd4c
    assertEqualString() that print out additional detail about their
Packit 08bd4c
    arguments if the assertion does fail.  'A' versions also accept
Packit 08bd4c
    a struct archive * and display any error message from there on
Packit 08bd4c
    failure.
Packit 08bd4c
Packit 08bd4c
  * You are encouraged to document each assertion with a failure() call
Packit 08bd4c
    just before the assert.  The failure() function is a printf-like
Packit 08bd4c
    function whose text is displayed only if the assertion fails.  It
Packit 08bd4c
    can be used to display additional information relevant to the failure:
Packit 08bd4c
Packit 08bd4c
       failure("The data read from file %s did not match the data written to that file.", filename);
Packit 08bd4c
       assert(strcmp(buff1, buff2) == 0);
Packit 08bd4c
Packit 08bd4c
  * Tests are encouraged to be economical with their memory and disk usage,
Packit 08bd4c
    though this is not essential.  The test is occasionally run under
Packit 08bd4c
    a memory debugger to try to locate memory leaks in the library;
Packit 08bd4c
    as a result, tests should be careful to release any memory they
Packit 08bd4c
    allocate.
Packit 08bd4c
Packit 08bd4c
  * Disable tests on specific platforms as necessary.  Please avoid
Packit 08bd4c
    using config.h to adjust feature requirements, as I want the tests
Packit 08bd4c
    to also serve as a check on the configure process.  The following
Packit 08bd4c
    form is usually more appropriate:
Packit 08bd4c
Packit 08bd4c
#if !defined(__PLATFORM) && !defined(__Platform2__)
Packit 08bd4c
    assert(xxxx)
Packit 08bd4c
#endif
Packit 08bd4c