Denton Liu | 788db14 | 2020-06-07 05:48:26 -0400 | [diff] [blame] | 1 | Core Git Tests |
Junio C Hamano | 986aa7f | 2005-05-14 00:25:06 -0700 | [diff] [blame] | 2 | ============== |
| 3 | |
Denton Liu | 788db14 | 2020-06-07 05:48:26 -0400 | [diff] [blame] | 4 | This directory holds many test scripts for core Git tools. The |
Junio C Hamano | 986aa7f | 2005-05-14 00:25:06 -0700 | [diff] [blame] | 5 | first part of this short document describes how to run the tests |
| 6 | and read their output. |
| 7 | |
| 8 | When fixing the tools or adding enhancements, you are strongly |
| 9 | encouraged to add tests in this directory to cover what you are |
| 10 | trying to fix or enhance. The later part of this short document |
| 11 | describes how your test scripts should be organized. |
| 12 | |
| 13 | |
| 14 | Running Tests |
| 15 | ------------- |
| 16 | |
| 17 | The easiest way to run tests is to say "make". This runs all |
| 18 | the tests. |
| 19 | |
| 20 | *** t0000-basic.sh *** |
Ævar Arnfjörð Bjarmason | 5099b99 | 2010-06-24 21:52:12 +0000 | [diff] [blame] | 21 | ok 1 - .git/objects should be empty after git init in an empty repo. |
| 22 | ok 2 - .git/objects should have 3 subdirectories. |
| 23 | ok 3 - success is reported like this |
Junio C Hamano | 986aa7f | 2005-05-14 00:25:06 -0700 | [diff] [blame] | 24 | ... |
Ævar Arnfjörð Bjarmason | 5099b99 | 2010-06-24 21:52:12 +0000 | [diff] [blame] | 25 | ok 43 - very long name in the index handled sanely |
| 26 | # fixed 1 known breakage(s) |
| 27 | # still have 1 known breakage(s) |
| 28 | # passed all remaining 42 test(s) |
| 29 | 1..43 |
| 30 | *** t0001-init.sh *** |
| 31 | ok 1 - plain |
| 32 | ok 2 - plain with GIT_WORK_TREE |
| 33 | ok 3 - plain bare |
Junio C Hamano | 986aa7f | 2005-05-14 00:25:06 -0700 | [diff] [blame] | 34 | |
Ævar Arnfjörð Bjarmason | 5099b99 | 2010-06-24 21:52:12 +0000 | [diff] [blame] | 35 | Since the tests all output TAP (see http://testanything.org) they can |
Ævar Arnfjörð Bjarmason | 85b0b34 | 2010-07-02 14:59:44 +0000 | [diff] [blame] | 36 | be run with any TAP harness. Here's an example of parallel testing |
Ævar Arnfjörð Bjarmason | 5099b99 | 2010-06-24 21:52:12 +0000 | [diff] [blame] | 37 | powered by a recent version of prove(1): |
Junio C Hamano | 986aa7f | 2005-05-14 00:25:06 -0700 | [diff] [blame] | 38 | |
Ævar Arnfjörð Bjarmason | 5099b99 | 2010-06-24 21:52:12 +0000 | [diff] [blame] | 39 | $ prove --timer --jobs 15 ./t[0-9]*.sh |
| 40 | [19:17:33] ./t0005-signals.sh ................................... ok 36 ms |
| 41 | [19:17:33] ./t0022-crlf-rename.sh ............................... ok 69 ms |
| 42 | [19:17:33] ./t0024-crlf-archive.sh .............................. ok 154 ms |
| 43 | [19:17:33] ./t0004-unwritable.sh ................................ ok 289 ms |
| 44 | [19:17:33] ./t0002-gitfile.sh ................................... ok 480 ms |
| 45 | ===( 102;0 25/? 6/? 5/? 16/? 1/? 4/? 2/? 1/? 3/? 1... )=== |
| 46 | |
| 47 | prove and other harnesses come with a lot of useful options. The |
| 48 | --state option in particular is very useful: |
| 49 | |
| 50 | # Repeat until no more failures |
| 51 | $ prove -j 15 --state=failed,save ./t[0-9]*.sh |
| 52 | |
Michael J Gruber | 28d836c | 2010-10-14 10:53:36 +0200 | [diff] [blame] | 53 | You can give DEFAULT_TEST_TARGET=prove on the make command (or define it |
| 54 | in config.mak) to cause "make test" to run tests under prove. |
| 55 | GIT_PROVE_OPTS can be used to pass additional options, e.g. |
| 56 | |
| 57 | $ make DEFAULT_TEST_TARGET=prove GIT_PROVE_OPTS='--timer --jobs 16' test |
| 58 | |
Ævar Arnfjörð Bjarmason | 5099b99 | 2010-06-24 21:52:12 +0000 | [diff] [blame] | 59 | You can also run each test individually from command line, like this: |
| 60 | |
| 61 | $ sh ./t3010-ls-files-killed-modified.sh |
| 62 | ok 1 - git update-index --add to add various paths. |
| 63 | ok 2 - git ls-files -k to show killed files. |
| 64 | ok 3 - validate git ls-files -k output. |
| 65 | ok 4 - git ls-files -m to show modified files. |
| 66 | ok 5 - validate git ls-files -m output. |
| 67 | # passed all 5 test(s) |
| 68 | 1..5 |
Junio C Hamano | 986aa7f | 2005-05-14 00:25:06 -0700 | [diff] [blame] | 69 | |
| 70 | You can pass --verbose (or -v), --debug (or -d), and --immediate |
Johannes Schindelin | 4e1be63 | 2009-02-04 00:25:59 +0100 | [diff] [blame] | 71 | (or -i) command line argument to the test, or by setting GIT_TEST_OPTS |
Matheus Tavares | 78dc088 | 2020-03-22 12:58:57 -0300 | [diff] [blame] | 72 | appropriately before running "make". Short options can be bundled, i.e. |
| 73 | '-d -v' is the same as '-dv'. |
Junio C Hamano | 986aa7f | 2005-05-14 00:25:06 -0700 | [diff] [blame] | 74 | |
Ilya Bobyr | 5e3b4fc | 2014-04-30 02:50:42 -0700 | [diff] [blame] | 75 | -v:: |
Junio C Hamano | 986aa7f | 2005-05-14 00:25:06 -0700 | [diff] [blame] | 76 | --verbose:: |
| 77 | This makes the test more verbose. Specifically, the |
| 78 | command being run and their output if any are also |
| 79 | output. |
| 80 | |
Thomas Rast | ff09af3 | 2013-06-23 20:12:56 +0200 | [diff] [blame] | 81 | --verbose-only=<pattern>:: |
| 82 | Like --verbose, but the effect is limited to tests with |
| 83 | numbers matching <pattern>. The number matched against is |
| 84 | simply the running count of the test within the file. |
| 85 | |
Jeff King | a136f6d | 2014-10-10 02:47:27 -0400 | [diff] [blame] | 86 | -x:: |
| 87 | Turn on shell tracing (i.e., `set -x`) during the tests |
SZEDER Gábor | 94201a2 | 2018-02-24 00:39:50 +0100 | [diff] [blame] | 88 | themselves. Implies `--verbose`. |
SZEDER Gábor | 5fc98e7 | 2018-02-24 00:39:42 +0100 | [diff] [blame] | 89 | Ignored in test scripts that set the variable 'test_untraceable' |
| 90 | to a non-empty value, unless it's run with a Bash version |
| 91 | supporting BASH_XTRACEFD, i.e. v4.1 or later. |
Jeff King | a136f6d | 2014-10-10 02:47:27 -0400 | [diff] [blame] | 92 | |
Ilya Bobyr | 5e3b4fc | 2014-04-30 02:50:42 -0700 | [diff] [blame] | 93 | -d:: |
Junio C Hamano | 986aa7f | 2005-05-14 00:25:06 -0700 | [diff] [blame] | 94 | --debug:: |
| 95 | This may help the person who is developing a new test. |
| 96 | It causes the command defined with test_debug to run. |
Piotr Krukowiecki | 0986de9 | 2011-03-15 20:58:14 +0100 | [diff] [blame] | 97 | The "trash" directory (used to store all temporary data |
| 98 | during testing) is not deleted even if there are no |
| 99 | failed tests so that you can inspect its contents after |
| 100 | the test finished. |
Junio C Hamano | 986aa7f | 2005-05-14 00:25:06 -0700 | [diff] [blame] | 101 | |
Ilya Bobyr | 5e3b4fc | 2014-04-30 02:50:42 -0700 | [diff] [blame] | 102 | -i:: |
Junio C Hamano | 986aa7f | 2005-05-14 00:25:06 -0700 | [diff] [blame] | 103 | --immediate:: |
| 104 | This causes the test to immediately exit upon the first |
Simon Ruderich | 13cb3bb | 2013-04-09 23:48:36 +0200 | [diff] [blame] | 105 | failed test. Cleanup commands requested with |
| 106 | test_when_finished are not executed if the test failed, |
| 107 | in order to keep the state for inspection by the tester |
| 108 | to diagnose the bug. |
Junio C Hamano | 986aa7f | 2005-05-14 00:25:06 -0700 | [diff] [blame] | 109 | |
Ilya Bobyr | 5e3b4fc | 2014-04-30 02:50:42 -0700 | [diff] [blame] | 110 | -l:: |
Lea Wiemann | 5e2c08c | 2008-06-17 03:29:02 +0200 | [diff] [blame] | 111 | --long-tests:: |
| 112 | This causes additional long-running tests to be run (where |
| 113 | available), for more exhaustive testing. |
| 114 | |
Ilya Bobyr | 0445e6f | 2014-04-30 02:50:44 -0700 | [diff] [blame] | 115 | -r:: |
| 116 | --run=<test-selector>:: |
| 117 | Run only the subset of tests indicated by |
| 118 | <test-selector>. See section "Skipping Tests" below for |
| 119 | <test-selector> syntax. |
| 120 | |
Thomas Rast | 952af35 | 2013-03-31 10:00:16 +0200 | [diff] [blame] | 121 | --valgrind=<tool>:: |
| 122 | Execute all Git binaries under valgrind tool <tool> and exit |
| 123 | with status 126 on errors (just like regular tests, this will |
| 124 | only stop the test script when running under -i). |
Junio C Hamano | 986aa7f | 2005-05-14 00:25:06 -0700 | [diff] [blame] | 125 | |
Johannes Schindelin | 3da9365 | 2009-02-04 00:26:26 +0100 | [diff] [blame] | 126 | Since it makes no sense to run the tests with --valgrind and |
| 127 | not see any output, this option implies --verbose. For |
| 128 | convenience, it also implies --tee. |
| 129 | |
Thomas Rast | 952af35 | 2013-03-31 10:00:16 +0200 | [diff] [blame] | 130 | <tool> defaults to 'memcheck', just like valgrind itself. |
| 131 | Other particularly useful choices include 'helgrind' and |
| 132 | 'drd', but you may use any tool recognized by your valgrind |
| 133 | installation. |
| 134 | |
Thomas Rast | 95d9d5e | 2013-03-31 10:00:17 +0200 | [diff] [blame] | 135 | As a special case, <tool> can be 'memcheck-fast', which uses |
| 136 | memcheck but disables --track-origins. Use this if you are |
| 137 | running tests in bulk, to see if there are _any_ memory |
| 138 | issues. |
| 139 | |
Thomas Rast | 952af35 | 2013-03-31 10:00:16 +0200 | [diff] [blame] | 140 | Note that memcheck is run with the option --leak-check=no, |
Carlos Martín Nieto | 9aec68d | 2011-03-15 10:32:11 +0100 | [diff] [blame] | 141 | as the git process is short-lived and some errors are not |
| 142 | interesting. In order to run a single command under the same |
| 143 | conditions manually, you should set GIT_VALGRIND to point to |
| 144 | the 't/valgrind/' directory and use the commands under |
| 145 | 't/valgrind/bin/'. |
| 146 | |
Thomas Rast | 5dfc368 | 2013-06-23 20:12:57 +0200 | [diff] [blame] | 147 | --valgrind-only=<pattern>:: |
| 148 | Like --valgrind, but the effect is limited to tests with |
| 149 | numbers matching <pattern>. The number matched against is |
| 150 | simply the running count of the test within the file. |
| 151 | |
Johannes Schindelin | 4413855 | 2009-02-04 00:26:12 +0100 | [diff] [blame] | 152 | --tee:: |
| 153 | In addition to printing the test output to the terminal, |
| 154 | write it to files named 't/test-results/$TEST_NAME.out'. |
| 155 | As the names depend on the tests' file names, it is safe to |
| 156 | run the tests with this option in parallel. |
| 157 | |
SZEDER Gábor | a5f52c6 | 2018-10-29 13:13:59 +0100 | [diff] [blame] | 158 | -V:: |
Jeff King | 452320f | 2016-10-21 06:48:00 -0400 | [diff] [blame] | 159 | --verbose-log:: |
| 160 | Write verbose output to the same logfile as `--tee`, but do |
| 161 | _not_ write it to stdout. Unlike `--tee --verbose`, this option |
| 162 | is safe to use when stdout is being consumed by a TAP parser |
| 163 | like `prove`. Implies `--tee` and `--verbose`. |
| 164 | |
Matthew Ogilvie | e4597aa | 2009-12-02 22:14:06 -0700 | [diff] [blame] | 165 | --with-dashes:: |
| 166 | By default tests are run without dashed forms of |
| 167 | commands (like git-commit) in the PATH (it only uses |
| 168 | wrappers from ../bin-wrappers). Use this option to include |
| 169 | the build directory (..) in the PATH, which contains all |
| 170 | the dashed forms of commands. This option is currently |
| 171 | implied by other options like --valgrind and |
| 172 | GIT_TEST_INSTALLED. |
| 173 | |
Johannes Schindelin | dd167a3 | 2019-01-29 06:19:37 -0800 | [diff] [blame] | 174 | --no-bin-wrappers:: |
| 175 | By default, the test suite uses the wrappers in |
| 176 | `../bin-wrappers/` to execute `git` and friends. With this option, |
| 177 | `../git` and friends are run directly. This is not recommended |
| 178 | in general, as the wrappers contain safeguards to ensure that no |
| 179 | files from an installed Git are used, but can speed up test runs |
| 180 | especially on platforms where running shell scripts is expensive |
| 181 | (most notably, Windows). |
| 182 | |
Thomas Rast | 0d4dbcd | 2010-06-10 20:24:46 +0200 | [diff] [blame] | 183 | --root=<directory>:: |
| 184 | Create "trash" directories used to store all temporary data during |
| 185 | testing under <directory>, instead of the t/ directory. |
| 186 | Using this option with a RAM-based filesystem (such as tmpfs) |
| 187 | can massively speed up the test suite. |
| 188 | |
Jeff King | bb79af9 | 2015-03-20 06:05:48 -0400 | [diff] [blame] | 189 | --chain-lint:: |
| 190 | --no-chain-lint:: |
| 191 | If --chain-lint is enabled, the test harness will check each |
| 192 | test to make sure that it properly "&&-chains" all commands (so |
| 193 | that a failure in the middle does not go unnoticed by the final |
| 194 | exit code of the test). This check is performed in addition to |
| 195 | running the tests themselves. You may also enable or disable |
| 196 | this feature by setting the GIT_TEST_CHAIN_LINT environment |
| 197 | variable to "1" or "0", respectively. |
| 198 | |
Jeff King | 2d86a96 | 2021-05-13 02:25:53 -0400 | [diff] [blame] | 199 | A few test scripts disable some of the more advanced |
| 200 | chain-linting detection in the name of efficiency. You can |
| 201 | override this by setting the GIT_TEST_CHAIN_LINT_HARDER |
| 202 | environment variable to "1". |
| 203 | |
SZEDER Gábor | fb7d1e3 | 2019-01-05 02:08:59 +0100 | [diff] [blame] | 204 | --stress:: |
SZEDER Gábor | fb7d1e3 | 2019-01-05 02:08:59 +0100 | [diff] [blame] | 205 | Run the test script repeatedly in multiple parallel jobs until |
| 206 | one of them fails. Useful for reproducing rare failures in |
| 207 | flaky tests. The number of parallel jobs is, in order of |
Johannes Schindelin | f545737 | 2019-03-03 06:44:55 -0800 | [diff] [blame] | 208 | precedence: the value of the GIT_TEST_STRESS_LOAD |
SZEDER Gábor | fb7d1e3 | 2019-01-05 02:08:59 +0100 | [diff] [blame] | 209 | environment variable, or twice the number of available |
| 210 | processors (as shown by the 'getconf' utility), or 8. |
| 211 | Implies `--verbose -x --immediate` to get the most information |
| 212 | about the failure. Note that the verbose output of each test |
| 213 | job is saved to 't/test-results/$TEST_NAME.stress-<nr>.out', |
| 214 | and only the output of the failed test job is shown on the |
| 215 | terminal. The names of the trash directories get a |
| 216 | '.stress-<nr>' suffix, and the trash directory of the failed |
| 217 | test job is renamed to end with a '.stress-failed' suffix. |
| 218 | |
Johannes Schindelin | f545737 | 2019-03-03 06:44:55 -0800 | [diff] [blame] | 219 | --stress-jobs=<N>:: |
| 220 | Override the number of parallel jobs. Implies `--stress`. |
| 221 | |
SZEDER Gábor | 76e27fb | 2019-02-08 12:50:45 +0100 | [diff] [blame] | 222 | --stress-limit=<N>:: |
| 223 | When combined with --stress run the test script repeatedly |
| 224 | this many times in each of the parallel jobs or until one of |
Johannes Schindelin | de69e6f | 2019-03-03 06:44:54 -0800 | [diff] [blame] | 225 | them fails, whichever comes first. Implies `--stress`. |
SZEDER Gábor | 76e27fb | 2019-02-08 12:50:45 +0100 | [diff] [blame] | 226 | |
Matthew Ogilvie | e160da7 | 2009-11-29 23:19:28 -0700 | [diff] [blame] | 227 | You can also set the GIT_TEST_INSTALLED environment variable to |
| 228 | the bindir of an existing git installation to test that installation. |
| 229 | You still need to have built this git sandbox, from which various |
| 230 | test-* support programs, templates, and perl libraries are used. |
| 231 | If your installed git is incomplete, it will silently test parts of |
| 232 | your built version instead. |
| 233 | |
| 234 | When using GIT_TEST_INSTALLED, you can also set GIT_TEST_EXEC_PATH to |
| 235 | override the location of the dashed-form subcommands (what |
| 236 | GIT_EXEC_PATH would be used for during normal operation). |
| 237 | GIT_TEST_EXEC_PATH defaults to `$GIT_TEST_INSTALLED/git --exec-path`. |
| 238 | |
| 239 | |
Jakub Narebski | fbd458a | 2008-06-20 23:10:50 +0200 | [diff] [blame] | 240 | Skipping Tests |
| 241 | -------------- |
| 242 | |
| 243 | In some environments, certain tests have no way of succeeding |
| 244 | due to platform limitation, such as lack of 'unzip' program, or |
| 245 | filesystem that do not allow arbitrary sequence of non-NUL bytes |
| 246 | as pathnames. |
| 247 | |
| 248 | You should be able to say something like |
| 249 | |
| 250 | $ GIT_SKIP_TESTS=t9200.8 sh ./t9200-git-cvsexport-commit.sh |
| 251 | |
| 252 | and even: |
| 253 | |
| 254 | $ GIT_SKIP_TESTS='t[0-4]??? t91?? t9200.8' make |
| 255 | |
| 256 | to omit such tests. The value of the environment variable is a |
| 257 | SP separated list of patterns that tells which tests to skip, |
| 258 | and either can match the "t[0-9]{4}" part to skip the whole |
| 259 | test, or t[0-9]{4} followed by ".$number" to say which |
| 260 | particular test to skip. |
| 261 | |
Ilya Bobyr | 0445e6f | 2014-04-30 02:50:44 -0700 | [diff] [blame] | 262 | For an individual test suite --run could be used to specify that |
| 263 | only some tests should be run or that some tests should be |
| 264 | excluded from a run. |
| 265 | |
Elijah Newren | f21ac36 | 2020-10-18 00:23:45 +0000 | [diff] [blame] | 266 | The argument for --run, <test-selector>, is a list of description |
| 267 | substrings or globs or individual test numbers or ranges with an |
| 268 | optional negation prefix (of '!') that define what tests in a test |
| 269 | suite to include (or exclude, if negated) in the run. A range is two |
| 270 | numbers separated with a dash and matches a range of tests with both |
| 271 | ends been included. You may omit the first or the second number to |
| 272 | mean "from the first test" or "up to the very last test" respectively. |
Ilya Bobyr | 0445e6f | 2014-04-30 02:50:44 -0700 | [diff] [blame] | 273 | |
Elijah Newren | f21ac36 | 2020-10-18 00:23:45 +0000 | [diff] [blame] | 274 | The argument to --run is split on commas into separate strings, |
| 275 | numbers, and ranges, and picks all tests that match any of the |
| 276 | individual selection criteria. If the substring of the description |
| 277 | text that you want to match includes a comma, use the glob character |
| 278 | '?' instead. For example --run='rebase,merge?cherry-pick' would match |
| 279 | on all tests that match either the glob *rebase* or the glob |
| 280 | *merge?cherry-pick*. |
Ilya Bobyr | 0445e6f | 2014-04-30 02:50:44 -0700 | [diff] [blame] | 281 | |
| 282 | If --run starts with an unprefixed number or range the initial |
| 283 | set of tests to run is empty. If the first item starts with '!' |
| 284 | all the tests are added to the initial set. After initial set is |
| 285 | determined every test number or range is added or excluded from |
| 286 | the set one by one, from left to right. |
| 287 | |
Ilya Bobyr | 0445e6f | 2014-04-30 02:50:44 -0700 | [diff] [blame] | 288 | For example, to run only tests up to a specific test (21), one |
| 289 | could do this: |
| 290 | |
| 291 | $ sh ./t9200-git-cvsexport-commit.sh --run='1-21' |
| 292 | |
| 293 | or this: |
| 294 | |
| 295 | $ sh ./t9200-git-cvsexport-commit.sh --run='-21' |
| 296 | |
| 297 | Common case is to run several setup tests (1, 2, 3) and then a |
| 298 | specific test (21) that relies on that setup: |
| 299 | |
Elijah Newren | f21ac36 | 2020-10-18 00:23:45 +0000 | [diff] [blame] | 300 | $ sh ./t9200-git-cvsexport-commit.sh --run='1,2,3,21' |
Ilya Bobyr | 0445e6f | 2014-04-30 02:50:44 -0700 | [diff] [blame] | 301 | |
| 302 | or: |
| 303 | |
| 304 | $ sh ./t9200-git-cvsexport-commit.sh --run=1,2,3,21 |
| 305 | |
| 306 | or: |
| 307 | |
Elijah Newren | f21ac36 | 2020-10-18 00:23:45 +0000 | [diff] [blame] | 308 | $ sh ./t9200-git-cvsexport-commit.sh --run='-3,21' |
Ilya Bobyr | 0445e6f | 2014-04-30 02:50:44 -0700 | [diff] [blame] | 309 | |
Kaartic Sivaraam | 01e4be6 | 2017-09-17 10:18:15 +0000 | [diff] [blame] | 310 | As noted above, the test set is built by going through the items |
| 311 | from left to right, so this: |
Ilya Bobyr | 0445e6f | 2014-04-30 02:50:44 -0700 | [diff] [blame] | 312 | |
Elijah Newren | f21ac36 | 2020-10-18 00:23:45 +0000 | [diff] [blame] | 313 | $ sh ./t9200-git-cvsexport-commit.sh --run='1-4,!3' |
Ilya Bobyr | 0445e6f | 2014-04-30 02:50:44 -0700 | [diff] [blame] | 314 | |
Kaartic Sivaraam | 01e4be6 | 2017-09-17 10:18:15 +0000 | [diff] [blame] | 315 | will run tests 1, 2, and 4. Items that come later have higher |
Ville Skyttä | 2e3a16b | 2016-08-09 11:53:38 +0300 | [diff] [blame] | 316 | precedence. It means that this: |
Ilya Bobyr | 0445e6f | 2014-04-30 02:50:44 -0700 | [diff] [blame] | 317 | |
Elijah Newren | f21ac36 | 2020-10-18 00:23:45 +0000 | [diff] [blame] | 318 | $ sh ./t9200-git-cvsexport-commit.sh --run='!3,1-4' |
Ilya Bobyr | 0445e6f | 2014-04-30 02:50:44 -0700 | [diff] [blame] | 319 | |
| 320 | would just run tests from 1 to 4, including 3. |
| 321 | |
| 322 | You may use negation with ranges. The following will run all |
| 323 | test in the test suite except from 7 up to 11: |
| 324 | |
| 325 | $ sh ./t9200-git-cvsexport-commit.sh --run='!7-11' |
| 326 | |
Elijah Newren | f21ac36 | 2020-10-18 00:23:45 +0000 | [diff] [blame] | 327 | Sometimes there may be multiple tests with e.g. "setup" in their name |
| 328 | that are needed and rather than figuring out the number for all of them |
| 329 | we can just use "setup" as a substring/glob to match against the test |
| 330 | description: |
| 331 | |
| 332 | $ sh ./t0050-filesystem.sh --run=setup,9-11 |
| 333 | |
| 334 | or one could select both the setup tests and the rename ones (assuming all |
| 335 | relevant tests had those words in their descriptions): |
| 336 | |
| 337 | $ sh ./t0050-filesystem.sh --run=setup,rename |
| 338 | |
Ilya Bobyr | 0445e6f | 2014-04-30 02:50:44 -0700 | [diff] [blame] | 339 | Some tests in a test suite rely on the previous tests performing |
| 340 | certain actions, specifically some tests are designated as |
| 341 | "setup" test, so you cannot _arbitrarily_ disable one test and |
| 342 | expect the rest to function correctly. |
| 343 | |
| 344 | --run is mostly useful when you want to focus on a specific test |
| 345 | and know what setup is needed for it. Or when you want to run |
| 346 | everything up to a certain test. |
Jakub Narebski | fbd458a | 2008-06-20 23:10:50 +0200 | [diff] [blame] | 347 | |
| 348 | |
Nguyễn Thái Ngọc Duy | 4c2db93 | 2018-04-14 17:34:59 +0200 | [diff] [blame] | 349 | Running tests with special setups |
| 350 | --------------------------------- |
| 351 | |
| 352 | The whole test suite could be run to test some special features |
| 353 | that cannot be easily covered by a few specific test cases. These |
| 354 | could be enabled by running the test suite with correct GIT_TEST_ |
| 355 | environment set. |
| 356 | |
Ævar Arnfjörð Bjarmason | c740039 | 2019-06-21 12:18:12 +0200 | [diff] [blame] | 357 | GIT_TEST_FAIL_PREREQS=<boolean> fails all prerequisites. This is |
Ævar Arnfjörð Bjarmason | dfe1a17 | 2019-05-13 20:32:42 +0200 | [diff] [blame] | 358 | useful for discovering issues with the tests where say a later test |
| 359 | implicitly depends on an optional earlier test. |
| 360 | |
| 361 | There's a "FAIL_PREREQS" prerequisite that can be used to test for |
| 362 | whether this mode is active, and e.g. skip some tests that are hard to |
| 363 | refactor to deal with it. The "SYMLINKS" prerequisite is currently |
| 364 | excluded as so much relies on it, but this might change in the future. |
| 365 | |
Nguyễn Thái Ngọc Duy | 4c2db93 | 2018-04-14 17:34:59 +0200 | [diff] [blame] | 366 | GIT_TEST_SPLIT_INDEX=<boolean> forces split-index mode on the whole |
| 367 | test suite. Accept any boolean values that are accepted by git-config. |
| 368 | |
Jonathan Nieder | 33166f3 | 2019-12-23 17:02:28 -0800 | [diff] [blame] | 369 | GIT_TEST_PROTOCOL_VERSION=<n>, when set, makes 'protocol.version' |
| 370 | default to n. |
Jonathan Tan | 8cbeba0 | 2019-02-25 13:54:06 -0800 | [diff] [blame] | 371 | |
Nguyễn Thái Ngọc Duy | 43fa44f | 2018-04-14 17:35:05 +0200 | [diff] [blame] | 372 | GIT_TEST_FULL_IN_PACK_ARRAY=<boolean> exercises the uncommon |
| 373 | pack-objects code path where there are more than 1024 packs even if |
| 374 | the actual number of packs in repository is below this limit. Accept |
| 375 | any boolean values that are accepted by git-config. |
| 376 | |
Nguyễn Thái Ngọc Duy | ac77d0c | 2018-04-14 17:35:10 +0200 | [diff] [blame] | 377 | GIT_TEST_OE_SIZE=<n> exercises the uncommon pack-objects code path |
| 378 | where we do not cache object size in memory and read it from existing |
| 379 | packs on demand. This normally only happens when the object size is |
| 380 | over 2GB. This variable forces the code path on any object larger than |
| 381 | <n> bytes. |
| 382 | |
Ben Peart | ac6e12f | 2018-09-18 23:29:34 +0000 | [diff] [blame] | 383 | GIT_TEST_OE_DELTA_SIZE=<n> exercises the uncommon pack-objects code |
Nguyễn Thái Ngọc Duy | 9ac3f0e | 2018-07-22 10:04:21 +0200 | [diff] [blame] | 384 | path where deltas larger than this limit require extra memory |
| 385 | allocation for bookkeeping. |
| 386 | |
Nguyễn Thái Ngọc Duy | 5f4436a | 2018-08-25 15:02:09 +0200 | [diff] [blame] | 387 | GIT_TEST_VALIDATE_INDEX_CACHE_ENTRIES=<boolean> checks that cache-tree |
| 388 | records are valid when the index is written out or after a merge. This |
| 389 | is mostly to catch missing invalidation. Default is true. |
| 390 | |
Derrick Stolee | 859fdc0 | 2018-08-29 05:49:04 -0700 | [diff] [blame] | 391 | GIT_TEST_COMMIT_GRAPH=<boolean>, when true, forces the commit-graph to |
| 392 | be written after every 'git commit' command, and overrides the |
| 393 | 'core.commitGraph' setting to true. |
| 394 | |
Garima Singh | d5b873c | 2020-04-06 16:59:55 +0000 | [diff] [blame] | 395 | GIT_TEST_COMMIT_GRAPH_CHANGED_PATHS=<boolean>, when true, forces |
| 396 | commit-graph write to compute and write changed path Bloom filters for |
| 397 | every 'git commit-graph write', as if the `--changed-paths` option was |
| 398 | passed in. |
| 399 | |
Ben Peart | 4cb54d0 | 2018-09-18 23:29:35 +0000 | [diff] [blame] | 400 | GIT_TEST_FSMONITOR=$PWD/t7519/fsmonitor-all exercises the fsmonitor |
| 401 | code path for utilizing a file system monitor to speed up detecting |
| 402 | new or changed files. |
| 403 | |
Ben Peart | 1f357b0 | 2018-09-18 23:29:36 +0000 | [diff] [blame] | 404 | GIT_TEST_INDEX_VERSION=<n> exercises the index read/write code path |
| 405 | for the index version specified. Can be set to any valid version |
| 406 | (currently 2, 3, or 4). |
| 407 | |
Derrick Stolee | 2d657ab | 2020-03-20 12:38:10 +0000 | [diff] [blame] | 408 | GIT_TEST_PACK_SPARSE=<boolean> if disabled will default the pack-objects |
| 409 | builtin to use the non-sparse object walk. This can still be overridden by |
| 410 | the --sparse command-line argument. |
Derrick Stolee | 99dbbfa | 2019-01-16 10:26:01 -0800 | [diff] [blame] | 411 | |
Ben Peart | 5765d97 | 2018-09-18 23:29:37 +0000 | [diff] [blame] | 412 | GIT_TEST_PRELOAD_INDEX=<boolean> exercises the preload-index code path |
| 413 | by overriding the minimum number of cache entries required per thread. |
| 414 | |
Johannes Schindelin | f83dff6 | 2019-11-13 12:40:57 +0000 | [diff] [blame] | 415 | GIT_TEST_ADD_I_USE_BUILTIN=<boolean>, when true, enables the |
| 416 | built-in version of git add -i. See 'add.interactive.useBuiltin' in |
| 417 | git-config(1). |
| 418 | |
Ben Peart | c780b9c | 2018-10-10 11:59:35 -0400 | [diff] [blame] | 419 | GIT_TEST_INDEX_THREADS=<n> enables exercising the multi-threaded loading |
| 420 | of the index for the whole test suite by bypassing the default number of |
| 421 | cache entries and thread minimums. Setting this to 1 will make the |
| 422 | index loading single threaded. |
| 423 | |
Derrick Stolee | 0465a50 | 2018-10-12 10:34:20 -0700 | [diff] [blame] | 424 | GIT_TEST_MULTI_PACK_INDEX=<boolean>, when true, forces the multi-pack- |
| 425 | index to be written after every 'git repack' command, and overrides the |
| 426 | 'core.multiPackIndex' setting to true. |
| 427 | |
Jonathan Tan | 07c3c2a | 2019-01-16 11:28:15 -0800 | [diff] [blame] | 428 | GIT_TEST_SIDEBAND_ALL=<boolean>, when true, overrides the |
| 429 | 'uploadpack.allowSidebandAll' setting to true, and when false, forces |
| 430 | fetch-pack to not request sideband-all (even if the server advertises |
| 431 | sideband-all). |
| 432 | |
Johannes Schindelin | b02e7d5 | 2019-04-12 02:37:24 -0700 | [diff] [blame] | 433 | GIT_TEST_DISALLOW_ABBREVIATED_OPTIONS=<boolean>, when true (which is |
| 434 | the default when running tests), errors out when an abbreviated option |
| 435 | is used. |
| 436 | |
Derrick Stolee | f3d66ec | 2020-08-17 14:04:46 +0000 | [diff] [blame] | 437 | GIT_TEST_DEFAULT_HASH=<hash-algo> specifies which hash algorithm to |
| 438 | use in the test scripts. Recognized values for <hash-algo> are "sha1" |
| 439 | and "sha256". |
| 440 | |
Taylor Blau | e8c58f8 | 2021-01-25 18:37:42 -0500 | [diff] [blame] | 441 | GIT_TEST_WRITE_REV_INDEX=<boolean>, when true enables the |
| 442 | 'pack.writeReverseIndex' setting. |
| 443 | |
Derrick Stolee | ecfc47c | 2021-03-30 13:10:49 +0000 | [diff] [blame] | 444 | GIT_TEST_SPARSE_INDEX=<boolean>, when true enables index writes to use the |
| 445 | sparse-index format by default. |
| 446 | |
Matheus Tavares | 87094fc | 2021-05-04 13:27:35 -0300 | [diff] [blame] | 447 | GIT_TEST_CHECKOUT_WORKERS=<n> overrides the 'checkout.workers' setting |
| 448 | to <n> and 'checkout.thresholdForParallelism' to 0, forcing the |
| 449 | execution of the parallel-checkout code. |
| 450 | |
Petr Baudis | f50c9f7 | 2005-05-15 01:34:22 +0200 | [diff] [blame] | 451 | Naming Tests |
| 452 | ------------ |
| 453 | |
| 454 | The test files are named as: |
| 455 | |
| 456 | tNNNN-commandname-details.sh |
| 457 | |
| 458 | where N is a decimal digit. |
| 459 | |
| 460 | First digit tells the family: |
| 461 | |
| 462 | 0 - the absolute basics and global stuff |
| 463 | 1 - the basic commands concerning database |
| 464 | 2 - the basic commands concerning the working tree |
| 465 | 3 - the other basic commands (e.g. ls-files) |
| 466 | 4 - the diff commands |
| 467 | 5 - the pull and exporting commands |
| 468 | 6 - the revision tree commands (even e.g. merge-base) |
Junio C Hamano | 8f4a9b6 | 2006-06-28 11:45:52 -0700 | [diff] [blame] | 469 | 7 - the porcelainish commands concerning the working tree |
Jakub Narebski | 8757749 | 2006-12-29 14:39:09 +0100 | [diff] [blame] | 470 | 8 - the porcelainish commands concerning forensics |
| 471 | 9 - the git tools |
Petr Baudis | f50c9f7 | 2005-05-15 01:34:22 +0200 | [diff] [blame] | 472 | |
| 473 | Second digit tells the particular command we are testing. |
| 474 | |
| 475 | Third digit (optionally) tells the particular switch or group of switches |
| 476 | we are testing. |
| 477 | |
Junio C Hamano | 7765660 | 2005-07-07 11:39:10 -0700 | [diff] [blame] | 478 | If you create files under t/ directory (i.e. here) that is not |
| 479 | the top-level test script, never name the file to match the above |
| 480 | pattern. The Makefile here considers all such files as the |
Michael Witten | 63d3294 | 2011-02-22 17:15:00 +0000 | [diff] [blame] | 481 | top-level test script and tries to run all of them. Care is |
Junio C Hamano | 7765660 | 2005-07-07 11:39:10 -0700 | [diff] [blame] | 482 | especially needed if you are creating a common test library |
| 483 | file, similar to test-lib.sh, because such a library file may |
| 484 | not be suitable for standalone execution. |
| 485 | |
Petr Baudis | f50c9f7 | 2005-05-15 01:34:22 +0200 | [diff] [blame] | 486 | |
Junio C Hamano | 986aa7f | 2005-05-14 00:25:06 -0700 | [diff] [blame] | 487 | Writing Tests |
| 488 | ------------- |
| 489 | |
| 490 | The test script is written as a shell script. It should start |
Thomas Gummerer | 51b7a52 | 2017-11-26 20:20:59 +0000 | [diff] [blame] | 491 | with the standard "#!/bin/sh", and an |
Junio C Hamano | 986aa7f | 2005-05-14 00:25:06 -0700 | [diff] [blame] | 492 | assignment to variable 'test_description', like this: |
| 493 | |
| 494 | #!/bin/sh |
Junio C Hamano | 986aa7f | 2005-05-14 00:25:06 -0700 | [diff] [blame] | 495 | |
Junio C Hamano | 14cd1ff | 2005-05-15 14:21:13 -0700 | [diff] [blame] | 496 | test_description='xxx test (option --frotz) |
Junio C Hamano | 986aa7f | 2005-05-14 00:25:06 -0700 | [diff] [blame] | 497 | |
| 498 | This test registers the following structure in the cache |
| 499 | and tries to run git-ls-files with option --frotz.' |
| 500 | |
Petr Baudis | f50c9f7 | 2005-05-15 01:34:22 +0200 | [diff] [blame] | 501 | |
Junio C Hamano | 986aa7f | 2005-05-14 00:25:06 -0700 | [diff] [blame] | 502 | Source 'test-lib.sh' |
| 503 | -------------------- |
| 504 | |
| 505 | After assigning test_description, the test script should source |
| 506 | test-lib.sh like this: |
| 507 | |
| 508 | . ./test-lib.sh |
| 509 | |
| 510 | This test harness library does the following things: |
| 511 | |
| 512 | - If the script is invoked with command line argument --help |
| 513 | (or -h), it shows the test_description and exits. |
| 514 | |
Ævar Arnfjörð Bjarmason | e1ca1c9 | 2010-07-02 14:59:43 +0000 | [diff] [blame] | 515 | - Creates an empty test directory with an empty .git/objects database |
| 516 | and chdir(2) into it. This directory is 't/trash |
| 517 | directory.$test_name_without_dotsh', with t/ subject to change by |
SZEDER Gábor | fb7d1e3 | 2019-01-05 02:08:59 +0100 | [diff] [blame] | 518 | the --root option documented above, and a '.stress-<N>' suffix |
| 519 | appended by the --stress option. |
Junio C Hamano | 986aa7f | 2005-05-14 00:25:06 -0700 | [diff] [blame] | 520 | |
| 521 | - Defines standard test helper functions for your scripts to |
| 522 | use. These functions are designed to make all scripts behave |
| 523 | consistently when command line arguments --verbose (or -v), |
| 524 | --debug (or -d), and --immediate (or -i) is given. |
| 525 | |
Matthew DeVore | 441ee35 | 2018-10-05 14:54:01 -0700 | [diff] [blame] | 526 | Do's & don'ts |
| 527 | ------------- |
Ævar Arnfjörð Bjarmason | 20873f4 | 2010-07-02 14:59:49 +0000 | [diff] [blame] | 528 | |
Junio C Hamano | 6fd4529 | 2010-07-05 11:37:30 -0700 | [diff] [blame] | 529 | Here are a few examples of things you probably should and shouldn't do |
Ævar Arnfjörð Bjarmason | 20873f4 | 2010-07-02 14:59:49 +0000 | [diff] [blame] | 530 | when writing tests. |
| 531 | |
Matthew DeVore | 441ee35 | 2018-10-05 14:54:01 -0700 | [diff] [blame] | 532 | Here are the "do's:" |
Ævar Arnfjörð Bjarmason | 20873f4 | 2010-07-02 14:59:49 +0000 | [diff] [blame] | 533 | |
Junio C Hamano | 6fd4529 | 2010-07-05 11:37:30 -0700 | [diff] [blame] | 534 | - Put all code inside test_expect_success and other assertions. |
Ævar Arnfjörð Bjarmason | 20873f4 | 2010-07-02 14:59:49 +0000 | [diff] [blame] | 535 | |
| 536 | Even code that isn't a test per se, but merely some setup code |
Junio C Hamano | 6fd4529 | 2010-07-05 11:37:30 -0700 | [diff] [blame] | 537 | should be inside a test assertion. |
Ævar Arnfjörð Bjarmason | 20873f4 | 2010-07-02 14:59:49 +0000 | [diff] [blame] | 538 | |
| 539 | - Chain your test assertions |
| 540 | |
| 541 | Write test code like this: |
| 542 | |
| 543 | git merge foo && |
| 544 | git push bar && |
| 545 | test ... |
| 546 | |
| 547 | Instead of: |
| 548 | |
| 549 | git merge hla |
| 550 | git push gh |
| 551 | test ... |
| 552 | |
| 553 | That way all of the commands in your tests will succeed or fail. If |
Elijah Newren | 00648ba | 2010-10-03 14:00:14 -0600 | [diff] [blame] | 554 | you must ignore the return value of something, consider using a |
| 555 | helper function (e.g. use sane_unset instead of unset, in order |
| 556 | to avoid unportable return value for unsetting a variable that was |
| 557 | already unset), or prepending the command with test_might_fail or |
| 558 | test_must_fail. |
Ævar Arnfjörð Bjarmason | 20873f4 | 2010-07-02 14:59:49 +0000 | [diff] [blame] | 559 | |
Ævar Arnfjörð Bjarmason | 0c35754 | 2010-07-25 19:52:44 +0000 | [diff] [blame] | 560 | - Check the test coverage for your tests. See the "Test coverage" |
| 561 | below. |
| 562 | |
Michael Witten | 63d3294 | 2011-02-22 17:15:00 +0000 | [diff] [blame] | 563 | Don't blindly follow test coverage metrics; if a new function you added |
| 564 | doesn't have any coverage, then you're probably doing something wrong, |
Ævar Arnfjörð Bjarmason | e8b55f5 | 2010-07-25 19:52:45 +0000 | [diff] [blame] | 565 | but having 100% coverage doesn't necessarily mean that you tested |
| 566 | everything. |
| 567 | |
| 568 | Tests that are likely to smoke out future regressions are better |
| 569 | than tests that just inflate the coverage metrics. |
| 570 | |
Johannes Sixt | 95b104c | 2011-01-11 08:44:30 +0100 | [diff] [blame] | 571 | - When a test checks for an absolute path that a git command generated, |
| 572 | construct the expected value using $(pwd) rather than $PWD, |
| 573 | $TEST_DIRECTORY, or $TRASH_DIRECTORY. It makes a difference on |
| 574 | Windows, where the shell (MSYS bash) mangles absolute path names. |
| 575 | For details, see the commit message of 4114156ae9. |
| 576 | |
Matthew DeVore | 441ee35 | 2018-10-05 14:54:01 -0700 | [diff] [blame] | 577 | - Remember that inside the <script> part, the standard output and |
| 578 | standard error streams are discarded, and the test harness only |
| 579 | reports "ok" or "not ok" to the end user running the tests. Under |
| 580 | --verbose, they are shown to help debug the tests. |
Ævar Arnfjörð Bjarmason | 20873f4 | 2010-07-02 14:59:49 +0000 | [diff] [blame] | 581 | |
Junio C Hamano | 7cc112d | 2020-03-27 10:55:09 -0700 | [diff] [blame] | 582 | - Be careful when you loop |
| 583 | |
| 584 | You may need to verify multiple things in a loop, but the |
| 585 | following does not work correctly: |
| 586 | |
| 587 | test_expect_success 'test three things' ' |
| 588 | for i in one two three |
| 589 | do |
| 590 | test_something "$i" |
| 591 | done && |
| 592 | test_something_else |
| 593 | ' |
| 594 | |
| 595 | Because the status of the loop itself is the exit status of the |
| 596 | test_something in the last round, the loop does not fail when |
| 597 | "test_something" for "one" or "two" fails. This is not what you |
| 598 | want. |
| 599 | |
| 600 | Instead, you can break out of the loop immediately when you see a |
| 601 | failure. Because all test_expect_* snippets are executed inside |
| 602 | a function, "return 1" can be used to fail the test immediately |
| 603 | upon a failure: |
| 604 | |
| 605 | test_expect_success 'test three things' ' |
| 606 | for i in one two three |
| 607 | do |
| 608 | test_something "$i" || return 1 |
| 609 | done && |
| 610 | test_something_else |
| 611 | ' |
| 612 | |
| 613 | Note that we still &&-chain the loop to propagate failures from |
| 614 | earlier commands. |
| 615 | |
| 616 | |
Matthew DeVore | 441ee35 | 2018-10-05 14:54:01 -0700 | [diff] [blame] | 617 | And here are the "don'ts:" |
| 618 | |
| 619 | - Don't exit() within a <script> part. |
Ævar Arnfjörð Bjarmason | 20873f4 | 2010-07-02 14:59:49 +0000 | [diff] [blame] | 620 | |
| 621 | The harness will catch this as a programming error of the test. |
| 622 | Use test_done instead if you need to stop the tests early (see |
| 623 | "Skipping tests" below). |
| 624 | |
Matthew DeVore | 441ee35 | 2018-10-05 14:54:01 -0700 | [diff] [blame] | 625 | - Don't use '! git cmd' when you want to make sure the git command |
| 626 | exits with failure in a controlled way by calling "die()". Instead, |
Junio C Hamano | ad78585 | 2012-06-12 09:44:56 -0700 | [diff] [blame] | 627 | use 'test_must_fail git cmd'. This will signal a failure if git |
| 628 | dies in an unexpected way (e.g. segfault). |
| 629 | |
Junio C Hamano | f445500 | 2013-06-04 09:50:12 -0700 | [diff] [blame] | 630 | On the other hand, don't use test_must_fail for running regular |
Junio C Hamano | 53de742 | 2014-11-24 09:47:07 -0800 | [diff] [blame] | 631 | platform commands; just use '! cmd'. We are not in the business |
| 632 | of verifying that the world given to us sanely works. |
Junio C Hamano | f445500 | 2013-06-04 09:50:12 -0700 | [diff] [blame] | 633 | |
Matthew DeVore | a378fee | 2018-10-05 14:54:02 -0700 | [diff] [blame] | 634 | - Don't feed the output of a git command to a pipe, as in: |
| 635 | |
| 636 | git -C repo ls-files | |
| 637 | xargs -n 1 basename | |
| 638 | grep foo |
| 639 | |
| 640 | which will discard git's exit code and may mask a crash. In the |
| 641 | above example, all exit codes are ignored except grep's. |
| 642 | |
| 643 | Instead, write the output of that command to a temporary |
| 644 | file with ">" or assign it to a variable with "x=$(git ...)" rather |
| 645 | than pipe it. |
| 646 | |
| 647 | - Don't use command substitution in a way that discards git's exit |
| 648 | code. When assigning to a variable, the exit code is not discarded, |
| 649 | e.g.: |
| 650 | |
| 651 | x=$(git cat-file -p $sha) && |
| 652 | ... |
| 653 | |
| 654 | is OK because a crash in "git cat-file" will cause the "&&" chain |
| 655 | to fail, but: |
| 656 | |
| 657 | test "refs/heads/foo" = "$(git symbolic-ref HEAD)" |
| 658 | |
| 659 | is not OK and a crash in git could go undetected. |
| 660 | |
Matthew DeVore | 441ee35 | 2018-10-05 14:54:01 -0700 | [diff] [blame] | 661 | - Don't use perl without spelling it as "$PERL_PATH". This is to help |
| 662 | our friends on Windows where the platform Perl often adds CR before |
Junio C Hamano | ad78585 | 2012-06-12 09:44:56 -0700 | [diff] [blame] | 663 | the end of line, and they bundle Git with a version of Perl that |
Jeff King | a0e0ec9 | 2013-10-28 21:22:07 -0400 | [diff] [blame] | 664 | does not do so, whose path is specified with $PERL_PATH. Note that we |
| 665 | provide a "perl" function which uses $PERL_PATH under the hood, so |
| 666 | you do not need to worry when simply running perl in the test scripts |
| 667 | (but you do, for example, on a shebang line or in a sub script |
| 668 | created via "write_script"). |
Junio C Hamano | ad78585 | 2012-06-12 09:44:56 -0700 | [diff] [blame] | 669 | |
Matthew DeVore | 441ee35 | 2018-10-05 14:54:01 -0700 | [diff] [blame] | 670 | - Don't use sh without spelling it as "$SHELL_PATH", when the script |
| 671 | can be misinterpreted by broken platform shell (e.g. Solaris). |
Junio C Hamano | ad78585 | 2012-06-12 09:44:56 -0700 | [diff] [blame] | 672 | |
Matthew DeVore | 441ee35 | 2018-10-05 14:54:01 -0700 | [diff] [blame] | 673 | - Don't chdir around in tests. It is not sufficient to chdir to |
Junio C Hamano | ad78585 | 2012-06-12 09:44:56 -0700 | [diff] [blame] | 674 | somewhere and then chdir back to the original location later in |
| 675 | the test, as any intermediate step can fail and abort the test, |
| 676 | causing the next test to start in an unexpected directory. Do so |
| 677 | inside a subshell if necessary. |
| 678 | |
Matthew DeVore | 441ee35 | 2018-10-05 14:54:01 -0700 | [diff] [blame] | 679 | - Don't save and verify the standard error of compound commands, i.e. |
| 680 | group commands, subshells, and shell functions (except test helper |
SZEDER Gábor | 94201a2 | 2018-02-24 00:39:50 +0100 | [diff] [blame] | 681 | functions like 'test_must_fail') like this: |
| 682 | |
| 683 | ( cd dir && git cmd ) 2>error && |
| 684 | test_cmp expect error |
| 685 | |
| 686 | When running the test with '-x' tracing, then the trace of commands |
| 687 | executed in the compound command will be included in standard error |
| 688 | as well, quite possibly throwing off the subsequent checks examining |
| 689 | the output. Instead, save only the relevant git command's standard |
| 690 | error: |
| 691 | |
| 692 | ( cd dir && git cmd 2>../error ) && |
| 693 | test_cmp expect error |
| 694 | |
Matthew DeVore | 441ee35 | 2018-10-05 14:54:01 -0700 | [diff] [blame] | 695 | - Don't break the TAP output |
Ævar Arnfjörð Bjarmason | 20873f4 | 2010-07-02 14:59:49 +0000 | [diff] [blame] | 696 | |
Junio C Hamano | 6fd4529 | 2010-07-05 11:37:30 -0700 | [diff] [blame] | 697 | The raw output from your test may be interpreted by a TAP harness. TAP |
| 698 | harnesses will ignore everything they don't know about, but don't step |
| 699 | on their toes in these areas: |
Ævar Arnfjörð Bjarmason | 20873f4 | 2010-07-02 14:59:49 +0000 | [diff] [blame] | 700 | |
| 701 | - Don't print lines like "$x..$y" where $x and $y are integers. |
| 702 | |
| 703 | - Don't print lines that begin with "ok" or "not ok". |
| 704 | |
Junio C Hamano | 6fd4529 | 2010-07-05 11:37:30 -0700 | [diff] [blame] | 705 | TAP harnesses expect a line that begins with either "ok" and "not |
Ævar Arnfjörð Bjarmason | 20873f4 | 2010-07-02 14:59:49 +0000 | [diff] [blame] | 706 | ok" to signal a test passed or failed (and our harness already |
| 707 | produces such lines), so your script shouldn't emit such lines to |
| 708 | their output. |
| 709 | |
| 710 | You can glean some further possible issues from the TAP grammar |
Ævar Arnfjörð Bjarmason | c1d44ce | 2017-03-22 22:18:52 +0000 | [diff] [blame] | 711 | (see https://metacpan.org/pod/TAP::Parser::Grammar#TAP-GRAMMAR) |
Ævar Arnfjörð Bjarmason | 20873f4 | 2010-07-02 14:59:49 +0000 | [diff] [blame] | 712 | but the best indication is to just run the tests with prove(1), |
| 713 | it'll complain if anything is amiss. |
| 714 | |
Ævar Arnfjörð Bjarmason | 20873f4 | 2010-07-02 14:59:49 +0000 | [diff] [blame] | 715 | |
Ævar Arnfjörð Bjarmason | b5500d1 | 2010-07-02 14:59:48 +0000 | [diff] [blame] | 716 | Skipping tests |
| 717 | -------------- |
| 718 | |
Mathias Lafeldt | 681186a | 2011-03-09 21:25:09 +0100 | [diff] [blame] | 719 | If you need to skip tests you should do so by using the three-arg form |
Ævar Arnfjörð Bjarmason | 99d9050 | 2010-07-28 10:34:59 +0000 | [diff] [blame] | 720 | of the test_* functions (see the "Test harness library" section |
| 721 | below), e.g.: |
| 722 | |
Junio C Hamano | ad78585 | 2012-06-12 09:44:56 -0700 | [diff] [blame] | 723 | test_expect_success PERL 'I need Perl' ' |
Jeff King | a0e0ec9 | 2013-10-28 21:22:07 -0400 | [diff] [blame] | 724 | perl -e "hlagh() if unf_unf()" |
Junio C Hamano | ad78585 | 2012-06-12 09:44:56 -0700 | [diff] [blame] | 725 | ' |
Ævar Arnfjörð Bjarmason | 99d9050 | 2010-07-28 10:34:59 +0000 | [diff] [blame] | 726 | |
| 727 | The advantage of skipping tests like this is that platforms that don't |
| 728 | have the PERL and other optional dependencies get an indication of how |
| 729 | many tests they're missing. |
| 730 | |
| 731 | If the test code is too hairy for that (i.e. does a lot of setup work |
| 732 | outside test assertions) you can also skip all remaining tests by |
| 733 | setting skip_all and immediately call test_done: |
Ævar Arnfjörð Bjarmason | b5500d1 | 2010-07-02 14:59:48 +0000 | [diff] [blame] | 734 | |
| 735 | if ! test_have_prereq PERL |
| 736 | then |
| 737 | skip_all='skipping perl interface tests, perl not available' |
| 738 | test_done |
| 739 | fi |
Junio C Hamano | 14cd1ff | 2005-05-15 14:21:13 -0700 | [diff] [blame] | 740 | |
Ævar Arnfjörð Bjarmason | 99d9050 | 2010-07-28 10:34:59 +0000 | [diff] [blame] | 741 | The string you give to skip_all will be used as an explanation for why |
| 742 | the test was skipped. |
| 743 | |
Junio C Hamano | 986aa7f | 2005-05-14 00:25:06 -0700 | [diff] [blame] | 744 | End with test_done |
| 745 | ------------------ |
| 746 | |
| 747 | Your script will be a sequence of tests, using helper functions |
| 748 | from the test harness library. At the end of the script, call |
| 749 | 'test_done'. |
| 750 | |
| 751 | |
| 752 | Test harness library |
| 753 | -------------------- |
| 754 | |
| 755 | There are a handful helper functions defined in the test harness |
| 756 | library for your script to use. |
| 757 | |
Ævar Arnfjörð Bjarmason | 9a89789 | 2010-07-02 14:59:45 +0000 | [diff] [blame] | 758 | - test_expect_success [<prereq>] <message> <script> |
Junio C Hamano | 986aa7f | 2005-05-14 00:25:06 -0700 | [diff] [blame] | 759 | |
Mathias Lafeldt | 72942a6 | 2011-04-26 12:33:26 +0200 | [diff] [blame] | 760 | Usually takes two strings as parameters, and evaluates the |
Junio C Hamano | 986aa7f | 2005-05-14 00:25:06 -0700 | [diff] [blame] | 761 | <script>. If it yields success, test is considered |
| 762 | successful. <message> should state what it is testing. |
| 763 | |
| 764 | Example: |
| 765 | |
| 766 | test_expect_success \ |
| 767 | 'git-write-tree should be able to write an empty tree.' \ |
| 768 | 'tree=$(git-write-tree)' |
| 769 | |
Ævar Arnfjörð Bjarmason | 9a89789 | 2010-07-02 14:59:45 +0000 | [diff] [blame] | 770 | If you supply three parameters the first will be taken to be a |
Mathias Lafeldt | 72942a6 | 2011-04-26 12:33:26 +0200 | [diff] [blame] | 771 | prerequisite; see the test_set_prereq and test_have_prereq |
Ævar Arnfjörð Bjarmason | 9a89789 | 2010-07-02 14:59:45 +0000 | [diff] [blame] | 772 | documentation below: |
| 773 | |
| 774 | test_expect_success TTY 'git --paginate rev-list uses a pager' \ |
| 775 | ' ... ' |
| 776 | |
Ævar Arnfjörð Bjarmason | 93a5724 | 2010-08-06 21:19:23 +0000 | [diff] [blame] | 777 | You can also supply a comma-separated list of prerequisites, in the |
| 778 | rare case where your test depends on more than one: |
| 779 | |
| 780 | test_expect_success PERL,PYTHON 'yo dawg' \ |
| 781 | ' test $(perl -E 'print eval "1 +" . qx[python -c "print 2"]') == "4" ' |
| 782 | |
Ævar Arnfjörð Bjarmason | 9a89789 | 2010-07-02 14:59:45 +0000 | [diff] [blame] | 783 | - test_expect_failure [<prereq>] <message> <script> |
Junio C Hamano | 986aa7f | 2005-05-14 00:25:06 -0700 | [diff] [blame] | 784 | |
Junio C Hamano | 41ac414 | 2008-02-01 01:50:53 -0800 | [diff] [blame] | 785 | This is NOT the opposite of test_expect_success, but is used |
| 786 | to mark a test that demonstrates a known breakage. Unlike |
| 787 | the usual test_expect_success tests, which say "ok" on |
| 788 | success and "FAIL" on failure, this will say "FIXED" on |
| 789 | success and "still broken" on failure. Failures from these |
| 790 | tests won't cause -i (immediate) to stop. |
Junio C Hamano | 986aa7f | 2005-05-14 00:25:06 -0700 | [diff] [blame] | 791 | |
Ævar Arnfjörð Bjarmason | 9a89789 | 2010-07-02 14:59:45 +0000 | [diff] [blame] | 792 | Like test_expect_success this function can optionally use a three |
| 793 | argument invocation with a prerequisite as the first argument. |
| 794 | |
Junio C Hamano | 986aa7f | 2005-05-14 00:25:06 -0700 | [diff] [blame] | 795 | - test_debug <script> |
| 796 | |
| 797 | This takes a single argument, <script>, and evaluates it only |
| 798 | when the test script is started with --debug command line |
| 799 | argument. This is primarily meant for use during the |
| 800 | development of a new test script. |
| 801 | |
Johannes Schindelin | 6a94088 | 2015-10-30 12:02:56 -0700 | [diff] [blame] | 802 | - debug <git-command> |
| 803 | |
| 804 | Run a git command inside a debugger. This is primarily meant for |
| 805 | use when debugging a failing test script. |
| 806 | |
Junio C Hamano | 986aa7f | 2005-05-14 00:25:06 -0700 | [diff] [blame] | 807 | - test_done |
| 808 | |
| 809 | Your test script must have test_done at the end. Its purpose |
| 810 | is to summarize successes and failures in the test script and |
| 811 | exit with an appropriate error code. |
| 812 | |
Johannes Schindelin | 0088496 | 2009-01-27 23:34:48 +0100 | [diff] [blame] | 813 | - test_tick |
| 814 | |
| 815 | Make commit and tag names consistent by setting the author and |
Michael Witten | 63d3294 | 2011-02-22 17:15:00 +0000 | [diff] [blame] | 816 | committer times to defined state. Subsequent calls will |
Johannes Schindelin | 0088496 | 2009-01-27 23:34:48 +0100 | [diff] [blame] | 817 | advance the times by a fixed amount. |
| 818 | |
| 819 | - test_commit <message> [<filename> [<contents>]] |
| 820 | |
| 821 | Creates a commit with the given message, committing the given |
| 822 | file with the given contents (default for both is to reuse the |
| 823 | message string), and adds a tag (again reusing the message |
| 824 | string as name). Calls test_tick to make the SHA-1s |
| 825 | reproducible. |
| 826 | |
| 827 | - test_merge <message> <commit-or-tag> |
| 828 | |
| 829 | Merges the given rev using the given message. Like test_commit, |
| 830 | creates a tag and calls test_tick before committing. |
Junio C Hamano | 986aa7f | 2005-05-14 00:25:06 -0700 | [diff] [blame] | 831 | |
Mathias Lafeldt | 72942a6 | 2011-04-26 12:33:26 +0200 | [diff] [blame] | 832 | - test_set_prereq <prereq> |
Ævar Arnfjörð Bjarmason | 9a89789 | 2010-07-02 14:59:45 +0000 | [diff] [blame] | 833 | |
| 834 | Set a test prerequisite to be used later with test_have_prereq. The |
Ævar Arnfjörð Bjarmason | be53dee | 2010-08-06 21:19:25 +0000 | [diff] [blame] | 835 | test-lib will set some prerequisites for you, see the |
| 836 | "Prerequisites" section below for a full list of these. |
| 837 | |
| 838 | Others you can set yourself and use later with either |
| 839 | test_have_prereq directly, or the three argument invocation of |
| 840 | test_expect_success and test_expect_failure. |
Ævar Arnfjörð Bjarmason | 9a89789 | 2010-07-02 14:59:45 +0000 | [diff] [blame] | 841 | |
Mathias Lafeldt | 72942a6 | 2011-04-26 12:33:26 +0200 | [diff] [blame] | 842 | - test_have_prereq <prereq> |
Ævar Arnfjörð Bjarmason | 9a89789 | 2010-07-02 14:59:45 +0000 | [diff] [blame] | 843 | |
Ævar Arnfjörð Bjarmason | 4473060 | 2017-03-22 22:18:54 +0000 | [diff] [blame] | 844 | Check if we have a prerequisite previously set with test_set_prereq. |
| 845 | The most common way to use this explicitly (as opposed to the |
| 846 | implicit use when an argument is passed to test_expect_*) is to skip |
| 847 | all the tests at the start of the test script if we don't have some |
| 848 | essential prerequisite: |
Ævar Arnfjörð Bjarmason | 9a89789 | 2010-07-02 14:59:45 +0000 | [diff] [blame] | 849 | |
| 850 | if ! test_have_prereq PERL |
| 851 | then |
| 852 | skip_all='skipping perl interface tests, perl not available' |
| 853 | test_done |
| 854 | fi |
| 855 | |
Ævar Arnfjörð Bjarmason | 2fac6a4 | 2010-07-02 14:59:46 +0000 | [diff] [blame] | 856 | - test_external [<prereq>] <message> <external> <script> |
| 857 | |
| 858 | Execute a <script> with an <external> interpreter (like perl). This |
| 859 | was added for tests like t9700-perl-git.sh which do most of their |
| 860 | work in an external test script. |
| 861 | |
| 862 | test_external \ |
| 863 | 'GitwebCache::*FileCache*' \ |
Jeff King | a0e0ec9 | 2013-10-28 21:22:07 -0400 | [diff] [blame] | 864 | perl "$TEST_DIRECTORY"/t9503/test_cache_interface.pl |
Ævar Arnfjörð Bjarmason | 2fac6a4 | 2010-07-02 14:59:46 +0000 | [diff] [blame] | 865 | |
| 866 | If the test is outputting its own TAP you should set the |
| 867 | test_external_has_tap variable somewhere before calling the first |
| 868 | test_external* function. See t9700-perl-git.sh for an example. |
| 869 | |
| 870 | # The external test will outputs its own plan |
| 871 | test_external_has_tap=1 |
| 872 | |
| 873 | - test_external_without_stderr [<prereq>] <message> <external> <script> |
| 874 | |
| 875 | Like test_external but fail if there's any output on stderr, |
| 876 | instead of checking the exit code. |
| 877 | |
| 878 | test_external_without_stderr \ |
| 879 | 'Perl API' \ |
Jeff King | a0e0ec9 | 2013-10-28 21:22:07 -0400 | [diff] [blame] | 880 | perl "$TEST_DIRECTORY"/t9700/test.pl |
Ævar Arnfjörð Bjarmason | 2fac6a4 | 2010-07-02 14:59:46 +0000 | [diff] [blame] | 881 | |
Ævar Arnfjörð Bjarmason | 892e6f7 | 2010-10-03 13:59:59 -0600 | [diff] [blame] | 882 | - test_expect_code <exit-code> <command> |
| 883 | |
| 884 | Run a command and ensure that it exits with the given exit code. |
| 885 | For example: |
| 886 | |
| 887 | test_expect_success 'Merge with d/f conflicts' ' |
| 888 | test_expect_code 1 git merge "merge msg" B master |
| 889 | ' |
| 890 | |
SZEDER Gábor | 12e31a6 | 2018-02-09 03:42:33 +0100 | [diff] [blame] | 891 | - test_must_fail [<options>] <git-command> |
Jonathan Nieder | c966745 | 2010-07-06 15:04:10 -0500 | [diff] [blame] | 892 | |
| 893 | Run a git command and ensure it fails in a controlled way. Use |
Brandon Casey | 971ecbd | 2010-07-20 12:17:12 -0500 | [diff] [blame] | 894 | this instead of "! <git-command>". When git-command dies due to a |
| 895 | segfault, test_must_fail diagnoses it as an error; "! <git-command>" |
| 896 | treats it as just another expected failure, which would let such a |
| 897 | bug go unnoticed. |
Jonathan Nieder | c966745 | 2010-07-06 15:04:10 -0500 | [diff] [blame] | 898 | |
SZEDER Gábor | 12e31a6 | 2018-02-09 03:42:33 +0100 | [diff] [blame] | 899 | Accepts the following options: |
| 900 | |
| 901 | ok=<signal-name>[,<...>]: |
| 902 | Don't treat an exit caused by the given signal as error. |
| 903 | Multiple signals can be specified as a comma separated list. |
| 904 | Currently recognized signal names are: sigpipe, success. |
| 905 | (Don't use 'success', use 'test_might_fail' instead.) |
| 906 | |
| 907 | - test_might_fail [<options>] <git-command> |
Jonathan Nieder | c966745 | 2010-07-06 15:04:10 -0500 | [diff] [blame] | 908 | |
| 909 | Similar to test_must_fail, but tolerate success, too. Use this |
| 910 | instead of "<git-command> || :" to catch failures due to segv. |
| 911 | |
SZEDER Gábor | 12e31a6 | 2018-02-09 03:42:33 +0100 | [diff] [blame] | 912 | Accepts the same options as test_must_fail. |
| 913 | |
Jonathan Nieder | c966745 | 2010-07-06 15:04:10 -0500 | [diff] [blame] | 914 | - test_cmp <expected> <actual> |
| 915 | |
| 916 | Check whether the content of the <actual> file matches the |
| 917 | <expected> file. This behaves like "cmp" but produces more |
| 918 | helpful output when the test is run with "-v" option. |
| 919 | |
Thomas Gummerer | 5a05262 | 2017-11-26 20:21:00 +0000 | [diff] [blame] | 920 | - test_cmp_rev <expected> <actual> |
| 921 | |
| 922 | Check whether the <expected> rev points to the same commit as the |
| 923 | <actual> rev. |
| 924 | |
Jonathan Nieder | fb3340a | 2010-10-31 02:33:50 -0500 | [diff] [blame] | 925 | - test_line_count (= | -lt | -ge | ...) <length> <file> |
| 926 | |
| 927 | Check whether a file has the length it is expected to. |
| 928 | |
Ævar Arnfjörð Bjarmason | 45a2686 | 2021-02-12 14:29:41 +0100 | [diff] [blame] | 929 | - test_path_is_file <path> |
| 930 | test_path_is_dir <path> |
| 931 | test_path_is_missing <path> |
Matthieu Moy | 2caf20c | 2010-08-10 17:17:52 +0200 | [diff] [blame] | 932 | |
Mathias Lafeldt | 72942a6 | 2011-04-26 12:33:26 +0200 | [diff] [blame] | 933 | Check if the named path is a file, if the named path is a |
| 934 | directory, or if the named path does not exist, respectively, |
Ævar Arnfjörð Bjarmason | 45a2686 | 2021-02-12 14:29:41 +0100 | [diff] [blame] | 935 | and fail otherwise. |
Matthieu Moy | 2caf20c | 2010-08-10 17:17:52 +0200 | [diff] [blame] | 936 | |
Jonathan Nieder | c966745 | 2010-07-06 15:04:10 -0500 | [diff] [blame] | 937 | - test_when_finished <script> |
| 938 | |
| 939 | Prepend <script> to a list of commands to run to clean up |
| 940 | at the end of the current test. If some clean-up command |
| 941 | fails, the test will not pass. |
| 942 | |
| 943 | Example: |
| 944 | |
| 945 | test_expect_success 'branch pointing to non-commit' ' |
| 946 | git rev-parse HEAD^{tree} >.git/refs/heads/invalid && |
| 947 | test_when_finished "git update-ref -d refs/heads/invalid" && |
| 948 | ... |
| 949 | ' |
| 950 | |
Johannes Schindelin | 900721e | 2019-03-13 13:24:11 +0100 | [diff] [blame] | 951 | - test_atexit <script> |
| 952 | |
| 953 | Prepend <script> to a list of commands to run unconditionally to |
| 954 | clean up before the test script exits, e.g. to stop a daemon: |
| 955 | |
| 956 | test_expect_success 'test git daemon' ' |
| 957 | git daemon & |
| 958 | daemon_pid=$! && |
| 959 | test_atexit 'kill $daemon_pid' && |
| 960 | hello world |
| 961 | ' |
| 962 | |
| 963 | The commands will be executed before the trash directory is removed, |
| 964 | i.e. the atexit commands will still be able to access any pidfiles or |
| 965 | socket files. |
| 966 | |
| 967 | Note that these commands will be run even when a test script run |
| 968 | with '--immediate' fails. Be careful with your atexit commands to |
| 969 | minimize any changes to the failed state. |
| 970 | |
Jonathan Nieder | bb98b01 | 2014-05-05 16:51:43 -0700 | [diff] [blame] | 971 | - test_write_lines <lines> |
Michael S. Tsirkin | ac9afcc | 2014-04-27 21:15:47 +0300 | [diff] [blame] | 972 | |
Jonathan Nieder | bb98b01 | 2014-05-05 16:51:43 -0700 | [diff] [blame] | 973 | Write <lines> on standard output, one line per argument. |
Michael S. Tsirkin | ac9afcc | 2014-04-27 21:15:47 +0300 | [diff] [blame] | 974 | Useful to prepare multi-line files in a compact form. |
| 975 | |
| 976 | Example: |
| 977 | |
Jonathan Nieder | bb98b01 | 2014-05-05 16:51:43 -0700 | [diff] [blame] | 978 | test_write_lines a b c d e f g >foo |
Michael S. Tsirkin | ac9afcc | 2014-04-27 21:15:47 +0300 | [diff] [blame] | 979 | |
| 980 | Is a more compact equivalent of: |
| 981 | cat >foo <<-EOF |
| 982 | a |
| 983 | b |
| 984 | c |
| 985 | d |
| 986 | e |
| 987 | f |
| 988 | g |
| 989 | EOF |
| 990 | |
| 991 | |
Jens Lehmann | c4d2539 | 2012-01-17 22:04:31 +0100 | [diff] [blame] | 992 | - test_pause |
| 993 | |
| 994 | This command is useful for writing and debugging tests and must be |
| 995 | removed before submitting. It halts the execution of the test and |
| 996 | spawns a shell in the trash directory. Exit the shell to continue |
| 997 | the test. Example: |
| 998 | |
| 999 | test_expect_success 'test' ' |
| 1000 | git do-something >actual && |
| 1001 | test_pause && |
| 1002 | test_cmp expected actual |
| 1003 | ' |
| 1004 | |
Johannes Sixt | 9ce415d | 2013-06-07 22:53:27 +0200 | [diff] [blame] | 1005 | - test_ln_s_add <path1> <path2> |
| 1006 | |
| 1007 | This function helps systems whose filesystem does not support symbolic |
| 1008 | links. Use it to add a symbolic link entry to the index when it is not |
| 1009 | important that the file system entry is a symbolic link, i.e., instead |
| 1010 | of the sequence |
| 1011 | |
| 1012 | ln -s foo bar && |
| 1013 | git add bar |
| 1014 | |
| 1015 | Sometimes it is possible to split a test in a part that does not need |
| 1016 | the symbolic link in the file system and a part that does; then only |
| 1017 | the latter part need be protected by a SYMLINKS prerequisite (see below). |
| 1018 | |
brian m. carlson | 2c02b11 | 2018-09-13 05:17:31 +0000 | [diff] [blame] | 1019 | - test_oid_init |
| 1020 | |
| 1021 | This function loads facts and useful object IDs related to the hash |
| 1022 | algorithm(s) in use from the files in t/oid-info. |
| 1023 | |
| 1024 | - test_oid_cache |
| 1025 | |
| 1026 | This function reads per-hash algorithm information from standard |
| 1027 | input (usually a heredoc) in the format described in |
| 1028 | t/oid-info/README. This is useful for test-specific values, such as |
| 1029 | object IDs, which must vary based on the hash algorithm. |
| 1030 | |
| 1031 | Certain fixed values, such as hash sizes and common placeholder |
| 1032 | object IDs, can be loaded with test_oid_init (described above). |
| 1033 | |
| 1034 | - test_oid <key> |
| 1035 | |
| 1036 | This function looks up a value for the hash algorithm in use, based |
| 1037 | on the key given. The value must have been loaded using |
| 1038 | test_oid_init or test_oid_cache. Providing an unknown key is an |
| 1039 | error. |
| 1040 | |
Junio C Hamano | 11f470a | 2019-02-09 10:25:26 -0800 | [diff] [blame] | 1041 | - yes [<string>] |
| 1042 | |
| 1043 | This is often seen in modern UNIX but some platforms lack it, so |
| 1044 | the test harness overrides the platform implementation with a |
| 1045 | more limited one. Use this only when feeding a handful lines of |
| 1046 | output to the downstream---unlike the real version, it generates |
| 1047 | only up to 99 lines. |
| 1048 | |
SZEDER Gábor | 43a2afe | 2019-11-22 14:14:36 +0100 | [diff] [blame] | 1049 | - test_bool_env <env-variable-name> <default-value> |
| 1050 | |
| 1051 | Given the name of an environment variable with a bool value, |
| 1052 | normalize its value to a 0 (true) or 1 (false or empty string) |
| 1053 | return code. Return with code corresponding to the given default |
| 1054 | value if the variable is unset. |
| 1055 | Abort the test script if either the value of the variable or the |
| 1056 | default are not valid bool values. |
| 1057 | |
Junio C Hamano | 11f470a | 2019-02-09 10:25:26 -0800 | [diff] [blame] | 1058 | |
Ævar Arnfjörð Bjarmason | be53dee | 2010-08-06 21:19:25 +0000 | [diff] [blame] | 1059 | Prerequisites |
| 1060 | ------------- |
| 1061 | |
| 1062 | These are the prerequisites that the test library predefines with |
| 1063 | test_have_prereq. |
| 1064 | |
| 1065 | See the prereq argument to the test_* functions in the "Test harness |
| 1066 | library" section above and the "test_have_prereq" function for how to |
| 1067 | use these, and "test_set_prereq" for how to define your own. |
| 1068 | |
Jonathan Nieder | f8fc0ee | 2013-10-28 12:22:16 -0700 | [diff] [blame] | 1069 | - PYTHON |
Ævar Arnfjörð Bjarmason | be53dee | 2010-08-06 21:19:25 +0000 | [diff] [blame] | 1070 | |
Jonathan Nieder | f8fc0ee | 2013-10-28 12:22:16 -0700 | [diff] [blame] | 1071 | Git wasn't compiled with NO_PYTHON=YesPlease. Wrap any tests that |
| 1072 | need Python with this. |
| 1073 | |
| 1074 | - PERL |
| 1075 | |
| 1076 | Git wasn't compiled with NO_PERL=YesPlease. |
| 1077 | |
| 1078 | Even without the PERL prerequisite, tests can assume there is a |
| 1079 | usable perl interpreter at $PERL_PATH, though it need not be |
| 1080 | particularly modern. |
Ævar Arnfjörð Bjarmason | be53dee | 2010-08-06 21:19:25 +0000 | [diff] [blame] | 1081 | |
| 1082 | - POSIXPERM |
| 1083 | |
| 1084 | The filesystem supports POSIX style permission bits. |
| 1085 | |
| 1086 | - BSLASHPSPEC |
| 1087 | |
| 1088 | Backslashes in pathspec are not directory separators. This is not |
| 1089 | set on Windows. See 6fd1106a for details. |
| 1090 | |
| 1091 | - EXECKEEPSPID |
| 1092 | |
| 1093 | The process retains the same pid across exec(2). See fb9a2bea for |
| 1094 | details. |
| 1095 | |
Adam Spiers | 2007327 | 2013-04-11 03:07:04 +0100 | [diff] [blame] | 1096 | - PIPE |
| 1097 | |
| 1098 | The filesystem we're on supports creation of FIFOs (named pipes) |
| 1099 | via mkfifo(1). |
| 1100 | |
Ævar Arnfjörð Bjarmason | be53dee | 2010-08-06 21:19:25 +0000 | [diff] [blame] | 1101 | - SYMLINKS |
| 1102 | |
| 1103 | The filesystem we're on supports symbolic links. E.g. a FAT |
| 1104 | filesystem doesn't support these. See 704a3143 for details. |
Ævar Arnfjörð Bjarmason | 2fac6a4 | 2010-07-02 14:59:46 +0000 | [diff] [blame] | 1105 | |
Ævar Arnfjörð Bjarmason | c91cfd1 | 2010-08-06 22:09:09 +0000 | [diff] [blame] | 1106 | - SANITY |
| 1107 | |
| 1108 | Test is not run by root user, and an attempt to write to an |
| 1109 | unwritable file is expected to fail correctly. |
Junio C Hamano | 986aa7f | 2005-05-14 00:25:06 -0700 | [diff] [blame] | 1110 | |
Ævar Arnfjörð Bjarmason | 3eb585c | 2017-05-20 21:42:06 +0000 | [diff] [blame] | 1111 | - PCRE |
Michał Kiedrowicz | 8f852ce | 2011-05-09 23:52:07 +0200 | [diff] [blame] | 1112 | |
Ævar Arnfjörð Bjarmason | 3eb585c | 2017-05-20 21:42:06 +0000 | [diff] [blame] | 1113 | Git was compiled with support for PCRE. Wrap any tests |
Michał Kiedrowicz | 8f852ce | 2011-05-09 23:52:07 +0200 | [diff] [blame] | 1114 | that use git-grep --perl-regexp or git-grep -P in these. |
| 1115 | |
Michael J Gruber | ac39aa6 | 2012-07-26 15:39:53 +0200 | [diff] [blame] | 1116 | - CASE_INSENSITIVE_FS |
| 1117 | |
| 1118 | Test is run on a case insensitive file system. |
| 1119 | |
Michael J Gruber | 5b0b5dd | 2012-07-26 15:39:56 +0200 | [diff] [blame] | 1120 | - UTF8_NFD_TO_NFC |
| 1121 | |
| 1122 | Test is run on a filesystem which converts decomposed utf-8 (nfd) |
| 1123 | to precomposed utf-8 (nfc). |
| 1124 | |
Ævar Arnfjörð Bjarmason | 68c7d27 | 2017-05-25 19:45:31 +0000 | [diff] [blame] | 1125 | - PTHREADS |
| 1126 | |
| 1127 | Git wasn't compiled with NO_PTHREADS=YesPlease. |
| 1128 | |
Junio C Hamano | 986aa7f | 2005-05-14 00:25:06 -0700 | [diff] [blame] | 1129 | Tips for Writing Tests |
| 1130 | ---------------------- |
| 1131 | |
| 1132 | As with any programming projects, existing programs are the best |
| 1133 | source of the information. However, do _not_ emulate |
| 1134 | t0000-basic.sh when writing your tests. The test is special in |
Denton Liu | 788db14 | 2020-06-07 05:48:26 -0400 | [diff] [blame] | 1135 | that it tries to validate the very core of Git. For example, it |
Junio C Hamano | 986aa7f | 2005-05-14 00:25:06 -0700 | [diff] [blame] | 1136 | knows that there will be 256 subdirectories under .git/objects/, |
| 1137 | and it knows that the object ID of an empty tree is a certain |
| 1138 | 40-byte string. This is deliberately done so in t0000-basic.sh |
| 1139 | because the things the very basic core test tries to achieve is |
Denton Liu | 788db14 | 2020-06-07 05:48:26 -0400 | [diff] [blame] | 1140 | to serve as a basis for people who are changing the Git internals |
Junio C Hamano | 986aa7f | 2005-05-14 00:25:06 -0700 | [diff] [blame] | 1141 | drastically. For these people, after making certain changes, |
| 1142 | not seeing failures from the basic test _is_ a failure. And |
Denton Liu | 788db14 | 2020-06-07 05:48:26 -0400 | [diff] [blame] | 1143 | such drastic changes to the core Git that even changes these |
Junio C Hamano | 986aa7f | 2005-05-14 00:25:06 -0700 | [diff] [blame] | 1144 | otherwise supposedly stable object IDs should be accompanied by |
| 1145 | an update to t0000-basic.sh. |
| 1146 | |
| 1147 | However, other tests that simply rely on basic parts of the core |
Denton Liu | 788db14 | 2020-06-07 05:48:26 -0400 | [diff] [blame] | 1148 | Git working properly should not have that level of intimate |
| 1149 | knowledge of the core Git internals. If all the test scripts |
Junio C Hamano | 986aa7f | 2005-05-14 00:25:06 -0700 | [diff] [blame] | 1150 | hardcoded the object IDs like t0000-basic.sh does, that defeats |
| 1151 | the purpose of t0000-basic.sh, which is to isolate that level of |
| 1152 | validation in one place. Your test also ends up needing |
| 1153 | updating when such a change to the internal happens, so do _not_ |
| 1154 | do it and leave the low level of validation to t0000-basic.sh. |
Ævar Arnfjörð Bjarmason | d15e9eb | 2010-08-08 14:49:25 +0000 | [diff] [blame] | 1155 | |
Ævar Arnfjörð Bjarmason | 0c35754 | 2010-07-25 19:52:44 +0000 | [diff] [blame] | 1156 | Test coverage |
| 1157 | ------------- |
| 1158 | |
| 1159 | You can use the coverage tests to find code paths that are not being |
| 1160 | used or properly exercised yet. |
| 1161 | |
| 1162 | To do that, run the coverage target at the top-level (not in the t/ |
| 1163 | directory): |
| 1164 | |
| 1165 | make coverage |
| 1166 | |
| 1167 | That'll compile Git with GCC's coverage arguments, and generate a test |
| 1168 | report with gcov after the tests finish. Running the coverage tests |
| 1169 | can take a while, since running the tests in parallel is incompatible |
| 1170 | with GCC's coverage mode. |
| 1171 | |
| 1172 | After the tests have run you can generate a list of untested |
| 1173 | functions: |
| 1174 | |
| 1175 | make coverage-untested-functions |
| 1176 | |
| 1177 | You can also generate a detailed per-file HTML report using the |
| 1178 | Devel::Cover module. To install it do: |
| 1179 | |
| 1180 | # On Debian or Ubuntu: |
| 1181 | sudo aptitude install libdevel-cover-perl |
| 1182 | |
| 1183 | # From the CPAN with cpanminus |
| 1184 | curl -L http://cpanmin.us | perl - --sudo --self-upgrade |
| 1185 | cpanm --sudo Devel::Cover |
| 1186 | |
| 1187 | Then, at the top-level: |
| 1188 | |
| 1189 | make cover_db_html |
| 1190 | |
| 1191 | That'll generate a detailed cover report in the "cover_db_html" |
| 1192 | directory, which you can then copy to a webserver, or inspect locally |
| 1193 | in a browser. |