- - test_tick
-
- Make commit and tag names consistent by setting the author and
- committer times to defined stated. Subsequent calls will
- advance the times by a fixed amount.
-
- - test_commit <message> [<filename> [<contents>]]
-
- Creates a commit with the given message, committing the given
- file with the given contents (default for both is to reuse the
- message string), and adds a tag (again reusing the message
- string as name). Calls test_tick to make the SHA-1s
- reproducible.
-
- - test_merge <message> <commit-or-tag>
-
- Merges the given rev using the given message. Like test_commit,
- creates a tag and calls test_tick before committing.
-
-Tips for Writing Tests
-----------------------
-
-As with any programming projects, existing programs are the best
-source of the information. However, do _not_ emulate
-t0000-basic.sh when writing your tests. The test is special in
-that it tries to validate the very core of GIT. For example, it
-knows that there will be 256 subdirectories under .git/objects/,
-and it knows that the object ID of an empty tree is a certain
-40-byte string. This is deliberately done so in t0000-basic.sh
-because the things the very basic core test tries to achieve is
-to serve as a basis for people who are changing the GIT internal
-drastically. For these people, after making certain changes,
-not seeing failures from the basic test _is_ a failure. And
-such drastic changes to the core GIT that even changes these
-otherwise supposedly stable object IDs should be accompanied by
-an update to t0000-basic.sh.
-
-However, other tests that simply rely on basic parts of the core
-GIT working properly should not have that level of intimate
-knowledge of the core GIT internals. If all the test scripts
-hardcoded the object IDs like t0000-basic.sh does, that defeats
-the purpose of t0000-basic.sh, which is to isolate that level of
-validation in one place. Your test also ends up needing
-updating when such a change to the internal happens, so do _not_
-do it and leave the low level of validation to t0000-basic.sh.
+There are also a number of notmuch-specific auxiliary functions and
+variables which are useful in writing tests:
+
+ generate_message
+
+ Generates a message with an optional template. Most tests will
+ actually prefer to call add_message. See below.
+
+ add_message
+
+ Generate a message and add it to the database (by calling "notmuch
+ new"). It is sufficient to simply call add_message with no
+ arguments if you don't care about the content of the message. If
+ more control is needed, arguments can be provide to specify many
+ different header values for the new message. See the documentation
+ within test-lib.sh or refer to many example calls within existing
+ tests.
+
+ add_email_corpus
+
+ This function should be called at the beginning of a test file
+ when a test needs to operate on a non-empty body of messages. It
+ 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.
+
+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`