]> git.notmuchmail.org Git - notmuch/blob - test/README
emacs: Use new advice mechanism do advice mm-shr
[notmuch] / test / README
1 Notmuch test suite
2 ==================
3 This directory contains the test suite for notmuch.
4
5 When fixing bugs or enhancing notmuch, you are strongly encouraged to
6 add tests in this directory to cover what you are trying to fix or
7 enhance.
8
9 Prerequisites
10 -------------
11 The test system itself requires:
12
13   - bash(1) version 4.0 or newer
14
15 Without bash 4.0+ the tests just refuse to run.
16
17 Some tests require external dependencies to run. Without them, they
18 will be skipped, or (rarely) marked failed. Please install these, so
19 that you know if you break anything.
20
21   - GNU tar(1)
22   - dtach(1)
23   - emacs(1)
24   - emacsclient(1)
25   - gdb(1)
26   - gpg(1)
27   - python(1)
28
29 If your system lacks these tools or have older, non-upgradable versions
30 of these, please (possibly compile and) install these to some other
31 path, for example /usr/local/bin or /opt/gnu/bin. Then prepend the
32 chosen directory to your PATH before running the tests.
33
34 e.g. env PATH=/opt/gnu/bin:$PATH make test
35
36 For FreeBSD you need to install latest gdb from ports or packages and
37 provide path to it in TEST_GDB environment variable before executing
38 the tests, native FreeBSD gdb does not not work.  If you install
39 coreutils, which provides GNU versions of basic utils like 'date' and
40 'base64' on FreeBSD, the test suite will use these instead of the
41 native ones. This provides robustness against portability issues with
42 these system tools. Most often the tests are written, reviewed and
43 tested on Linux system so such portability issues arise from time to
44 time.
45
46 Running Tests
47 -------------
48 The easiest way to run tests is to say "make test", (or simply run the
49 notmuch-test script). Either command will run all available tests.
50
51 Alternately, you can run a specific subset of tests by simply invoking
52 one of the executable scripts in this directory, (such as ./T*-search.sh,
53 ./T*-reply.sh, etc). Note that you will probably want "make test-binaries"
54 before running individual tests.
55
56 The following command-line options are available when running tests:
57
58 --debug::
59         This may help the person who is developing a new test.
60         It causes the command defined with test_debug to run.
61
62 --immediate::
63         This causes the test to immediately exit upon the first
64         failed test.
65
66 --valgrind::
67         Execute notmuch with valgrind and exit with status
68         126 on errors (just like regular tests, this will only stop
69         the test script when running under -i).  Valgrind errors
70         go to stderr, so you might want to pass the -v option, too.
71
72         Since it makes no sense to run the tests with --valgrind and
73         not see any output, this option implies --verbose.  For
74         convenience, it also implies --tee.
75
76 --tee::
77         In addition to printing the test output to the terminal,
78         write it to files named 't/test-results/$TEST_NAME.out'.
79         As the names depend on the tests' file names, it is safe to
80         run the tests with this option in parallel.
81
82 Certain tests require precomputed databases to complete. You can fetch these
83 databases with
84
85         make download-test-databases
86
87 If you do not download the test databases, the relevant tests will be
88 skipped.
89
90 When invoking the test suite via "make test" any of the above options
91 can be specified as follows:
92
93         make test OPTIONS="--verbose"
94
95 You can choose an emacs binary (and corresponding emacsclient) to run
96 the tests in one of the following ways.
97
98         TEST_EMACS=my-emacs TEST_EMACSCLIENT=my-emacsclient make test
99         TEST_EMACS=my-emacs TEST_EMACSCLIENT=my-emacsclient ./T*-emacs.sh
100         make test TEST_EMACS=my-emacs TEST_EMACSCLIENT=my-emacsclient
101
102 Some tests may require a c compiler. You can choose the name and flags similarly
103 to with emacs, e.g.
104
105      make test TEST_CC=gcc TEST_CFLAGS="-g -O2"
106
107 Parallel Execution
108 ------------------
109 If either the moreutils or GNU "parallel" utility is available all
110 tests will be run in parallel.  If the NOTMUCH_TEST_SERIALIZE variable
111 is non-null all tests will be executed sequentially.
112
113 Quiet Execution
114 ---------------
115 Normally, when new script starts and when test PASSes you get a message
116 printed on screen. This printing can be disabled by setting the
117 NOTMUCH_TEST_QUIET variable to a non-null value. Message on test
118 failures and skips are still printed.
119
120 Skipping Tests
121 --------------
122 If, for any reason, you need to skip one or more tests, you can do so
123 by setting the NOTMUCH_SKIP_TESTS variable to the name of one or more
124 sections of tests.
125
126 For example:
127
128     $ NOTMUCH_SKIP_TESTS="search reply" make test
129
130 Even more fine-grained skipping is possible by appending a test number
131 (or glob pattern) after the section name. For example, the first
132 search test and the second reply test could be skipped with:
133
134     $ NOTMUCH_SKIP_TESTS="search.1 reply.2" make test
135
136 Note that some tests in the existing test suite rely on previous test
137 items, so you cannot arbitrarily skip any test and expect the
138 remaining tests to be unaffected.
139
140 Currently we do not consider skipped tests as build failures. For
141 maximum robustness, when setting up automated build processes, you
142 should explicitly skip tests, rather than relying on notmuch's
143 detection of missing prerequisites. In the future we may treat tests
144 unable to run because of missing prerequisites, but not explicitly
145 skipped by the user, as failures.
146
147 Writing Tests
148 -------------
149 The test script is written as a shell script. It is to be named as
150 Tddd-testname.sh where 'ddd' is three digits and 'testname' the "bare"
151 name of your test. Tests will be run in order the 'ddd' part determines.
152
153 The test script should start with the standard "#!/usr/bin/env bash"
154 and an assignment to variable 'test_description', like this:
155
156         #!/usr/bin/env bash
157
158         test_description='xxx test (option --frotz)
159
160         This test exercises the "notmuch xxx" command when
161         given the option --frotz.'
162
163 Source 'test-lib.sh'
164 --------------------
165 After assigning test_description, the test script should source
166 test-lib.sh like this:
167
168         . ./test-lib.sh || exit 1
169
170 This test harness library does the following things:
171
172  - If the script is invoked with command line argument --help
173    (or -h), it shows the test_description and exits.
174
175  - Creates a temporary directory with default notmuch-config and a
176    mail store with a corpus of mail, (initially, 50 early messages
177    sent to the notmuch list). This directory is
178    test/tmp.<test-basename>. The path to notmuch-config is exported in
179    NOTMUCH_CONFIG environment variable and mail store path is stored
180    in MAIL_DIR variable.
181
182  - Defines standard test helper functions for your scripts to
183    use.  These functions are designed to make all scripts behave
184    consistently when command line arguments --verbose (or -v),
185    --debug (or -d), and --immediate (or -i) is given.
186
187 End with test_done
188 ------------------
189 Your script will be a sequence of tests, using helper functions
190 from the test harness library.  At the end of the script, call
191 'test_done'.
192
193 Test harness library
194 --------------------
195 There are a handful helper functions defined in the test harness
196 library for your script to use.
197
198  test_begin_subtest <message>
199
200    Set the test description message for a subsequent test_expect_*
201    invocation (see below).
202
203  test_expect_success <script>
204
205    This takes a string as parameter, and evaluates the
206    <script>.  If it yields success, test is considered
207    successful.
208
209  test_expect_code <code> <script>
210
211    This takes two strings as parameter, and evaluates the <script>.
212    If it yields <code> exit status, test is considered successful.
213
214  test_subtest_known_broken
215
216    Mark the current test as broken.  Such tests are expected to fail.
217    Unlike the normal tests, which say "PASS" on success and "FAIL" on
218    failure, these will say "FIXED" on success and "BROKEN" on failure.
219    Failures from these tests won't cause -i (immediate) to stop.  A
220    test must call this before any test_expect_* function.
221
222  test_expect_equal <output> <expected>
223
224    This is an often-used convenience function built on top of
225    test_expect_success. It uses the message from the last
226    test_begin_subtest call, so call before calling
227    test_expect_equal. This function generates a successful test if
228    both the <output> and <expected> strings are identical. If not, it
229    will generate a failure and print the difference of the two
230    strings.
231
232  test_expect_equal_file <file1> <file2>
233
234    Identical to test_expect_equal, except that <file1> and <file2>
235    are files instead of strings.  This is a much more robust method to
236    compare formatted textual information, since it also notices
237    whitespace and closing newline differences.
238
239  test_expect_equal_json <output> <expected>
240
241    Identical to test_expect_equal, except that the two strings are
242    treated as JSON and canonicalized before equality testing.  This is
243    useful to abstract away from whitespace differences in the expected
244    output and that generated by running a notmuch command.
245
246  test_debug <script>
247
248    This takes a single argument, <script>, and evaluates it only
249    when the test script is started with --debug command line
250    argument.  This is primarily meant for use during the
251    development of a new test script.
252
253  test_emacs <emacs-lisp-expressions>
254
255    This function executes the provided emacs lisp script within
256    emacs. The script can be a sequence of emacs lisp expressions,
257    (that is, they will be evaluated within a progn form). Emacs
258    stdout and stderr is not available, the common way to get output
259    is to save it to a file. There are some auxiliary functions
260    useful in emacs tests provided in test-lib.el. Do not use `setq'
261    for setting variables in Emacs tests because it affects other
262    tests that may run in the same Emacs instance.  Use `let' instead
263    so the scope of the changed variables is limited to a single test.
264
265  test_emacs_expect_t <emacs-lisp-expressions>
266
267   This function executes the provided emacs lisp script within
268   emacs in a manner similar to 'test_emacs'. The expressions should
269   return the value `t' to indicate that the test has passed. If the
270   test does not return `t' then it is considered failed and all data
271   returned by the test is reported to the tester.
272
273  test_done
274
275    Your test script must have test_done at the end.  Its purpose
276    is to summarize successes and failures in the test script and
277    exit with an appropriate error code.
278
279 There are also a number of notmuch-specific auxiliary functions and
280 variables which are useful in writing tests:
281
282   generate_message
283
284     Generates a message with an optional template. Most tests will
285     actually prefer to call add_message. See below.
286
287   add_message
288
289     Generate a message and add it to the database (by calling "notmuch
290     new"). It is sufficient to simply call add_message with no
291     arguments if you don't care about the content of the message. If
292     more control is needed, arguments can be provide to specify many
293     different header values for the new message. See the documentation
294     within test-lib.sh or refer to many example calls within existing
295     tests.
296
297   add_email_corpus
298
299     This function should be called at the beginning of a test file
300     when a test needs to operate on a non-empty body of messages. It
301     will initialize the mail database to a known state of 50 sample
302     messages, (culled from the early history of the notmuch mailing
303     list).
304
305   notmuch_counter_reset
306   $notmuch_counter_command
307   notmuch_counter_value
308
309     These allow to count how many times notmuch binary is called.
310     notmuch_counter_reset() function generates a script that counts
311     how many times it is called and resets the counter to zero.  The
312     function sets $notmuch_counter_command variable to the path to the
313     generated script that should be called instead of notmuch to do
314     the counting.  The notmuch_counter_value() function prints the
315     current counter value.
316
317 There are also functions which remove various environment-dependent
318 values from notmuch output; these are useful to ensure that test
319 results remain consistent across different machines.
320
321  notmuch_search_sanitize
322  notmuch_show_sanitize
323  notmuch_show_sanitize_all
324  notmuch_json_show_sanitize
325
326    All these functions should receive the text to be sanitized as the
327    input of a pipe, e.g.
328    output=`notmuch search "..." | notmuch_search_sanitize`