tests/README.tests

   1 For users
   2 =========
   3
   4 To run the tests:
   5
   6   make check
   7   make check-valgrind
   8
   9 To test against the real VDDK library:
  10
  11   make check-vddk vddkdir=vmware-vix-disklib-distrib
  12
  13 Optionally:
  14
  15   sudo make check-root
  16
  17
  18 For developers
  19 ==============
  20
  21 This directory contains the nbdkit test suite.  It uses the automake
  22 Parallel Test Harness[1] to run the tests in parallel.  We prefer
  23 individual small tests as they are easier to parallelize and debug.
  24
  25 [1] https://www.gnu.org/software/automake/manual/html_node/Parallel-Test-Harness.html
  26
  27 Existing tests generally use one of these approaches:
  28
  29 (1) shell script + qemu-io.
  30
  31 (2) shell script + guestfish.
  32
  33 (3) shell script + nbdsh (preferred over (1) and (2), if possible).
  34
  35 (4) C program using libguestfs + test harness.  The test harness is
  36     described below.
  37
  38 (5) C program using libnbd (somewhat preferred over (4), if possible).
  39
  40
  41 Shell script tests
  42 ------------------
  43
  44 At the top of the shell script use:
  45
  46   source ./functions.sh
  47   set -e     # optional, depends on the test
  48   set -x     # optional, but usually better to have it
  49
  50 The ‘functions.sh’ script contains many useful functions that help
  51 with writing tests, specifying test prerequisites, and cleaning up.
  52
  53 Mosts tests will need one or more ‘requires’ lines in order to skip
  54 the test if required utilities are not available.  See existing tests
  55 for examples.
  56
  57 Before any shell script test will run, you must add it to ‘TESTS’ and
  58 ‘EXTRA_DIST’ in the ‘Makefile.am’ file.
  59
  60 There are many examples, eg. ‘tests/test-limit.sh’.
  61
  62
  63 To test a plugin using libnbd
  64 -----------------------------
  65
  66 Open a libnbd handle, and configure it using:
  67
  68   nbd_connect_command (nbd,
  69                        (char *[]) {
  70                          "nbdkit", "-s", "--exit-with-parent",
  71                          "plugin", <plugin args ...>, NULL });
  72
  73 Perform tests via libnbd functions.
  74
  75 Add the test to ‘LIBNBD_TESTS’ and ‘EXTRA_DIST’ in ‘Makefile.am’.
  76
  77 For an example, see ‘test-delay.c’.
  78
  79
  80 To test a plugin using libguestfs
  81 ---------------------------------
  82
  83 There is a small test harness to help with tests written in C using
  84 libguestfs (http://libguestfs.org).
  85
  86 #include "test.h"
  87
  88 Call at the beginning.  This starts the nbdkit server:
  89
  90   test_start_nbdkit ("plugin", <plugin args ...>, NULL)
  91
  92 Open a libguestfs handle, and configure the NBD client using:
  93
  94   guestfs_add_drive_opts (g, "",
  95                           GUESTFS_ADD_DRIVE_OPTS_FORMAT, "raw",
  96                           GUESTFS_ADD_DRIVE_OPTS_PROTOCOL, "nbd",
  97                           GUESTFS_ADD_DRIVE_OPTS_SERVER, server,
  98                           -1);
  99
 100 ‘server’ is a global that is initialized by ‘test_start_nbdkit’ and
 101 points to the nbdkit server socket.
 102
 103 Perform tests via libguestfs using the libguestfs device "/dev/sda",
 104 which corresponds to the NBD drive exposed by the plugin.
 105
 106 Close the handle and exit.  An atexit handler installed by
 107 ‘test_start_nbdkit’ cleans up the server automatically.
 108
 109 Add the test to ‘LIBGUESTFS_TESTS’ and ‘EXTRA_DIST’ in ‘Makefile.am’.
 110
 111 For an example, see ‘test-data.c’.