t/README: reformat Do, Don't, Keep in mind lists
The list of Don'ts for test writing has grown large such that it is hard to see at a glance which section an item is in. In other words, if I ignore a little bit of surrounding context, the "don'ts" look like "do's." To make the list more readable, prefix "Don't" in front of every first sentence in the items. Also, the "Keep in mind" list is out of place and awkward, because it was a very short "list" beneath two very long ones, and it seemed easy to miss under the list of "don'ts," and it only had one item. So move this item to the list of "do's" and phrase as "Remember..." Signed-off-by: Matthew DeVore <matvore@google.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Matthew DeVore committed
Oct 5, 2018 at 14:54 UTC
441ee35d8384fe7f6328584ac1634da14ed42e11
1 file changed
+20
-22
t/README
+20
-22
@@ -401,13 +401,13 @@ This test harness library does the following things:
401
consistently when command line arguments --verbose (or -v),
402
--debug (or -d), and --immediate (or -i) is given.
403
404
-Do's, don'ts & things to keep in mind
405
--------------------------------------
404
+Do's & don'ts
405
+-------------
406
407
Here are a few examples of things you probably should and shouldn't do
408
when writing tests.
409
410
-Do:
410
+Here are the "do's:"
411
412
- Put all code inside test_expect_success and other assertions.
413
@@ -452,16 +452,21 @@ Do:
452
Windows, where the shell (MSYS bash) mangles absolute path names.
453
For details, see the commit message of 4114156ae9.
454
455
-Don't:
455
+ - Remember that inside the <script> part, the standard output and
456
+ standard error streams are discarded, and the test harness only
457
+ reports "ok" or "not ok" to the end user running the tests. Under
458
+ --verbose, they are shown to help debug the tests.
459
+
460
+And here are the "don'ts:"
461
457
- - exit() within a <script> part.
462
+ - Don't exit() within a <script> part.
463
464
The harness will catch this as a programming error of the test.
465
Use test_done instead if you need to stop the tests early (see
466
"Skipping tests" below).
467
463
- - use '! git cmd' when you want to make sure the git command exits
464
- with failure in a controlled way by calling "die()". Instead,
468
+ - Don't use '! git cmd' when you want to make sure the git command
469
+ exits with failure in a controlled way by calling "die()". Instead,
470
use 'test_must_fail git cmd'. This will signal a failure if git
471
dies in an unexpected way (e.g. segfault).
472
@@ -469,8 +474,8 @@ Don't:
474
platform commands; just use '! cmd'. We are not in the business
475
of verifying that the world given to us sanely works.
476
472
- - use perl without spelling it as "$PERL_PATH". This is to help our
473
- friends on Windows where the platform Perl often adds CR before
477
+ - Don't use perl without spelling it as "$PERL_PATH". This is to help
478
+ our friends on Windows where the platform Perl often adds CR before
479
the end of line, and they bundle Git with a version of Perl that
480
does not do so, whose path is specified with $PERL_PATH. Note that we
481
provide a "perl" function which uses $PERL_PATH under the hood, so
@@ -478,17 +483,17 @@ Don't:
483
(but you do, for example, on a shebang line or in a sub script
484
created via "write_script").
485
481
- - use sh without spelling it as "$SHELL_PATH", when the script can
482
- be misinterpreted by broken platform shell (e.g. Solaris).
486
+ - Don't use sh without spelling it as "$SHELL_PATH", when the script
487
+ can be misinterpreted by broken platform shell (e.g. Solaris).
488
484
- - chdir around in tests. It is not sufficient to chdir to
489
+ - Don't chdir around in tests. It is not sufficient to chdir to
490
somewhere and then chdir back to the original location later in
491
the test, as any intermediate step can fail and abort the test,
492
causing the next test to start in an unexpected directory. Do so
493
inside a subshell if necessary.
494
490
- - save and verify the standard error of compound commands, i.e. group
491
- commands, subshells, and shell functions (except test helper
495
+ - Don't save and verify the standard error of compound commands, i.e.
496
+ group commands, subshells, and shell functions (except test helper
497
functions like 'test_must_fail') like this:
498
499
( cd dir && git cmd ) 2>error &&
@@ -503,7 +508,7 @@ Don't:
508
( cd dir && git cmd 2>../error ) &&
509
test_cmp expect error
510
506
- - Break the TAP output
511
+ - Don't break the TAP output
512
513
The raw output from your test may be interpreted by a TAP harness. TAP
514
harnesses will ignore everything they don't know about, but don't step
@@ -523,13 +528,6 @@ Don't:
528
but the best indication is to just run the tests with prove(1),
529
it'll complain if anything is amiss.
530
526
-Keep in mind:
527
-
528
- - Inside the <script> part, the standard output and standard error
529
- streams are discarded, and the test harness only reports "ok" or
530
- "not ok" to the end user running the tests. Under --verbose, they
531
- are shown to help debugging the tests.
532
-
531
532
Skipping tests
533
--------------