t/README: suggest how to leave test early with failure
Over time, we added the support to our test framework to make it easy to leave a test early with failure, but it was not clearly documented in t/README to help developers writing new tests. Helped-by: Jeff King <peff@peff.net> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Junio C Hamano committed
Mar 27, 2020 at 10:55 UTC
7cc112dc95fd75ba230ad424de622c9d1c1a8b73
1 file changed
+35
t/README
+35
@@ -550,6 +550,41 @@ Here are the "do's:"
550
reports "ok" or "not ok" to the end user running the tests. Under
551
--verbose, they are shown to help debug the tests.
552
553
+ - Be careful when you loop
554
+
555
+ You may need to verify multiple things in a loop, but the
556
+ following does not work correctly:
557
+
558
+ test_expect_success 'test three things' '
559
+ for i in one two three
560
+ do
561
+ test_something "$i"
562
+ done &&
563
+ test_something_else
564
+ '
565
+
566
+ Because the status of the loop itself is the exit status of the
567
+ test_something in the last round, the loop does not fail when
568
+ "test_something" for "one" or "two" fails. This is not what you
569
+ want.
570
+
571
+ Instead, you can break out of the loop immediately when you see a
572
+ failure. Because all test_expect_* snippets are executed inside
573
+ a function, "return 1" can be used to fail the test immediately
574
+ upon a failure:
575
+
576
+ test_expect_success 'test three things' '
577
+ for i in one two three
578
+ do
579
+ test_something "$i" || return 1
580
+ done &&
581
+ test_something_else
582
+ '
583
+
584
+ Note that we still &&-chain the loop to propagate failures from
585
+ earlier commands.
586
+
587
+
588
And here are the "don'ts:"
589
590
- Don't exit() within a <script> part.