cli: use designated initializer to initialize add_files_state

[notmuch] / test / README

diff --git a/test/README b/test/README
index bde6db0c04a4979ea29ac1451e5d0e6b80b8fb50..e54e36b795e852e536dab96256420edbfee84368 100644 (file)
--- a/test/README
+++ b/test/README
@@ -6,6 +6,19 @@ When fixing bugs or enhancing notmuch, you are strongly encouraged to
 add tests in this directory to cover what you are trying to fix or
 enhance.
 
 add tests in this directory to cover what you are trying to fix or
 enhance.
 

+Prerequisites
+-------------
+Some tests require external dependencies to run. Without them, they
+will be skipped, or (rarely) marked failed. Please install these, so
+that you know if you break anything.
+
+  - dtach(1)
+  - emacs(1)
+  - emacsclient(1)
+  - gdb(1)
+  - gpg(1)
+  - python(1)
+

 Running Tests
 -------------
 The easiest way to run tests is to say "make test", (or simply run the
 Running Tests
 -------------
 The easiest way to run tests is to say "make test", (or simply run the


@@ -43,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.


@@ -51,17 +64,38 @@ The following command-line options are available when running tests:
        Pointing this argument at a tmpfs filesystem can improve the
        speed of the test suite for some users.
 
        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:
 
        make test OPTIONS="--verbose"
 
 When invoking the test suite via "make test" any of the above options
 can be specified as follows:
 
        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 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
+
+Some tests may require a c compiler. You can choose the name and flags similarly
+to with emacs, e.g.
+
+     make test TEST_CC=gcc TEST_CFLAGS="-g -O2"

 
 

-       TEST_EMACS=my-special-emacs make test
-       TEST_EMACS=my-special-emacs ./emacs
-       make test TEST_EMACS=my-special-emacs
+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
 --------------


@@ -83,6 +117,13 @@ Note that some tests in the existing test suite rely on previous test
 items, so you cannot arbitrarily skip any test and expect the
 remaining tests to be unaffected.
 
 items, so you cannot arbitrarily skip any test and expect the
 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
+detection of missing prerequisites. In the future we may treat tests
+unable to run because of missing prerequisites, but not explicitely
+skipped by the user, as failures.
+

 Writing Tests
 -------------
 The test script is written as a shell script.  It should start with
 Writing Tests
 -------------
 The test script is written as a shell script.  It should start with


@@ -104,7 +145,7 @@ Source 'test-lib.sh'
 After assigning test_description, the test script should source
 test-lib.sh like this:
 
 After assigning test_description, the test script should source
 test-lib.sh like this:
 

-       . ./test-lib.sh
+       . ./test-lib.sh || exit 1

 
 This test harness library does the following things:
 
 
 This test harness library does the following things:
 


@@ -163,12 +204,19 @@ library for your script to use.
    will generate a failure and print the difference of the two
    strings.
 
    will generate a failure and print the difference of the two
    strings.
 

- test_expect_equal_file <output> <expected>
+ test_expect_equal_file <file1> <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.

 
 

-   Identical to test_exepect_equal, except that <output> and
-   <expected> 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>
 
 
  test_debug <script>
 


@@ -189,6 +237,14 @@ library for your script to use.
    tests that may run in the same Emacs instance.  Use `let' instead
    so the scope of the changed variables is limited to a single test.
 
    tests that may run in the same Emacs instance.  Use `let' instead
    so the scope of the changed variables is limited to a single test.
 

+ test_emacs_expect_t <emacs-lisp-expressions>
+
+  This function executes the provided emacs lisp script within
+  emacs in a manner similar to 'test_emacs'. The expressions should
+  return the value `t' to indicate that the test has passed. If the
+  test does not return `t' then it is considered failed and all data
+  returned by the test is reported to the tester.
+

  test_done
 
    Your test script must have test_done at the end.  Its purpose
  test_done
 
    Your test script must have test_done at the end.  Its purpose


@@ -232,3 +288,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`