Do's, don'ts & things to keep in mind
-------------------------------------
-Here's a few examples of things you probably should and shouldn't do
+Here are a few examples of things you probably should and shouldn't do
when writing tests.
Do:
- - Put as much code as possible inside test_expect_success and other
- assertions.
+ - Put all code inside test_expect_success and other assertions.
Even code that isn't a test per se, but merely some setup code
- should be inside a test assertion if at all possible. Test scripts
- should only have trivial code outside of their assertions.
+ should be inside a test assertion.
- Chain your test assertions
test ...
That way all of the commands in your tests will succeed or fail. If
- you must ignore the return value of something (e.g. the return
- value of export is unportable) it's best to indicate so explicitly
- with a semicolon:
+ you must ignore the return value of something (e.g., the return
+ after unsetting a variable that was already unset is unportable) it's
+ best to indicate so explicitly with a semicolon:
- export HLAGH;
+ unset HLAGH;
git merge hla &&
git push gh &&
test ...
- Break the TAP output
- The raw output from your test might be interpreted by a TAP
- harness. You usually don't have to worry about that. TAP harnesses
- will ignore everything they don't know about, but don't step on
- their toes in these areas:
+ The raw output from your test may be interpreted by a TAP harness. TAP
+ harnesses will ignore everything they don't know about, but don't step
+ on their toes in these areas:
- Don't print lines like "$x..$y" where $x and $y are integers.
- Don't print lines that begin with "ok" or "not ok".
- A TAP harness expect a line that begins with either "ok" and "not
+ TAP harnesses expect a line that begins with either "ok" and "not
ok" to signal a test passed or failed (and our harness already
produces such lines), so your script shouldn't emit such lines to
their output.
Keep in mind:
- - That what you print to stderr and stdout is usually ignored
-
- Inside <script> part, the standard output and standard error
+ - Inside <script> part, the standard output and standard error
streams are discarded, and the test harness only reports "ok" or
"not ok" to the end user running the tests. Under --verbose, they
are shown to help debugging the tests.
'Perl API' \
"$PERL_PATH" "$TEST_DIRECTORY"/t9700/test.pl
+ - test_must_fail <git-command>
+
+ Run a git command and ensure it fails in a controlled way. Use
+ this instead of "! <git-command>". When git-command dies due to a
+ segfault, test_must_fail diagnoses it as an error; "! <git-command>"
+ treats it as just another expected failure, which would let such a
+ bug go unnoticed.
+
+ - test_might_fail <git-command>
+
+ Similar to test_must_fail, but tolerate success, too. Use this
+ instead of "<git-command> || :" to catch failures due to segv.
+
+ - test_cmp <expected> <actual>
+
+ Check whether the content of the <actual> file matches the
+ <expected> file. This behaves like "cmp" but produces more
+ helpful output when the test is run with "-v" option.
+
+ - test_when_finished <script>
+
+ Prepend <script> to a list of commands to run to clean up
+ at the end of the current test. If some clean-up command
+ fails, the test will not pass.
+
+ Example:
+
+ test_expect_success 'branch pointing to non-commit' '
+ git rev-parse HEAD^{tree} >.git/refs/heads/invalid &&
+ test_when_finished "git update-ref -d refs/heads/invalid" &&
+ ...
+ '
+
Tips for Writing Tests
----------------------