tests/README.md

   1 # multipath-tools unit tests
   2
   3 Unit tests are built and run by running `make test` in the top directory,
   4 or simply `make` in the `tests` subdirectory. The test output is saved as
   5 `<testname>.out`. The test programs are called `<testname>-test`, and can
   6 be run standalone e.g. for debugging purposes.
   7
   8 ## Notes on individual tests
   9
  10 ### Tests that require root permissions
  11
  12 The following tests must be run as root, otherwise some test items will be
  13 skipped because of missing permissions, or the test will fail outright:
  14
  15  * `dmevents`
  16  * `directio` (if `DIO_TEST_DEV` is set, see below)
  17
  18 To run these tests, after building the tests as non-root user, change to the
  19 `tests` directory and run `make test-clean`; then run `make` again as root.
  20
  21 ### directio test
  22
  23 This test includes test items that require a access to a block device. The
  24 device will be opened in read-only mode; you don't need to worry about data
  25 loss. However, the user needs to specify a device to be used. Set the
  26 environment variable `DIO_TEST_DEV` to the path of the device.
  27 Alternatively, create a file `directio_test_dev` under
  28 the `tests` directory containting a single line that sets this environment
  29 variable in Bourne Shell syntax, like this:
  30
  31     DIO_TEST_DEV=/dev/sdc3
  32
  33 After that, run `make directio.out` as root in the `tests` directory to
  34 perform the test.
  35
  36 ## Adding tests
  37
  38 The unit tests are based on the [cmocka test framework](https://cmocka.org/),
  39 and make use of cmocka's "mock objects" feature to simulate how the code behaves
  40 for different input values. cmocka achieves this by modifying the symbol
  41 lookup at link time, substituting "wrapper functions" for the originally
  42 called function. The Makefile contains code to make sure that `__wrap_xyz()`
  43 wrapper functions are automatically passed to the linker with matching
  44 `-Wl,--wrap` command line arguments, so that tests are correctly rebuilt if
  45 wrapper functions are added or removed.
  46
  47 ### Making sure symbol wrapping works: OBJDEPS
  48
  49 Special care must be taken to wrap function calls inside a library. Suppose you want
  50 to wrap a function which is both defined in libmultipath and called from other
  51 functions in libmultipath, such as `checker_check()`. When `libmultipath.so` is
  52 created, the linker resolves calls to `checker_check()` inside the `.so`
  53 file. When later the test executable is built by linking the test object file with
  54 `libmultipath.so`, these calls can't be wrapped any more, because they've
  55 already been resolved, and wrapping works only for *unresolved* symbols.
  56 Therefore, object files from libraries that contain calls to functions
  57 which need to be wrapped must be explicitly listed on the linker command line
  58 in order to make the wrapping work. To enforce this, add these object files to
  59 the `xyz-test_OBJDEPS` variable in the Makefile.
  60
  61 ### Using wrapper function libraries: TESTDEPS
  62
  63 Some wrapper functions are useful in multiple tests. These are maintained in
  64 separate input files, such as `test-lib.c` or `test-log.c`. List these files
  65 in the `xyz-test_TESTDEPS` variable for your test program if you need these
  66 wrappers.
  67
  68 ### Specifying library dependencies: LIBDEPS
  69
  70 In order to keep the tests lean, not all libraries that libmultipath
  71 normally pulls in are used for every test. Add libraries you need (such as
  72 `-lpthread`) to the `xyz-test_LIBDEPS` variable.