t/README: unify documentation of test function args
PATCH 1/1 t/README: unify documentation of test function args
Document all test function arguments in the same way.
While at it, correct some grammatical errors.
--- t/README | 26 +++++++++++++------------- 1 files changed, 13 insertions(+), 13 deletions(-)
t/README +13 -13
@@ -379,7 +379,7 @@ library for your script to use. - test_expect_success [<prereq>] <message> <script> - Usually takes two strings as parameter, and evaluates the + Usually takes two strings as parameters, and evaluates the <script>. If it yields success, test is considered successful. <message> should state what it is testing.
@@ -389,7 +389,7 @@ library for your script to use. 'git-write-tree should be able to write an empty tree.' \ 'tree=$(git-write-tree)' - If you supply three parameters the first will be taken to be a + If you supply three parameters, the first will be taken to be a prerequisite, see the test_set_prereq and test_have_prereq documentation below:
@@ -446,7 +446,7 @@ library for your script to use. Merges the given rev using the given message. Like test_commit, creates a tag and calls test_tick before committing. - - test_set_prereq SOME_PREREQ + - test_set_prereq <prereq> Set a test prerequisite to be used later with test_have_prereq. The test-lib will set some prerequisites for you, see the
@@ -456,7 +456,7 @@ library for your script to use. test_have_prereq directly, or the three argument invocation of test_expect_success and test_expect_failure. - - test_have_prereq SOME PREREQ + - test_have_prereq <prereq> Check if we have a prerequisite previously set with test_set_prereq. The most common use of this directly is to skip
@@ -503,18 +503,18 @@ library for your script to use. test_expect_code 1 git merge "merge msg" B master ' - - test_must_fail <git-command> + - test_must_fail <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. + Run a command and ensure it fails in a controlled way. Use this + instead of "! <command>". When the command dies due to a segfault, + test_must_fail diagnoses it as an error; "! <command>" treats it as + just another expected failure, which would let such a bug go + unnoticed. - - test_might_fail <git-command> + - test_might_fail <command> Similar to test_must_fail, but tolerate success, too. Use this - instead of "<git-command> || :" to catch failures due to segv. + instead of "<command> || :" to catch failures due to segfault. - test_cmp <expected> <actual>
@@ -530,7 +530,7 @@ library for your script to use. test_path_is_dir <dir> [<diagnosis>] test_path_is_missing <path> [<diagnosis>] - Check whether a file/directory exists or doesn't. <diagnosis> will + Check whether a file/directory exists or not. <diagnosis> will be displayed if the test fails. - test_when_finished <script>
Signature · 1 line
1.7.5.rc3
Quoted 5 lines · Mathias Lafeldt
Document all test function arguments in the same way.
While at it, correct some grammatical errors.
Signed-off-by Mathias Lafeldt <[email protected]>
Thanks.
t/README
Quoted 4 lines
t/README +0
-0
Everything before this hunk looks sensible.
Quoted 7 lines
t/README +1
-1@@ -503,18 +503,18 @@ library for your script to use. test_expect_code 1 git merge "merge msg" B master ' - - test_must_fail <git-command> + - test_must_fail <command>
t/README library for your script to use.
Quoted 10 lines
t/README +6
-1+ Run a command and ensure it fails in a controlled way. Use this + instead of "! <command>". When the command dies due to a segfault, + test_must_fail diagnoses it as an error; "! <command>" treats it as + just another expected failure, which would let such a bug go + unnoticed. - - test_might_fail <git-command> + - test_might_fail <command> Similar to test_must_fail, but tolerate success, too...
But the above two deliberately say "git-command" to clarify that these are special cases and meant to be used only to run a git command. If we expect a failure from a command that is not "git", say "date", we would want to say "! date", not "test_must_fail date".
t/README library for your script to use. · line 533
Quoted 6 lines
t/README +1
-1@@ -530,7 +530,7 @@ library for your script to use. test_path_is_dir <dir> [<diagnosis>] test_path_is_missing <path> [<diagnosis>] - Check whether a file/directory exists or doesn't. <diagnosis> will + Check whether a file/directory exists or not. <diagnosis> will
Is the original really a grammo, or is this change just your personal taste? If I were rewriting this, I would probably say something like:
- test_path_is_file <path> [<diagnosis>] test_path_is_dir <path> [<diagnosis>] test_path_is_missing <path> [<diagnosis>]
Check if the named path is a file, if the named path is a directory, or if the named path does not exist, respectively, and fail otherwise, showing the <diagnosis> text.
[...]
Quoted 18 lines
Everything before this hunk looks sensible.
Quoted 16 lines
t/README +7
-2@@ -503,18 +503,18 @@ library for your script to use. test_expect_code 1 git merge "merge msg" B master ' - - test_must_fail <git-command> + - test_must_fail <command> + Run a command and ensure it fails in a controlled way. Use this + instead of "! <command>". When the command dies due to a segfault, + test_must_fail diagnoses it as an error; "! <command>" treats it as + just another expected failure, which would let such a bug go + unnoticed. - - test_might_fail <git-command> + - test_might_fail <command>
Quoted 7 lines
Quoted 1 line
Similar to
test_must_fail, but tolerate success, too...But the above two deliberately say "git-command" to clarify that these are special cases and meant to be used only to run a git command. If we expect a failure from a command that is not "git", say "date", we would want to say "! date", not "
test_must_faildate".
Ah, okay. Is this true for test_expect_code too? It also has a git command in the example, but it says <command>, not <git-command>:
- test_expect_code <exit-code> <command>
Run a command and ensure that it exits with the given exit code. For example:
test_expect_success 'Merge with d/f conflicts' '
test_expect_code 1 git merge "merge msg" B master
'
Quoted 10 lines
t/README library for your script to use. · line 533
Quoted 6 lines
t/README +1
-1@@ -530,7 +530,7 @@ library for your script to use. test_path_is_dir <dir> [<diagnosis>] test_path_is_missing <path> [<diagnosis>] - Check whether a file/directory exists or doesn't. <diagnosis> will + Check whether a file/directory exists or not. <diagnosis> willIs the original really a grammo, or is this change just your personal taste? If I were rewriting this, I would probably say something like:
Quoted 7 lines
-
test_path_is_file<path> [<diagnosis>]test_path_is_dir<path> [<diagnosis>]test_path_is_missing<path> [<diagnosis>]Check if the named path is a file, if the named path is a directory, or if the named path does not exist, respectively, and fail otherwise, showing the <diagnosis> text.
Yes, it's just a matter of taste, but your rewrite is even better.
-Mathias
Quoted 4 lines · Mathias Lafeldt
Ah, okay. Is this true for
test_expect_codetoo? It also has a git command in the example, but it says <command>, not <git-command>:-
test_expect_code<exit-code> <command>
I think that one is Ok as there is no git specific hacks in the semantics. It is a straight "Run this command, and make sure you get this exit code".
The "must-fail" is really a special case in that we just do not expect any failure, but expect a controlled failure. Currently we only catch segv, but we should anticipate that we will reject other types of uncontrolled failures in the future, and keeping the function "git-only" makes it easier to manage.
PATCH v2 1/1 t/README: unify documentation of test function args
Document all test function arguments in the same way.
While at it, tweak the description of test_path_is_* (thanks to Junio), and correct some grammatical errors.
--- t/README | 17 +++++++++-------- 1 files changed, 9 insertions(+), 8 deletions(-)
t/README +9 -8
@@ -379,7 +379,7 @@ library for your script to use. - test_expect_success [<prereq>] <message> <script> - Usually takes two strings as parameter, and evaluates the + Usually takes two strings as parameters, and evaluates the <script>. If it yields success, test is considered successful. <message> should state what it is testing.
@@ -389,7 +389,7 @@ library for your script to use. 'git-write-tree should be able to write an empty tree.' \ 'tree=$(git-write-tree)' - If you supply three parameters the first will be taken to be a + If you supply three parameters, the first will be taken to be a prerequisite, see the test_set_prereq and test_have_prereq documentation below:
@@ -446,7 +446,7 @@ library for your script to use. Merges the given rev using the given message. Like test_commit, creates a tag and calls test_tick before committing. - - test_set_prereq SOME_PREREQ + - test_set_prereq <prereq> Set a test prerequisite to be used later with test_have_prereq. The test-lib will set some prerequisites for you, see the
@@ -456,7 +456,7 @@ library for your script to use. test_have_prereq directly, or the three argument invocation of test_expect_success and test_expect_failure. - - test_have_prereq SOME PREREQ + - test_have_prereq <prereq> Check if we have a prerequisite previously set with test_set_prereq. The most common use of this directly is to skip
@@ -526,12 +526,13 @@ library for your script to use. Check whether a file has the length it is expected to. - - test_path_is_file <file> [<diagnosis>] - test_path_is_dir <dir> [<diagnosis>] + - test_path_is_file <path> [<diagnosis>] + test_path_is_dir <path> [<diagnosis>] test_path_is_missing <path> [<diagnosis>] - Check whether a file/directory exists or doesn't. <diagnosis> will - be displayed if the test fails. + Check if the named path is a file, if the named path is a + directory, or if the named path does not exist, respectively, + and fail otherwise, showing the <diagnosis> text. - test_when_finished <script>
Signature · 1 line
1.7.5
t/README library for your script to use. · line 394
Quoted 8 lines · Mathias Lafeldt
t/README +1
-1@@ -389,7 +389,7 @@ library for your script to use. 'git-write-tree should be able to write an empty tree.' \ 'tree=$(git-write-tree)' - If you supply three parameters the first will be taken to be a + If you supply three parameters, the first will be taken to be a prerequisite, see the test_set_prereq and test_have_prereq documentation below:
As "If you supply three parameters" is not an introductory clause to a larger complete thought in the following few words, the additional comma is unnecessary.
Signature · 4 lines
-Drew Northup ________________________________________________ "As opposed to vegetable or mineral error?" -John Pescatore, SANS NewsBites Vol. 12 Num. 59
Quoted 6 lines · Drew Northup
Quoted 4 lines · Mathias Lafeldt
t/README +0
-0@@ -389,7 +389,7 @@ library for your script to use. 'git-write-tree should be able to write an empty tree.' \ 'tree=$(git-write-tree)'
Quoted 8 lines
t/README library for your script to use. · line 394
Quoted 4 lines
t/README +1
-1- If you supply three parameters the first will be taken to be a + If you supply three parameters, the first will be taken to be a prerequisite, see the test_set_prereq and test_have_prereq documentation below:As "If you supply three parameters" is not an introductory clause to a larger complete thought in the following few words, the additional comma is unnecessary.
Makes sense.
On the other hand, "see the ... below" is a separate sentence, and it deserves to have something stronger than a comma in front of it. I've queued with a minor fixup.
Thanks.