1 files changed, 137 insertions, 0 deletions
diff --git a/Documentation/howto-tests.txt b/Documentation/howto-tests.txt
new file mode 100644
index 0000000..71c7f85
--- /dev/null
+++ b/Documentation/howto-tests.txt
@@ -0,0 +1,137 @@
+
+ util-linux regression tests
+ ~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+ It's expected that for each invasive change or important bugfix you will
+ include a test to your patch.
+
+ Compile tests & run basic tests:
+
+	$ make check
+
+ Note that the configure option --disable-static disables many of libmount and
+ libblkid unit tests.
+
+ Run all tests including tests that require root permissions:
+
+	# cd tests
+	# ./run.sh [--verbose] [--memcheck]
+
+	Alternatively using sudo and make:
+
+	$ make check TS_COMMAND="true"
+	$ sudo -E make check TS_OPTS="--parallel=1"
+
+ note that as root you have to manually remove output and diff directories
+
+	# rm -rf output diff
+
+ or run 'make clean' as root.
+
+
+ Run subset of tests:
+
+	$ ./run.sh <test_directory-name>
+
+        for example:
+
+              $ ./run.sh blkid
+              $ ./run.sh libmount
+
+ The tests is possible to exclude by ./run.sh --exclude=<list>  where the
+ <list> is blank separated test names in format "testdir/testname", for example:
+
+	$ ./run.sh --exclude="mount/move"
+
+ The --exclude is evaluated by the ./run.sh script only. See below
+
+	TS_OPT_testdir_[testscript_]fake=
+
+ environment variable which provides more powerful functionality to skip tests.
+
+
+ *** WARNING for root users ***
+
+ The tests touch your /etc/fstab, initialize loop devices or scsi_debug devices
+ if executed with root permissions.
+
+ Please, be careful and use these tests only for development and never on
+ production system.
+
+
+environment variables
+---------------------
+
+TS_COMMAND
+
+    Evaluated by "make check" to override the default command (run.sh).
+    Example:
+      - build all test dependencies, but skip the actual test
+        $ make check TS_COMMAND="true"
+
+TS_OPTS
+
+    Evaluated by "make check" to pass options.to run.sh (see ./run.sh --help).
+    Examples:
+      - run utmp tests only
+        $ make check TS_OPTS="--parallel=1 utmp"
+
+TS_OPT_testdir_[testscript_]fake="<yes|no>"
+
+    Evaluated by any test script to skip certain tests.
+    Examples:
+      - skip all the tests within "fdisk" test-directory:
+        $ make check TS_OPT_fdisk_fake="yes"
+
+      - skip only "fdisk/bsd" test:
+        $ make check TS_OPT_fdisk_bsd_fake="yes"
+
+      - skip all "fdisk" tests except fdisk/bsd:
+        $ make check TS_OPT_fdisk_fake="yes" TS_OPT_fdisk_bsd_fake="no"
+
+TS_OPT_testdir_[testscript_]known_fail="<yes|no>"
+
+    Similar usage like TS_OPT_*_fake above. "known_fail" means that the given
+    test will run but (negative) results will be ignored. The build log and test
+    diffs will still remind you about the issue.
+
+TS_OPT_testdir_[testscript_]verbose="<yes|no>"
+
+    Set verbosity for certain tests. Similar usage like TS_OPT_*_fake above.
+
+TS_OPT_testdir_[testscript_]memcheck="<yes|no>"
+
+    Run certain tests with valgrind. Similar usage like TS_OPT_*_fake above.
+
+
+External services 
+-----------------
+
+Travis CI - automatically executed for all github commits.
+
+    URL: https://travis-ci.org/karelzak/util-linux/
+
+    See .travis.yml for more details.
+
+    We require "sudo" to install additional stuff and to run the tests with
+    UID=0, it means that tests are executed on travis "legacy infrastructure".
+
+
+Drone.io - automatically executed for all github commits.
+
+    URL: https://drone.io/github.com/karelzak/util-linux
+
+    The drone.io does not use any in-tree config file (like travis-ci), the
+    currently used configuration (maintained by Drone.io web UI):
+
+	MAKE_CHECK="root"
+	MAKE_CHECK_OPTS="--skip-loopdevs --exclude=mount/move"
+	source ./.travis-functions.sh
+	travis_install_script || exit
+	travis_before_script || exit
+	ret=0
+	travis_script || ret=$?
+	travis_after_script
+	exit $ret  
+	
+    yes, it shares the setup functions with travis-ci.