diff options
Diffstat (limited to 't/README')
| -rw-r--r-- | t/README | 124 |
1 files changed, 60 insertions, 64 deletions
@@ -32,7 +32,14 @@ the tests. ok 2 - plain with GIT_WORK_TREE ok 3 - plain bare -Since the tests all output TAP (see http://testanything.org) they can +t/Makefile defines a target for each test file, such that you can also use +shell pattern matching to run a subset of the tests: + + make *checkout* + +will run all tests with 'checkout' in their filename. + +Since the tests all output TAP (see https://testanything.org) they can be run with any TAP harness. Here's an example of parallel testing powered by a recent version of prove(1): @@ -262,8 +269,8 @@ The argument for --run, <test-selector>, is a list of description substrings or globs or individual test numbers or ranges with an optional negation prefix (of '!') that define what tests in a test suite to include (or exclude, if negated) in the run. A range is two -numbers separated with a dash and matches a range of tests with both -ends been included. You may omit the first or the second number to +numbers separated with a dash and specifies an inclusive range of tests +to run. You may omit the first or the second number to mean "from the first test" or "up to the very last test" respectively. The argument to --run is split on commas into separate strings, @@ -274,10 +281,10 @@ text that you want to match includes a comma, use the glob character on all tests that match either the glob *rebase* or the glob *merge?cherry-pick*. -If --run starts with an unprefixed number or range the initial -set of tests to run is empty. If the first item starts with '!' +If --run starts with an unprefixed number or range, the initial +set of tests to run is empty. If the first item starts with '!', all the tests are added to the initial set. After initial set is -determined every test number or range is added or excluded from +determined, every test number or range is added or excluded from the set one by one, from left to right. For example, to run only tests up to a specific test (21), one @@ -361,48 +368,6 @@ excluded as so much relies on it, but this might change in the future. GIT_TEST_SPLIT_INDEX=<boolean> forces split-index mode on the whole test suite. Accept any boolean values that are accepted by git-config. -GIT_TEST_PASSING_SANITIZE_LEAK=true skips those tests that haven't -declared themselves as leak-free by setting -"TEST_PASSES_SANITIZE_LEAK=true" before sourcing "test-lib.sh". This -test mode is used by the "linux-leaks" CI target. - -GIT_TEST_PASSING_SANITIZE_LEAK=check checks that our -"TEST_PASSES_SANITIZE_LEAK=true" markings are current. Rather than -skipping those tests that haven't set "TEST_PASSES_SANITIZE_LEAK=true" -before sourcing "test-lib.sh" this mode runs them with -"--invert-exit-code". This is used to check that there's a one-to-one -mapping between "TEST_PASSES_SANITIZE_LEAK=true" and those tests that -pass under "SANITIZE=leak". This is especially useful when testing a -series that fixes various memory leaks with "git rebase -x". - -GIT_TEST_SANITIZE_LEAK_LOG=true will log memory leaks to -"test-results/$TEST_NAME.leak/trace.*" files. The logs include a -"dedup_token" (see +"ASAN_OPTIONS=help=1 ./git") and other options to -make logs +machine-readable. - -With GIT_TEST_SANITIZE_LEAK_LOG=true we'll look at the leak logs -before exiting and exit on failure if the logs showed that we had a -memory leak, even if the test itself would have otherwise passed. This -allows us to catch e.g. missing &&-chaining. This is especially useful -when combined with "GIT_TEST_PASSING_SANITIZE_LEAK", see below. - -GIT_TEST_PASSING_SANITIZE_LEAK=check when combined with "--immediate" -will run to completion faster, and result in the same failing -tests. The only practical reason to run -GIT_TEST_PASSING_SANITIZE_LEAK=check without "--immediate" is to -combine it with "GIT_TEST_SANITIZE_LEAK_LOG=true". If we stop at the -first failing test case our leak logs won't show subsequent leaks we -might have run into. - -GIT_TEST_PASSING_SANITIZE_LEAK=(true|check) will not catch all memory -leaks unless combined with GIT_TEST_SANITIZE_LEAK_LOG=true. Some tests -run "git" (or "test-tool" etc.) without properly checking the exit -code, or git will invoke itself and fail to ferry the abort() exit -code to the original caller. When the two modes are combined we'll -look at the "test-results/$TEST_NAME.leak/trace.*" files at the end of -the test run to see if had memory leaks which the test itself didn't -catch. - GIT_TEST_PROTOCOL_VERSION=<n>, when set, makes 'protocol.version' default to n. @@ -462,9 +427,9 @@ GIT_TEST_MULTI_PACK_INDEX=<boolean>, when true, forces the multi-pack- index to be written after every 'git repack' command, and overrides the 'core.multiPackIndex' setting to true. -GIT_TEST_MULTI_PACK_INDEX_WRITE_BITMAP=<boolean>, when true, sets the -'--bitmap' option on all invocations of 'git multi-pack-index write', -and ignores pack-objects' '--write-bitmap-index'. +GIT_TEST_MULTI_PACK_INDEX_WRITE_INCREMENTAL=<boolean>, when true, sets +the '--incremental' option on all invocations of 'git multi-pack-index +write'. GIT_TEST_SIDEBAND_ALL=<boolean>, when true, overrides the 'uploadpack.allowSidebandAll' setting to true, and when false, forces @@ -479,6 +444,10 @@ GIT_TEST_DEFAULT_HASH=<hash-algo> specifies which hash algorithm to use in the test scripts. Recognized values for <hash-algo> are "sha1" and "sha256". +GIT_TEST_DEFAULT_REF_FORMAT=<format> specifies which ref storage format to use +in the test scripts. Recognized values for <format> are "files" and +"reftable". + GIT_TEST_NO_WRITE_REV_INDEX=<boolean>, when true disables the 'pack.writeReverseIndex' setting. @@ -579,11 +548,11 @@ This test harness library does the following things: Recommended style ----------------- -Here are some recommented styles when writing test case. - - Keep test title the same line with test helper function itself. + - Keep the test_expect_* function call and test title on + the same line. - Take test_expect_success helper for example, write it like: + For example, with test_expect_success, write it like: test_expect_success 'test title' ' ... test body ... @@ -595,10 +564,9 @@ Here are some recommented styles when writing test case. 'test title' \ '... test body ...' + - End the line with an opening single quote. - - End the line with a single quote. - - - Indent the body of here-document, and use "<<-" instead of "<<" + - Indent here-document bodies, and use "<<-" instead of "<<" to strip leading TABs used for indentation: test_expect_success 'test something' ' @@ -624,7 +592,7 @@ Here are some recommented styles when writing test case. ' - Quote or escape the EOF delimiter that begins a here-document if - there is no parameter and other expansion in it, to signal readers + there is no parameter or other expansion in it, to signal readers that they can skim it more casually: cmd <<-\EOF @@ -638,7 +606,7 @@ Do's & don'ts Here are a few examples of things you probably should and shouldn't do when writing tests. -Here are the "do's:" +The "do's:" - Put all code inside test_expect_success and other assertions. @@ -722,6 +690,26 @@ Here are the "do's:" Note that we still &&-chain the loop to propagate failures from earlier commands. + - Repeat tests with slightly different arguments in a loop. + + In some cases it may make sense to re-run the same set of tests with + different options or commands to ensure that the command behaves + despite the different parameters. This can be achieved by looping + around a specific parameter: + + for arg in '' "--foo" + do + test_expect_success "test command ${arg:-without arguments}" ' + command $arg + ' + done + + Note that while the test title uses double quotes ("), the test body + should continue to use single quotes (') to avoid breakage in case the + values contain e.g. quoting characters. The loop variable will be + accessible regardless of the single quotes as the test body is passed + to `eval`. + And here are the "don'ts:" @@ -877,6 +865,14 @@ see test-lib-functions.sh for the full list and their options. 'git-write-tree should be able to write an empty tree.' \ 'tree=$(git-write-tree)' + If <script> is `-` (a single dash), then the script to run is read + from stdin. This lets you more easily use single quotes within the + script by using a here-doc. For example: + + test_expect_success 'output contains expected string' - <<\EOT + grep "this string has 'quotes' in it" output + EOT + 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: @@ -888,7 +884,7 @@ see test-lib-functions.sh for the full list and their options. rare case where your test depends on more than one: test_expect_success PERL,PYTHON 'yo dawg' \ - ' test $(perl -E 'print eval "1 +" . qx[python -c "print 2"]') == "4" ' + ' test $(perl -E '\''print eval "1 +" . qx[python -c "print(2)"]'\'') = "4" ' - test_expect_failure [<prereq>] <message> <script> @@ -1237,8 +1233,8 @@ and it knows that the object ID of an empty tree is a certain because the things the very basic core test tries to achieve is to serve as a basis for people who are changing the Git internals drastically. For these people, after making certain changes, -not seeing failures from the basic test _is_ a failure. And -such drastic changes to the core Git that even changes these +not seeing failures from the basic test _is_ a failure. Any +Git core changes so drastic that they change even these otherwise supposedly stable object IDs should be accompanied by an update to t0000-basic.sh. @@ -1248,7 +1244,7 @@ knowledge of the core Git internals. If all the test scripts hardcoded the object IDs like t0000-basic.sh does, that defeats the purpose of t0000-basic.sh, which is to isolate that level of validation in one place. Your test also ends up needing -updating when such a change to the internal happens, so do _not_ +an update whenever the internals change, so do _not_ do it and leave the low level of validation to t0000-basic.sh. Test coverage @@ -1279,7 +1275,7 @@ Devel::Cover module. To install it do: sudo aptitude install libdevel-cover-perl # From the CPAN with cpanminus - curl -L http://cpanmin.us | perl - --sudo --self-upgrade + curl -L https://cpanmin.us/ | perl - --sudo --self-upgrade cpanm --sudo Devel::Cover Then, at the top-level: |