tests: add README.md
authorMartin Wilck <mwilck@suse.com>
Mon, 2 Mar 2020 22:20:25 +0000 (23:20 +0100)
committerChristophe Varoqui <christophe.varoqui@opensvc.com>
Mon, 4 May 2020 13:10:29 +0000 (15:10 +0200)
Add a README explaining how to run the tests, and some of less obvious
stuff in the Makefile.

Signed-off-by: Martin Wilck <mwilck@suse.com>
tests/README.md [new file with mode: 0644]

diff --git a/tests/README.md b/tests/README.md
new file mode 100644 (file)
index 0000000..6438a82
--- /dev/null
@@ -0,0 +1,72 @@
+# multipath-tools unit tests
+
+Unit tests are built and run by running `make test` in the top directory,
+or simply `make` in the `tests` subdirectory. The test output is saved as
+`<testname>.out`. The test programs are called `<testname>-test`, and can
+be run standalone e.g. for debugging purposes.
+
+## Notes on individual tests
+
+### Tests that require root permissions
+
+The following tests must be run as root, otherwise some test items will be
+skipped because of missing permissions, or the test will fail outright:
+
+ * `dmevents`
+ * `directio` (if `DIO_TEST_DEV` is set, see below)
+
+To run these tests, after building the tests as non-root user, change to the
+`tests` directory and run `make test-clean`; then run `make` again as root.
+
+### directio test
+
+This test includes test items that require a access to a block device. The
+device will be opened in read-only mode; you don't need to worry about data
+loss. However, the user needs to specify a device to be used. Set the
+environment variable `DIO_TEST_DEV` to the path of the device.
+Alternatively, create a file `directio_test_dev` under
+the `tests` directory containting a single line that sets this environment
+variable in Bourne Shell syntax, like this:
+
+    DIO_TEST_DEV=/dev/sdc3
+
+After that, run `make directio.out` as root in the `tests` directory to
+perform the test.
+
+## Adding tests
+
+The unit tests are based on the [cmocka test framework](https://cmocka.org/),
+and make use of cmocka's "mock objects" feature to simulate how the code behaves
+for different input values. cmocka achieves this by modifying the symbol
+lookup at link time, substituting "wrapper functions" for the originally
+called function. The Makefile contains code to make sure that `__wrap_xyz()`
+wrapper functions are automatically passed to the linker with matching
+`-Wl,--wrap` command line arguments, so that tests are correctly rebuilt if
+wrapper functions are added or removed.
+
+### Making sure symbol wrapping works: OBJDEPS
+
+Special care must be taken to wrap function calls inside a library. Suppose you want
+to wrap a function which is both defined in libmultipath and called from other
+functions in libmultipath, such as `checker_check()`. When `libmultipath.so` is
+created, the linker resolves calls to `checker_check()` inside the `.so`
+file. When later the test executable is built by linking the test object file with
+`libmultipath.so`, these calls can't be wrapped any more, because they've
+already been resolved, and wrapping works only for *unresolved* symbols.
+Therefore, object files from libraries that contain calls to functions
+which need to be wrapped must be explicitly listed on the linker command line
+in order to make the wrapping work. To enforce this, add these object files to
+the `xyz-test_OBJDEPS` variable in the Makefile.
+
+### Using wrapper function libraries: TESTDEPS
+
+Some wrapper functions are useful in multiple tests. These are maintained in
+separate input files, such as `test-lib.c` or `test-log.c`. List these files
+in the `xyz-test_TESTDEPS` variable for your test program if you need these
+wrappers.
+
+### Specifying library dependencies: LIBDEPS
+
+In order to keep the tests lean, not all libraries that libmultipath
+normally pulls in are used for every test. Add libraries you need (such as
+`-lpthread`) to the `xyz-test_LIBDEPS` variable.