Merge tag 'debian/0.17-4'

[notmuch] / test / README

diff --git a/test/README b/test/README
index e0364e86652e6422c8172894d4dc16436ec06adc..79a9b1b2f9a15aba7466e4e5b1b308663dd1296c 100644 (file)
--- a/test/README
+++ b/test/README
@@ -56,7 +56,7 @@ The following command-line options are available when running tests:
        run the tests with this option in parallel.
 
 --root=<dir>::
        run the tests with this option in parallel.
 
 --root=<dir>::

-       This runs the testsuites specified under a seperate directory.
+       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.
        However, caution is advised, as not all tests are maintained
        with this relocation in mind, so some tests may behave
        differently.


@@ -69,12 +69,20 @@ can be specified as follows:
 
        make test OPTIONS="--verbose"
 
 
        make test OPTIONS="--verbose"
 

-You can choose an emacs binary to run the tests in one of the
-following ways.
+You can choose an emacs binary (and corresponding emacsclient) to run
+the tests in one of the following ways.

 
 

-       TEST_EMACS=my-special-emacs make test
-       TEST_EMACS=my-special-emacs ./emacs
-       make test TEST_EMACS=my-special-emacs
+       TEST_EMACS=my-special-emacs TEST_EMACSCLIENT=my-emacsclient make test
+       TEST_EMACS=my-special-emacs TEST_EMACSCLIENT=my-emacsclient ./emacs
+       make test TEST_EMACS=my-special-emacs TEST_EMACSCLIENT=my-emacsclient
+
+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
+failures and skips are still printed.

 
 Skipping Tests
 --------------
 
 Skipping Tests
 --------------


@@ -178,11 +186,18 @@ library for your script to use.
 
  test_expect_equal_file <file1> <file2>
 
 
  test_expect_equal_file <file1> <file2>
 

-   Identical to test_exepect_equal, except that <file1> and <file2>
+   Identical to test_expect_equal, except that <file1> and <file2>

    are files instead of strings.  This is a much more robust method to
    compare formatted textual information, since it also notices
    whitespace and closing newline differences.
 
    are files instead of strings.  This is a much more robust method to
    compare formatted textual information, since it also notices
    whitespace and closing newline differences.
 

+ test_expect_equal_json <output> <expected>
+
+   Identical to test_expect_equal, except that the two strings are
+   treated as JSON and canonicalized before equality testing.  This is
+   useful to abstract away from whitespace differences in the expected
+   output and that generated by running a notmuch command.
+

  test_debug <script>
 
    This takes a single argument, <script>, and evaluates it only
  test_debug <script>
 
    This takes a single argument, <script>, and evaluates it only


@@ -253,3 +268,16 @@ variables which are useful in writing tests:
     generated script that should be called instead of notmuch to do
     the counting.  The notmuch_counter_value() function prints the
     current counter value.
     generated script that should be called instead of notmuch to do
     the counting.  The notmuch_counter_value() function prints the
     current counter value.

+
+There are also functions which remove various environment-dependent
+values from notmuch output; these are useful to ensure that test
+results remain consistent across different machines.
+
+ notmuch_search_sanitize
+ notmuch_show_sanitize
+ notmuch_show_sanitize_all
+ notmuch_json_show_sanitize
+
+   All these functions should receive the text to be sanitized as the
+   input of a pipe, e.g.
+   output=`notmuch search "..." | notmuch_search_sanitize`