t/README: add a bit more Don'ts
Add a few more advices that we often have to give to new test writers. Also update an example where a double quote pair is used to enclose a test body to use a single quote pair, which is more readable and more importantly gives saner semantics for variable substitution. Signed-off-by: Junio C Hamano <gitster@pobox.com>
Junio C Hamano committed
Jun 12, 2012 at 09:44 UTC
ad78585eeebd8d5ac596ad4f06f549734ce9d870
1 file changed
+22
-3
t/README
+22
-3
@@ -307,6 +307,25 @@ Don't:
307
Use test_done instead if you need to stop the tests early (see
308
"Skipping tests" below).
309
310
+ - use '! git cmd' when you want to make sure the git command exits
311
+ with failure in a controlled way by calling "die()". Instead,
312
+ use 'test_must_fail git cmd'. This will signal a failure if git
313
+ dies in an unexpected way (e.g. segfault).
314
+
315
+ - use perl without spelling it as "$PERL_PATH". This is to help our
316
+ friends on Windows where the platform Perl often adds CR before
317
+ the end of line, and they bundle Git with a version of Perl that
318
+ does not do so, whose path is specified with $PERL_PATH.
319
+
320
+ - use sh without spelling it as "$SHELL_PATH", when the script can
321
+ be misinterpreted by broken platform shell (e.g. Solaris).
322
+
323
+ - chdir around in tests. It is not sufficient to chdir to
324
+ somewhere and then chdir back to the original location later in
325
+ the test, as any intermediate step can fail and abort the test,
326
+ causing the next test to start in an unexpected directory. Do so
327
+ inside a subshell if necessary.
328
+
329
- Break the TAP output
330
331
The raw output from your test may be interpreted by a TAP harness. TAP
@@ -342,9 +361,9 @@ If you need to skip tests you should do so by using the three-arg form
361
of the test_* functions (see the "Test harness library" section
362
below), e.g.:
363
345
- test_expect_success PERL 'I need Perl' "
346
- '$PERL_PATH' -e 'hlagh() if unf_unf()'
347
- "
364
+ test_expect_success PERL 'I need Perl' '
365
+ "$PERL_PATH" -e "hlagh() if unf_unf()"
366
+ '
367
368
The advantage of skipping tests like this is that platforms that don't
369
have the PERL and other optional dependencies get an indication of how