From: Matthew DeVore <matvore@google.com>
To: git@vger.kernel.org
Cc: Matthew DeVore <matvore@google.com>,
peff@peff.net, jonathantanmy@google.com, gitster@pobox.com,
jrn@google.com, sunshine@sunshineco.com, szeder.dev@gmail.com
Subject: [PATCH v4 1/7] t/README: reformat Do, Don't, Keep in mind lists
Date: Wed, 3 Oct 2018 09:25:59 -0700 [thread overview]
Message-ID: <32f6f14f8d3323468b4255927cca028a82f64b39.1538581868.git.matvore@google.com> (raw)
In-Reply-To: <cover.1538581868.git.matvore@google.com>
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>
---
t/README | 40 +++++++++++++++++++---------------------
1 file changed, 19 insertions(+), 21 deletions(-)
diff --git a/t/README b/t/README
index 9028b47d9..85024aba6 100644
--- a/t/README
+++ b/t/README
@@ -393,13 +393,13 @@ This test harness library does the following things:
consistently when command line arguments --verbose (or -v),
--debug (or -d), and --immediate (or -i) is given.
-Do's, don'ts & things to keep in mind
+Do's & don'ts
-------------------------------------
Here are a few examples of things you probably should and shouldn't do
when writing tests.
-Do:
+Here are the "do's:"
- Put all code inside test_expect_success and other assertions.
@@ -444,16 +444,21 @@ Do:
Windows, where the shell (MSYS bash) mangles absolute path names.
For details, see the commit message of 4114156ae9.
-Don't:
+ - Remember that inside the <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 debug the tests.
- - exit() within a <script> part.
+And here are the "don'ts:"
+
+ - Don't exit() within a <script> part.
The harness will catch this as a programming error of the test.
Use test_done instead if you need to stop the tests early (see
"Skipping tests" below).
- - use '! git cmd' when you want to make sure the git command exits
- with failure in a controlled way by calling "die()". Instead,
+ - Don't use '! git cmd' when you want to make sure the git command
+ exits with failure in a controlled way by calling "die()". Instead,
use 'test_must_fail git cmd'. This will signal a failure if git
dies in an unexpected way (e.g. segfault).
@@ -461,8 +466,8 @@ Don't:
platform commands; just use '! cmd'. We are not in the business
of verifying that the world given to us sanely works.
- - use perl without spelling it as "$PERL_PATH". This is to help our
- friends on Windows where the platform Perl often adds CR before
+ - Don't use perl without spelling it as "$PERL_PATH". This is to help
+ our friends on Windows where the platform Perl often adds CR before
the end of line, and they bundle Git with a version of Perl that
does not do so, whose path is specified with $PERL_PATH. Note that we
provide a "perl" function which uses $PERL_PATH under the hood, so
@@ -470,17 +475,17 @@ Don't:
(but you do, for example, on a shebang line or in a sub script
created via "write_script").
- - use sh without spelling it as "$SHELL_PATH", when the script can
- be misinterpreted by broken platform shell (e.g. Solaris).
+ - Don't use sh without spelling it as "$SHELL_PATH", when the script
+ can be misinterpreted by broken platform shell (e.g. Solaris).
- - chdir around in tests. It is not sufficient to chdir to
+ - Don't chdir around in tests. It is not sufficient to chdir to
somewhere and then chdir back to the original location later in
the test, as any intermediate step can fail and abort the test,
causing the next test to start in an unexpected directory. Do so
inside a subshell if necessary.
- - save and verify the standard error of compound commands, i.e. group
- commands, subshells, and shell functions (except test helper
+ - Don't save and verify the standard error of compound commands, i.e.
+ group commands, subshells, and shell functions (except test helper
functions like 'test_must_fail') like this:
( cd dir && git cmd ) 2>error &&
@@ -495,7 +500,7 @@ Don't:
( cd dir && git cmd 2>../error ) &&
test_cmp expect error
- - Break the TAP output
+ - Don't break the TAP output
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
@@ -515,13 +520,6 @@ Don't:
but the best indication is to just run the tests with prove(1),
it'll complain if anything is amiss.
-Keep in mind:
-
- - Inside the <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.
-
Skipping tests
--------------
--
2.19.0.605.g01d371f741-goog
next prev parent reply other threads:[~2018-10-03 16:26 UTC|newest]
Thread overview: 66+ messages / expand[flat|nested] mbox.gz Atom feed top
2018-09-15 0:02 [PATCH v1 0/2] Cleanup tests for test_cmp argument ordering and "|" placement Matthew DeVore
2018-09-15 0:02 ` [PATCH v1 1/2] t/*: fix pipe placement and remove \'s Matthew DeVore
2018-09-17 16:31 ` Jonathan Nieder
2018-09-17 21:47 ` Matthew DeVore
2018-09-15 0:02 ` [PATCH v1 2/2] t/*: fix ordering of expected/observed arguments Matthew DeVore
2018-09-17 12:56 ` Matthew DeVore
2018-09-15 15:55 ` [PATCH v1 0/2] Cleanup tests for test_cmp argument ordering and "|" placement Junio C Hamano
2018-09-17 22:24 ` [PATCH v2 0/6] Clean up tests for test_cmp arg ordering and pipe placement Matthew DeVore
2018-09-17 22:24 ` [PATCH v2 4/6] tests: Add linter check for pipe placement style Matthew DeVore
2018-09-18 0:34 ` Eric Sunshine
2018-09-19 17:39 ` Matthew DeVore
[not found] ` <cover.1537223021.git.matvore@google.com>
2018-09-17 22:24 ` [PATCH v2 1/6] CodingGuidelines: add shell piping guidelines Matthew DeVore
2018-09-18 0:16 ` Eric Sunshine
2018-09-19 2:11 ` Matthew DeVore
2018-09-19 12:36 ` Eric Sunshine
2018-09-19 14:24 ` Junio C Hamano
2018-09-19 20:06 ` Matthew DeVore
2018-09-17 22:24 ` [PATCH v2 2/6] tests: standardize pipe placement Matthew DeVore
2018-09-17 22:24 ` [PATCH v2 3/6] t/*: fix ordering of expected/observed arguments Matthew DeVore
2018-09-17 22:24 ` [PATCH v2 4/6] tests: add linter check for pipe placement style Matthew DeVore
2018-09-17 22:24 ` [PATCH v2 5/6] tests: split up pipes Matthew DeVore
2018-09-18 1:30 ` Eric Sunshine
2018-09-19 2:33 ` Matthew DeVore
2018-09-17 22:24 ` [PATCH v2 6/6] t9109-git-svn-props.sh: split up several pipes Matthew DeVore
2018-09-18 1:56 ` Eric Sunshine
2018-09-19 2:56 ` Matthew DeVore
2018-09-19 12:50 ` Eric Sunshine
2018-09-19 18:43 ` Matthew DeVore
2018-09-21 1:43 ` [PATCH v3 0/5] Clean up tests for test_cmp arg ordering and pipe placement Matthew DeVore
2018-09-21 1:43 ` [PATCH v3 1/5] CodingGuidelines: add shell piping guidelines Matthew DeVore
2018-09-21 2:06 ` Eric Sunshine
2018-09-21 21:03 ` Matthew DeVore
2018-09-24 21:03 ` SZEDER Gábor
2018-09-25 21:58 ` Matthew DeVore
2018-09-27 21:18 ` SZEDER Gábor
2018-10-01 23:07 ` Matthew DeVore
2018-09-21 1:43 ` [PATCH v3 2/5] tests: standardize pipe placement Matthew DeVore
2018-09-21 1:43 ` [PATCH v3 3/5] t/*: fix ordering of expected/observed arguments Matthew DeVore
2018-09-21 1:43 ` [PATCH v3 4/5] tests: don't swallow Git errors upstream of pipes Matthew DeVore
2018-09-21 1:43 ` [PATCH v3 5/5] t9109: " Matthew DeVore
2018-10-03 16:25 ` [PATCH v4 0/7] Clean up tests for test_cmp arg ordering and pipe placement Matthew DeVore
2018-10-03 16:25 ` Matthew DeVore [this message]
2018-10-05 6:15 ` [PATCH v4 1/7] t/README: reformat Do, Don't, Keep in mind lists Junio C Hamano
2018-10-05 14:57 ` Matthew DeVore
2018-10-03 16:26 ` [PATCH v4 2/7] Documentation: add shell guidelines Matthew DeVore
2018-10-05 16:48 ` Junio C Hamano
2018-10-05 18:21 ` Matthew DeVore
2018-10-03 16:26 ` [PATCH v4 3/7] tests: standardize pipe placement Matthew DeVore
2018-10-03 16:26 ` [PATCH v4 4/7] t/*: fix ordering of expected/observed arguments Matthew DeVore
2018-10-03 16:26 ` [PATCH v4 5/7] tests: don't swallow Git errors upstream of pipes Matthew DeVore
2018-10-05 16:48 ` Junio C Hamano
2018-10-05 17:54 ` Matthew DeVore
2018-10-05 18:12 ` Matthew DeVore
2018-10-03 16:26 ` [PATCH v4 6/7] t9109: " Matthew DeVore
2018-10-03 16:26 ` [PATCH v4 7/7] tests: order arguments to git-rev-list properly Matthew DeVore
2018-10-03 16:33 ` Matthew DeVore
2018-10-05 8:16 ` Junio C Hamano
2018-10-05 21:54 ` [PATCH v5 0/7] subject: Clean up tests for test_cmp arg ordering and pipe placement Matthew DeVore
2018-10-05 21:54 ` [PATCH v5 1/7] t/README: reformat Do, Don't, Keep in mind lists Matthew DeVore
2018-10-05 21:54 ` [PATCH v5 2/7] Documentation: add shell guidelines Matthew DeVore
2018-10-05 21:54 ` [PATCH v5 3/7] tests: standardize pipe placement Matthew DeVore
2018-10-05 21:54 ` [PATCH v5 4/7] t/*: fix ordering of expected/observed arguments Matthew DeVore
2018-10-05 21:54 ` [PATCH v5 5/7] tests: don't swallow Git errors upstream of pipes Matthew DeVore
2018-10-05 21:54 ` [PATCH v5 6/7] t9109: " Matthew DeVore
2018-10-05 21:54 ` [PATCH v5 7/7] tests: order arguments to git-rev-list properly Matthew DeVore
2018-10-06 23:53 ` [PATCH v5 0/7] subject: Clean up tests for test_cmp arg ordering and pipe placement Junio C Hamano
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
List information: http://vger.kernel.org/majordomo-info.html
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=32f6f14f8d3323468b4255927cca028a82f64b39.1538581868.git.matvore@google.com \
--to=matvore@google.com \
--cc=git@vger.kernel.org \
--cc=gitster@pobox.com \
--cc=jonathantanmy@google.com \
--cc=jrn@google.com \
--cc=peff@peff.net \
--cc=sunshine@sunshineco.com \
--cc=szeder.dev@gmail.com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this public inbox
https://80x24.org/mirrors/git.git
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).