test: Add `test_emacs_expect_t'.

[notmuch] / test / README

diff --git a/test/README b/test/README
index 0b547480e5497e80b05c3001265ead2cb4f7dc9a..43656a35baf9f9bc5e5d41aca2b65c8e4e763450 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


@@ -13,7 +26,8 @@ notmuch-test script). Either command will run all available tests.
 
 Alternately, you can run a specific subset of tests by simply invoking
 one of the executable scripts in this directory, (such as ./search,
 
 Alternately, you can run a specific subset of tests by simply invoking
 one of the executable scripts in this directory, (such as ./search,

-./reply, etc.)
+./reply, etc). Note that you will probably want "make test-binaries"
+before running individual tests.

 
 The following command-line options are available when running tests:
 
 
 The following command-line options are available when running tests:
 


@@ -55,6 +69,13 @@ 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.
+
+       TEST_EMACS=my-special-emacs make test
+       TEST_EMACS=my-special-emacs ./emacs
+       make test TEST_EMACS=my-special-emacs
+

 Skipping Tests
 --------------
 If, for any reason, you need to skip one or more tests, you can do so
 Skipping Tests
 --------------
 If, for any reason, you need to skip one or more tests, you can do so


@@ -162,13 +183,6 @@ library for your script to use.
    robust method to compare formatted textual information, since it
    also notices whitespace and closing newline differences.
 
    robust method to compare formatted textual information, since it
    also notices whitespace and closing newline differences.
 

- test_expect_equal_failure <output> <expected>
-
-   This works similar to test_expect_equal (see above) but is used to
-   mark a test that demonstrates a known breakage, (that is, the
-   author of the test expects "output" and "expected" to differ until
-   the breakage is fixed). See test_expect_failure for details.
-

  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


@@ -188,14 +202,22 @@ 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
    is to summarize successes and failures in the test script and
    exit with an appropriate error code.
 
  test_done
 
    Your test script must have test_done at the end.  Its purpose
    is to summarize successes and failures in the test script and
    exit with an appropriate error code.
 

-There are also a number of mail-specific functions which are useful in
-writing tests:
+There are also a number of notmuch-specific auxiliary functions and
+variables which are useful in writing tests:

 
   generate_message
 
 
   generate_message
 


@@ -219,3 +241,15 @@ writing tests:
     will initialize the mail database to a known state of 50 sample
     messages, (culled from the early history of the notmuch mailing
     list).
     will initialize the mail database to a known state of 50 sample
     messages, (culled from the early history of the notmuch mailing
     list).

+
+  notmuch_counter_reset
+  $notmuch_counter_command
+  notmuch_counter_value
+
+    These allow to count how many times notmuch binary is called.
+    notmuch_counter_reset() function generates a script that counts
+    how many times it is called and resets the counter to zero.  The
+    function sets $notmuch_counter_command variable to the path to the
+    generated script that should be called instead of notmuch to do
+    the counting.  The notmuch_counter_value() function prints the
+    current counter value.