X-Git-Url: https://git.notmuchmail.org/git?a=blobdiff_plain;f=test%2FREADME;h=a81808b164f0cec0ec6c0010cb023fe77d7e098c;hb=b49377e5093e1c8af801e1065ef086a0cd15625a;hp=f2499bce780bdda3ae1c17242aab4f00d9ad8252;hpb=1ec634461ea25d87cc16dbeb1318f8e30a07c9f1;p=notmuch
diff --git a/test/README b/test/README
index f2499bce..a81808b1 100644
--- a/test/README
+++ b/test/README
@@ -25,8 +25,9 @@ that you know if you break anything.
- gdb(1)
- gpg(1)
- python(1)
+ - xapian-metadata(1)
-If your system lacks these tools or have older, non-upgreable versions
+If your system lacks these tools or have older, non-upgradable versions
of these, please (possibly compile and) install these to some other
path, for example /usr/local/bin or /opt/gnu/bin. Then prepend the
chosen directory to your PATH before running the tests.
@@ -43,7 +44,6 @@ these system tools. Most often the tests are written, reviewed and
tested on Linux system so such portability issues arise from time to
time.
-
Running Tests
-------------
The easiest way to run tests is to say "make test", (or simply run the
@@ -80,23 +80,6 @@ The following command-line options are available when running tests:
As the names depend on the tests' file names, it is safe to
run the tests with this option in parallel.
---root=
::
- This runs the testsuites specified under a separate directory.
- However, caution is advised, as not all tests are maintained
- with this relocation in mind, so some tests may behave
- differently.
-
- Pointing this argument at a tmpfs filesystem can improve the
- speed of the test suite for some users.
-
-Certain tests require precomputed databases to complete. You can fetch these
-databases with
-
- make download-test-databases
-
-If you do not download the test databases, the relevant tests will be
-skipped.
-
When invoking the test suite via "make test" any of the above options
can be specified as follows:
@@ -114,9 +97,14 @@ to with emacs, e.g.
make test TEST_CC=gcc TEST_CFLAGS="-g -O2"
+Parallel Execution
+------------------
+If either the moreutils or GNU "parallel" utility is available all
+tests will be run in parallel. If the NOTMUCH_TEST_SERIALIZE variable
+is non-null all tests will be executed sequentially.
+
Quiet Execution
---------------
-
Normally, when new script starts and when test PASSes you get a message
printed on screen. This printing can be disabled by setting the
NOTMUCH_TEST_QUIET variable to a non-null value. Message on test
@@ -144,11 +132,28 @@ remaining tests to be unaffected.
Currently we do not consider skipped tests as build failures. For
maximum robustness, when setting up automated build processes, you
-should explicitely skip tests, rather than relying on notmuch's
+should explicitly skip tests, rather than relying on notmuch's
detection of missing prerequisites. In the future we may treat tests
-unable to run because of missing prerequisites, but not explicitely
+unable to run because of missing prerequisites, but not explicitly
skipped by the user, as failures.
+Testing installed notmuch
+-------------------------
+
+Systems integrators (e.g. Linux distros) may wish to test an installed
+version of notmuch. This can be done be running
+
+ $ NOTMUCH_TEST_INSTALLED=1 ./test/notmuch-test
+
+In this scenario the test suite does not assume a built tree, and in
+particular cannot rely on the output of 'configure'. You may want to
+set certain feature environment variables ('NOTMUCH_HAVE_*') directly
+if you know those apply to your installed notmuch). Consider also
+setting TERM=dumb if the value of TERM cannot be used (e.g. in a
+chroot with missing terminfo). Note that having a built tree may cause
+surprising/broken results for NOTMUCH_TEST_INSTALLED, so consider
+cleaning first.
+
Writing Tests
-------------
The test script is written as a shell script. It is to be named as