]>
Commit | Line | Data |
---|---|---|
788db145 | 1 | Core Git Tests |
986aa7f1 JH |
2 | ============== |
3 | ||
788db145 | 4 | This directory holds many test scripts for core Git tools. The |
986aa7f1 JH |
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 *** | |
5099b99d ÆAB |
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 | |
986aa7f1 | 24 | ... |
5099b99d ÆAB |
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 | |
34 | ||
8d383806 PB |
35 | t/Makefile defines a target for each test file, such that you can also use |
36 | shell pattern matching to run a subset of the tests: | |
37 | ||
38 | make *checkout* | |
39 | ||
40 | will run all tests with 'checkout' in their filename. | |
41 | ||
d05b08cd | 42 | Since the tests all output TAP (see https://testanything.org) they can |
85b0b34e | 43 | be run with any TAP harness. Here's an example of parallel testing |
5099b99d ÆAB |
44 | powered by a recent version of prove(1): |
45 | ||
46 | $ prove --timer --jobs 15 ./t[0-9]*.sh | |
47 | [19:17:33] ./t0005-signals.sh ................................... ok 36 ms | |
48 | [19:17:33] ./t0022-crlf-rename.sh ............................... ok 69 ms | |
49 | [19:17:33] ./t0024-crlf-archive.sh .............................. ok 154 ms | |
50 | [19:17:33] ./t0004-unwritable.sh ................................ ok 289 ms | |
51 | [19:17:33] ./t0002-gitfile.sh ................................... ok 480 ms | |
52 | ===( 102;0 25/? 6/? 5/? 16/? 1/? 4/? 2/? 1/? 3/? 1... )=== | |
53 | ||
54 | prove and other harnesses come with a lot of useful options. The | |
55 | --state option in particular is very useful: | |
56 | ||
57 | # Repeat until no more failures | |
58 | $ prove -j 15 --state=failed,save ./t[0-9]*.sh | |
986aa7f1 | 59 | |
28d836c8 MG |
60 | You can give DEFAULT_TEST_TARGET=prove on the make command (or define it |
61 | in config.mak) to cause "make test" to run tests under prove. | |
62 | GIT_PROVE_OPTS can be used to pass additional options, e.g. | |
63 | ||
64 | $ make DEFAULT_TEST_TARGET=prove GIT_PROVE_OPTS='--timer --jobs 16' test | |
65 | ||
5099b99d | 66 | You can also run each test individually from command line, like this: |
986aa7f1 | 67 | |
5099b99d ÆAB |
68 | $ sh ./t3010-ls-files-killed-modified.sh |
69 | ok 1 - git update-index --add to add various paths. | |
70 | ok 2 - git ls-files -k to show killed files. | |
71 | ok 3 - validate git ls-files -k output. | |
72 | ok 4 - git ls-files -m to show modified files. | |
73 | ok 5 - validate git ls-files -m output. | |
74 | # passed all 5 test(s) | |
75 | 1..5 | |
986aa7f1 JH |
76 | |
77 | You can pass --verbose (or -v), --debug (or -d), and --immediate | |
4e1be63c | 78 | (or -i) command line argument to the test, or by setting GIT_TEST_OPTS |
78dc0887 MT |
79 | appropriately before running "make". Short options can be bundled, i.e. |
80 | '-d -v' is the same as '-dv'. | |
986aa7f1 | 81 | |
5e3b4fce | 82 | -v:: |
986aa7f1 JH |
83 | --verbose:: |
84 | This makes the test more verbose. Specifically, the | |
85 | command being run and their output if any are also | |
86 | output. | |
87 | ||
ff09af3f TR |
88 | --verbose-only=<pattern>:: |
89 | Like --verbose, but the effect is limited to tests with | |
90 | numbers matching <pattern>. The number matched against is | |
91 | simply the running count of the test within the file. | |
92 | ||
a136f6d8 JK |
93 | -x:: |
94 | Turn on shell tracing (i.e., `set -x`) during the tests | |
94201a2b | 95 | themselves. Implies `--verbose`. |
5fc98e79 SG |
96 | Ignored in test scripts that set the variable 'test_untraceable' |
97 | to a non-empty value, unless it's run with a Bash version | |
98 | supporting BASH_XTRACEFD, i.e. v4.1 or later. | |
a136f6d8 | 99 | |
5e3b4fce | 100 | -d:: |
986aa7f1 JH |
101 | --debug:: |
102 | This may help the person who is developing a new test. | |
103 | It causes the command defined with test_debug to run. | |
0986de94 PK |
104 | The "trash" directory (used to store all temporary data |
105 | during testing) is not deleted even if there are no | |
106 | failed tests so that you can inspect its contents after | |
107 | the test finished. | |
986aa7f1 | 108 | |
5e3b4fce | 109 | -i:: |
986aa7f1 JH |
110 | --immediate:: |
111 | This causes the test to immediately exit upon the first | |
13cb3bb7 SR |
112 | failed test. Cleanup commands requested with |
113 | test_when_finished are not executed if the test failed, | |
114 | in order to keep the state for inspection by the tester | |
115 | to diagnose the bug. | |
986aa7f1 | 116 | |
5e3b4fce | 117 | -l:: |
5e2c08c6 LW |
118 | --long-tests:: |
119 | This causes additional long-running tests to be run (where | |
120 | available), for more exhaustive testing. | |
121 | ||
0445e6f0 IB |
122 | -r:: |
123 | --run=<test-selector>:: | |
124 | Run only the subset of tests indicated by | |
125 | <test-selector>. See section "Skipping Tests" below for | |
126 | <test-selector> syntax. | |
127 | ||
952af351 TR |
128 | --valgrind=<tool>:: |
129 | Execute all Git binaries under valgrind tool <tool> and exit | |
130 | with status 126 on errors (just like regular tests, this will | |
131 | only stop the test script when running under -i). | |
986aa7f1 | 132 | |
3da93652 JS |
133 | Since it makes no sense to run the tests with --valgrind and |
134 | not see any output, this option implies --verbose. For | |
135 | convenience, it also implies --tee. | |
136 | ||
952af351 TR |
137 | <tool> defaults to 'memcheck', just like valgrind itself. |
138 | Other particularly useful choices include 'helgrind' and | |
139 | 'drd', but you may use any tool recognized by your valgrind | |
140 | installation. | |
141 | ||
95d9d5ec TR |
142 | As a special case, <tool> can be 'memcheck-fast', which uses |
143 | memcheck but disables --track-origins. Use this if you are | |
144 | running tests in bulk, to see if there are _any_ memory | |
145 | issues. | |
146 | ||
952af351 | 147 | Note that memcheck is run with the option --leak-check=no, |
9aec68d3 CMN |
148 | as the git process is short-lived and some errors are not |
149 | interesting. In order to run a single command under the same | |
150 | conditions manually, you should set GIT_VALGRIND to point to | |
151 | the 't/valgrind/' directory and use the commands under | |
152 | 't/valgrind/bin/'. | |
153 | ||
5dfc368f TR |
154 | --valgrind-only=<pattern>:: |
155 | Like --valgrind, but the effect is limited to tests with | |
156 | numbers matching <pattern>. The number matched against is | |
157 | simply the running count of the test within the file. | |
158 | ||
44138559 JS |
159 | --tee:: |
160 | In addition to printing the test output to the terminal, | |
161 | write it to files named 't/test-results/$TEST_NAME.out'. | |
162 | As the names depend on the tests' file names, it is safe to | |
163 | run the tests with this option in parallel. | |
164 | ||
a5f52c6d | 165 | -V:: |
452320f1 JK |
166 | --verbose-log:: |
167 | Write verbose output to the same logfile as `--tee`, but do | |
168 | _not_ write it to stdout. Unlike `--tee --verbose`, this option | |
169 | is safe to use when stdout is being consumed by a TAP parser | |
170 | like `prove`. Implies `--tee` and `--verbose`. | |
171 | ||
e4597aae MO |
172 | --with-dashes:: |
173 | By default tests are run without dashed forms of | |
174 | commands (like git-commit) in the PATH (it only uses | |
175 | wrappers from ../bin-wrappers). Use this option to include | |
176 | the build directory (..) in the PATH, which contains all | |
177 | the dashed forms of commands. This option is currently | |
178 | implied by other options like --valgrind and | |
179 | GIT_TEST_INSTALLED. | |
180 | ||
dd167a30 JS |
181 | --no-bin-wrappers:: |
182 | By default, the test suite uses the wrappers in | |
183 | `../bin-wrappers/` to execute `git` and friends. With this option, | |
184 | `../git` and friends are run directly. This is not recommended | |
185 | in general, as the wrappers contain safeguards to ensure that no | |
186 | files from an installed Git are used, but can speed up test runs | |
187 | especially on platforms where running shell scripts is expensive | |
188 | (most notably, Windows). | |
189 | ||
0d4dbcd3 TR |
190 | --root=<directory>:: |
191 | Create "trash" directories used to store all temporary data during | |
192 | testing under <directory>, instead of the t/ directory. | |
193 | Using this option with a RAM-based filesystem (such as tmpfs) | |
194 | can massively speed up the test suite. | |
195 | ||
bb79af9d JK |
196 | --chain-lint:: |
197 | --no-chain-lint:: | |
198 | If --chain-lint is enabled, the test harness will check each | |
199 | test to make sure that it properly "&&-chains" all commands (so | |
200 | that a failure in the middle does not go unnoticed by the final | |
201 | exit code of the test). This check is performed in addition to | |
202 | running the tests themselves. You may also enable or disable | |
203 | this feature by setting the GIT_TEST_CHAIN_LINT environment | |
204 | variable to "1" or "0", respectively. | |
205 | ||
fb7d1e3a | 206 | --stress:: |
fb7d1e3a SG |
207 | Run the test script repeatedly in multiple parallel jobs until |
208 | one of them fails. Useful for reproducing rare failures in | |
209 | flaky tests. The number of parallel jobs is, in order of | |
f5457371 | 210 | precedence: the value of the GIT_TEST_STRESS_LOAD |
fb7d1e3a SG |
211 | environment variable, or twice the number of available |
212 | processors (as shown by the 'getconf' utility), or 8. | |
213 | Implies `--verbose -x --immediate` to get the most information | |
214 | about the failure. Note that the verbose output of each test | |
215 | job is saved to 't/test-results/$TEST_NAME.stress-<nr>.out', | |
216 | and only the output of the failed test job is shown on the | |
217 | terminal. The names of the trash directories get a | |
218 | '.stress-<nr>' suffix, and the trash directory of the failed | |
219 | test job is renamed to end with a '.stress-failed' suffix. | |
220 | ||
f5457371 JS |
221 | --stress-jobs=<N>:: |
222 | Override the number of parallel jobs. Implies `--stress`. | |
223 | ||
76e27fbf SG |
224 | --stress-limit=<N>:: |
225 | When combined with --stress run the test script repeatedly | |
226 | this many times in each of the parallel jobs or until one of | |
de69e6f6 | 227 | them fails, whichever comes first. Implies `--stress`. |
76e27fbf | 228 | |
e160da7f MO |
229 | You can also set the GIT_TEST_INSTALLED environment variable to |
230 | the bindir of an existing git installation to test that installation. | |
231 | You still need to have built this git sandbox, from which various | |
232 | test-* support programs, templates, and perl libraries are used. | |
233 | If your installed git is incomplete, it will silently test parts of | |
234 | your built version instead. | |
235 | ||
236 | When using GIT_TEST_INSTALLED, you can also set GIT_TEST_EXEC_PATH to | |
237 | override the location of the dashed-form subcommands (what | |
238 | GIT_EXEC_PATH would be used for during normal operation). | |
239 | GIT_TEST_EXEC_PATH defaults to `$GIT_TEST_INSTALLED/git --exec-path`. | |
240 | ||
241 | ||
fbd458a3 JN |
242 | Skipping Tests |
243 | -------------- | |
244 | ||
245 | In some environments, certain tests have no way of succeeding | |
246 | due to platform limitation, such as lack of 'unzip' program, or | |
247 | filesystem that do not allow arbitrary sequence of non-NUL bytes | |
248 | as pathnames. | |
249 | ||
250 | You should be able to say something like | |
251 | ||
252 | $ GIT_SKIP_TESTS=t9200.8 sh ./t9200-git-cvsexport-commit.sh | |
253 | ||
254 | and even: | |
255 | ||
256 | $ GIT_SKIP_TESTS='t[0-4]??? t91?? t9200.8' make | |
257 | ||
258 | to omit such tests. The value of the environment variable is a | |
259 | SP separated list of patterns that tells which tests to skip, | |
260 | and either can match the "t[0-9]{4}" part to skip the whole | |
261 | test, or t[0-9]{4} followed by ".$number" to say which | |
262 | particular test to skip. | |
263 | ||
0445e6f0 IB |
264 | For an individual test suite --run could be used to specify that |
265 | only some tests should be run or that some tests should be | |
266 | excluded from a run. | |
267 | ||
f21ac368 EN |
268 | The argument for --run, <test-selector>, is a list of description |
269 | substrings or globs or individual test numbers or ranges with an | |
270 | optional negation prefix (of '!') that define what tests in a test | |
271 | suite to include (or exclude, if negated) in the run. A range is two | |
97509a34 ŠN |
272 | numbers separated with a dash and specifies an inclusive range of tests |
273 | to run. You may omit the first or the second number to | |
f21ac368 EN |
274 | mean "from the first test" or "up to the very last test" respectively. |
275 | ||
276 | The argument to --run is split on commas into separate strings, | |
277 | numbers, and ranges, and picks all tests that match any of the | |
278 | individual selection criteria. If the substring of the description | |
279 | text that you want to match includes a comma, use the glob character | |
280 | '?' instead. For example --run='rebase,merge?cherry-pick' would match | |
281 | on all tests that match either the glob *rebase* or the glob | |
282 | *merge?cherry-pick*. | |
0445e6f0 | 283 | |
97509a34 ŠN |
284 | If --run starts with an unprefixed number or range, the initial |
285 | set of tests to run is empty. If the first item starts with '!', | |
0445e6f0 | 286 | all the tests are added to the initial set. After initial set is |
97509a34 | 287 | determined, every test number or range is added or excluded from |
0445e6f0 IB |
288 | the set one by one, from left to right. |
289 | ||
0445e6f0 IB |
290 | For example, to run only tests up to a specific test (21), one |
291 | could do this: | |
292 | ||
293 | $ sh ./t9200-git-cvsexport-commit.sh --run='1-21' | |
294 | ||
295 | or this: | |
296 | ||
297 | $ sh ./t9200-git-cvsexport-commit.sh --run='-21' | |
298 | ||
299 | Common case is to run several setup tests (1, 2, 3) and then a | |
300 | specific test (21) that relies on that setup: | |
301 | ||
f21ac368 | 302 | $ sh ./t9200-git-cvsexport-commit.sh --run='1,2,3,21' |
0445e6f0 IB |
303 | |
304 | or: | |
305 | ||
306 | $ sh ./t9200-git-cvsexport-commit.sh --run=1,2,3,21 | |
307 | ||
308 | or: | |
309 | ||
f21ac368 | 310 | $ sh ./t9200-git-cvsexport-commit.sh --run='-3,21' |
0445e6f0 | 311 | |
01e4be6c KS |
312 | As noted above, the test set is built by going through the items |
313 | from left to right, so this: | |
0445e6f0 | 314 | |
f21ac368 | 315 | $ sh ./t9200-git-cvsexport-commit.sh --run='1-4,!3' |
0445e6f0 | 316 | |
01e4be6c | 317 | will run tests 1, 2, and 4. Items that come later have higher |
2e3a16b2 | 318 | precedence. It means that this: |
0445e6f0 | 319 | |
f21ac368 | 320 | $ sh ./t9200-git-cvsexport-commit.sh --run='!3,1-4' |
0445e6f0 IB |
321 | |
322 | would just run tests from 1 to 4, including 3. | |
323 | ||
324 | You may use negation with ranges. The following will run all | |
325 | test in the test suite except from 7 up to 11: | |
326 | ||
327 | $ sh ./t9200-git-cvsexport-commit.sh --run='!7-11' | |
328 | ||
f21ac368 EN |
329 | Sometimes there may be multiple tests with e.g. "setup" in their name |
330 | that are needed and rather than figuring out the number for all of them | |
331 | we can just use "setup" as a substring/glob to match against the test | |
332 | description: | |
333 | ||
334 | $ sh ./t0050-filesystem.sh --run=setup,9-11 | |
335 | ||
336 | or one could select both the setup tests and the rename ones (assuming all | |
337 | relevant tests had those words in their descriptions): | |
338 | ||
339 | $ sh ./t0050-filesystem.sh --run=setup,rename | |
340 | ||
0445e6f0 IB |
341 | Some tests in a test suite rely on the previous tests performing |
342 | certain actions, specifically some tests are designated as | |
343 | "setup" test, so you cannot _arbitrarily_ disable one test and | |
344 | expect the rest to function correctly. | |
345 | ||
346 | --run is mostly useful when you want to focus on a specific test | |
347 | and know what setup is needed for it. Or when you want to run | |
348 | everything up to a certain test. | |
fbd458a3 JN |
349 | |
350 | ||
4c2db938 NTND |
351 | Running tests with special setups |
352 | --------------------------------- | |
353 | ||
354 | The whole test suite could be run to test some special features | |
355 | that cannot be easily covered by a few specific test cases. These | |
356 | could be enabled by running the test suite with correct GIT_TEST_ | |
357 | environment set. | |
358 | ||
c7400399 | 359 | GIT_TEST_FAIL_PREREQS=<boolean> fails all prerequisites. This is |
dfe1a17d ÆAB |
360 | useful for discovering issues with the tests where say a later test |
361 | implicitly depends on an optional earlier test. | |
362 | ||
363 | There's a "FAIL_PREREQS" prerequisite that can be used to test for | |
364 | whether this mode is active, and e.g. skip some tests that are hard to | |
365 | refactor to deal with it. The "SYMLINKS" prerequisite is currently | |
366 | excluded as so much relies on it, but this might change in the future. | |
367 | ||
4c2db938 NTND |
368 | GIT_TEST_SPLIT_INDEX=<boolean> forces split-index mode on the whole |
369 | test suite. Accept any boolean values that are accepted by git-config. | |
370 | ||
ac8e3e94 ÆAB |
371 | GIT_TEST_PASSING_SANITIZE_LEAK=true skips those tests that haven't |
372 | declared themselves as leak-free by setting | |
373 | "TEST_PASSES_SANITIZE_LEAK=true" before sourcing "test-lib.sh". This | |
374 | test mode is used by the "linux-leaks" CI target. | |
956d2e46 | 375 | |
e92684e1 ÆAB |
376 | GIT_TEST_PASSING_SANITIZE_LEAK=check checks that our |
377 | "TEST_PASSES_SANITIZE_LEAK=true" markings are current. Rather than | |
378 | skipping those tests that haven't set "TEST_PASSES_SANITIZE_LEAK=true" | |
379 | before sourcing "test-lib.sh" this mode runs them with | |
380 | "--invert-exit-code". This is used to check that there's a one-to-one | |
381 | mapping between "TEST_PASSES_SANITIZE_LEAK=true" and those tests that | |
382 | pass under "SANITIZE=leak". This is especially useful when testing a | |
383 | series that fixes various memory leaks with "git rebase -x". | |
384 | ||
366bd129 ÆAB |
385 | GIT_TEST_SANITIZE_LEAK_LOG=true will log memory leaks to |
386 | "test-results/$TEST_NAME.leak/trace.*" files. The logs include a | |
387 | "dedup_token" (see +"ASAN_OPTIONS=help=1 ./git") and other options to | |
388 | make logs +machine-readable. | |
389 | ||
faececa5 ÆAB |
390 | With GIT_TEST_SANITIZE_LEAK_LOG=true we'll look at the leak logs |
391 | before exiting and exit on failure if the logs showed that we had a | |
392 | memory leak, even if the test itself would have otherwise passed. This | |
393 | allows us to catch e.g. missing &&-chaining. This is especially useful | |
394 | when combined with "GIT_TEST_PASSING_SANITIZE_LEAK", see below. | |
395 | ||
e92684e1 ÆAB |
396 | GIT_TEST_PASSING_SANITIZE_LEAK=check when combined with "--immediate" |
397 | will run to completion faster, and result in the same failing | |
398 | tests. The only practical reason to run | |
399 | GIT_TEST_PASSING_SANITIZE_LEAK=check without "--immediate" is to | |
400 | combine it with "GIT_TEST_SANITIZE_LEAK_LOG=true". If we stop at the | |
401 | first failing test case our leak logs won't show subsequent leaks we | |
402 | might have run into. | |
403 | ||
faececa5 ÆAB |
404 | GIT_TEST_PASSING_SANITIZE_LEAK=(true|check) will not catch all memory |
405 | leaks unless combined with GIT_TEST_SANITIZE_LEAK_LOG=true. Some tests | |
406 | run "git" (or "test-tool" etc.) without properly checking the exit | |
407 | code, or git will invoke itself and fail to ferry the abort() exit | |
408 | code to the original caller. When the two modes are combined we'll | |
409 | look at the "test-results/$TEST_NAME.leak/trace.*" files at the end of | |
410 | the test run to see if had memory leaks which the test itself didn't | |
411 | catch. | |
412 | ||
33166f3a JN |
413 | GIT_TEST_PROTOCOL_VERSION=<n>, when set, makes 'protocol.version' |
414 | default to n. | |
8cbeba06 | 415 | |
43fa44fa NTND |
416 | GIT_TEST_FULL_IN_PACK_ARRAY=<boolean> exercises the uncommon |
417 | pack-objects code path where there are more than 1024 packs even if | |
418 | the actual number of packs in repository is below this limit. Accept | |
419 | any boolean values that are accepted by git-config. | |
420 | ||
ac77d0c3 NTND |
421 | GIT_TEST_OE_SIZE=<n> exercises the uncommon pack-objects code path |
422 | where we do not cache object size in memory and read it from existing | |
423 | packs on demand. This normally only happens when the object size is | |
424 | over 2GB. This variable forces the code path on any object larger than | |
425 | <n> bytes. | |
426 | ||
ac6e12f9 | 427 | GIT_TEST_OE_DELTA_SIZE=<n> exercises the uncommon pack-objects code |
9ac3f0e5 NTND |
428 | path where deltas larger than this limit require extra memory |
429 | allocation for bookkeeping. | |
430 | ||
5f4436a7 NTND |
431 | GIT_TEST_VALIDATE_INDEX_CACHE_ENTRIES=<boolean> checks that cache-tree |
432 | records are valid when the index is written out or after a merge. This | |
433 | is mostly to catch missing invalidation. Default is true. | |
434 | ||
859fdc0c DS |
435 | GIT_TEST_COMMIT_GRAPH=<boolean>, when true, forces the commit-graph to |
436 | be written after every 'git commit' command, and overrides the | |
437 | 'core.commitGraph' setting to true. | |
438 | ||
d5b873c8 GS |
439 | GIT_TEST_COMMIT_GRAPH_CHANGED_PATHS=<boolean>, when true, forces |
440 | commit-graph write to compute and write changed path Bloom filters for | |
441 | every 'git commit-graph write', as if the `--changed-paths` option was | |
442 | passed in. | |
443 | ||
4cb54d0a | 444 | GIT_TEST_FSMONITOR=$PWD/t7519/fsmonitor-all exercises the fsmonitor |
1e0ea5c4 JH |
445 | code paths for utilizing a (hook based) file system monitor to speed up |
446 | detecting new or changed files. | |
4cb54d0a | 447 | |
1f357b04 BP |
448 | GIT_TEST_INDEX_VERSION=<n> exercises the index read/write code path |
449 | for the index version specified. Can be set to any valid version | |
450 | (currently 2, 3, or 4). | |
451 | ||
b0afdce5 TB |
452 | GIT_TEST_PACK_USE_BITMAP_BOUNDARY_TRAVERSAL=<boolean> if enabled will |
453 | use the boundary-based bitmap traversal algorithm. See the documentation | |
454 | of `pack.useBitmapBoundaryTraversal` for more details. | |
455 | ||
2d657ab9 DS |
456 | GIT_TEST_PACK_SPARSE=<boolean> if disabled will default the pack-objects |
457 | builtin to use the non-sparse object walk. This can still be overridden by | |
458 | the --sparse command-line argument. | |
99dbbfa8 | 459 | |
5765d97b BP |
460 | GIT_TEST_PRELOAD_INDEX=<boolean> exercises the preload-index code path |
461 | by overriding the minimum number of cache entries required per thread. | |
462 | ||
c780b9cf BP |
463 | GIT_TEST_INDEX_THREADS=<n> enables exercising the multi-threaded loading |
464 | of the index for the whole test suite by bypassing the default number of | |
465 | cache entries and thread minimums. Setting this to 1 will make the | |
466 | index loading single threaded. | |
467 | ||
0465a505 DS |
468 | GIT_TEST_MULTI_PACK_INDEX=<boolean>, when true, forces the multi-pack- |
469 | index to be written after every 'git repack' command, and overrides the | |
470 | 'core.multiPackIndex' setting to true. | |
471 | ||
ff1e653c TB |
472 | GIT_TEST_MULTI_PACK_INDEX_WRITE_BITMAP=<boolean>, when true, sets the |
473 | '--bitmap' option on all invocations of 'git multi-pack-index write', | |
474 | and ignores pack-objects' '--write-bitmap-index'. | |
475 | ||
07c3c2aa JT |
476 | GIT_TEST_SIDEBAND_ALL=<boolean>, when true, overrides the |
477 | 'uploadpack.allowSidebandAll' setting to true, and when false, forces | |
478 | fetch-pack to not request sideband-all (even if the server advertises | |
479 | sideband-all). | |
480 | ||
b02e7d5d JS |
481 | GIT_TEST_DISALLOW_ABBREVIATED_OPTIONS=<boolean>, when true (which is |
482 | the default when running tests), errors out when an abbreviated option | |
483 | is used. | |
484 | ||
f3d66ec8 DS |
485 | GIT_TEST_DEFAULT_HASH=<hash-algo> specifies which hash algorithm to |
486 | use in the test scripts. Recognized values for <hash-algo> are "sha1" | |
487 | and "sha256". | |
488 | ||
58aaf591 PS |
489 | GIT_TEST_DEFAULT_REF_FORMAT=<format> specifies which ref storage format |
490 | to use in the test scripts. Recognized values for <format> are "files". | |
491 | ||
9f7f10a2 | 492 | GIT_TEST_NO_WRITE_REV_INDEX=<boolean>, when true disables the |
e8c58f89 TB |
493 | 'pack.writeReverseIndex' setting. |
494 | ||
ecfc47c0 DS |
495 | GIT_TEST_SPARSE_INDEX=<boolean>, when true enables index writes to use the |
496 | sparse-index format by default. | |
497 | ||
87094fc2 MT |
498 | GIT_TEST_CHECKOUT_WORKERS=<n> overrides the 'checkout.workers' setting |
499 | to <n> and 'checkout.thresholdForParallelism' to 0, forcing the | |
500 | execution of the parallel-checkout code. | |
501 | ||
a35e03de JT |
502 | GIT_TEST_FATAL_REGISTER_SUBMODULE_ODB=<boolean>, when true, makes |
503 | registering submodule ODBs as alternates a fatal action. Support for | |
504 | this environment variable can be removed once the migration to | |
505 | explicitly providing repositories when accessing submodule objects is | |
71ef66d7 JT |
506 | complete or needs to be abandoned for whatever reason (in which case the |
507 | migrated codepaths still retain their performance benefits). | |
a35e03de | 508 | |
8205b2ff | 509 | GIT_TEST_REQUIRE_PREREQ=<list> allows specifying a space separated list of |
5024ade1 FS |
510 | prereqs that are required to succeed. If a prereq in this list is triggered by |
511 | a test and then fails then the whole test run will abort. This can help to make | |
512 | sure the expected tests are executed and not silently skipped when their | |
513 | dependency breaks or is simply not present in a new environment. | |
514 | ||
f50c9f76 PB |
515 | Naming Tests |
516 | ------------ | |
517 | ||
518 | The test files are named as: | |
519 | ||
520 | tNNNN-commandname-details.sh | |
521 | ||
522 | where N is a decimal digit. | |
523 | ||
524 | First digit tells the family: | |
525 | ||
526 | 0 - the absolute basics and global stuff | |
527 | 1 - the basic commands concerning database | |
528 | 2 - the basic commands concerning the working tree | |
529 | 3 - the other basic commands (e.g. ls-files) | |
530 | 4 - the diff commands | |
531 | 5 - the pull and exporting commands | |
532 | 6 - the revision tree commands (even e.g. merge-base) | |
8f4a9b62 | 533 | 7 - the porcelainish commands concerning the working tree |
8757749e JN |
534 | 8 - the porcelainish commands concerning forensics |
535 | 9 - the git tools | |
f50c9f76 PB |
536 | |
537 | Second digit tells the particular command we are testing. | |
538 | ||
539 | Third digit (optionally) tells the particular switch or group of switches | |
540 | we are testing. | |
541 | ||
77656600 JH |
542 | If you create files under t/ directory (i.e. here) that is not |
543 | the top-level test script, never name the file to match the above | |
544 | pattern. The Makefile here considers all such files as the | |
63d32945 | 545 | top-level test script and tries to run all of them. Care is |
77656600 JH |
546 | especially needed if you are creating a common test library |
547 | file, similar to test-lib.sh, because such a library file may | |
548 | not be suitable for standalone execution. | |
549 | ||
f50c9f76 | 550 | |
986aa7f1 JH |
551 | Writing Tests |
552 | ------------- | |
553 | ||
554 | The test script is written as a shell script. It should start | |
51b7a525 | 555 | with the standard "#!/bin/sh", and an |
986aa7f1 JH |
556 | assignment to variable 'test_description', like this: |
557 | ||
558 | #!/bin/sh | |
986aa7f1 | 559 | |
14cd1ff3 | 560 | test_description='xxx test (option --frotz) |
986aa7f1 JH |
561 | |
562 | This test registers the following structure in the cache | |
563 | and tries to run git-ls-files with option --frotz.' | |
564 | ||
f50c9f76 | 565 | |
986aa7f1 JH |
566 | Source 'test-lib.sh' |
567 | -------------------- | |
568 | ||
569 | After assigning test_description, the test script should source | |
570 | test-lib.sh like this: | |
571 | ||
572 | . ./test-lib.sh | |
573 | ||
574 | This test harness library does the following things: | |
575 | ||
576 | - If the script is invoked with command line argument --help | |
577 | (or -h), it shows the test_description and exits. | |
578 | ||
e1ca1c9d ÆAB |
579 | - Creates an empty test directory with an empty .git/objects database |
580 | and chdir(2) into it. This directory is 't/trash | |
581 | directory.$test_name_without_dotsh', with t/ subject to change by | |
fb7d1e3a SG |
582 | the --root option documented above, and a '.stress-<N>' suffix |
583 | appended by the --stress option. | |
986aa7f1 JH |
584 | |
585 | - Defines standard test helper functions for your scripts to | |
586 | use. These functions are designed to make all scripts behave | |
587 | consistently when command line arguments --verbose (or -v), | |
588 | --debug (or -d), and --immediate (or -i) is given. | |
589 | ||
18337d40 LL |
590 | Recommended style |
591 | ----------------- | |
18337d40 | 592 | |
97509a34 ŠN |
593 | - Keep the test_expect_* function call and test title on |
594 | the same line. | |
18337d40 | 595 | |
97509a34 | 596 | For example, with test_expect_success, write it like: |
18337d40 LL |
597 | |
598 | test_expect_success 'test title' ' | |
599 | ... test body ... | |
600 | ' | |
601 | ||
602 | Instead of: | |
603 | ||
604 | test_expect_success \ | |
605 | 'test title' \ | |
606 | '... test body ...' | |
607 | ||
97509a34 | 608 | - End the line with an opening single quote. |
18337d40 | 609 | |
97509a34 | 610 | - Indent here-document bodies, and use "<<-" instead of "<<" |
18337d40 LL |
611 | to strip leading TABs used for indentation: |
612 | ||
613 | test_expect_success 'test something' ' | |
614 | cat >expect <<-\EOF && | |
615 | one | |
616 | two | |
617 | three | |
618 | EOF | |
619 | test_something > actual && | |
620 | test_cmp expect actual | |
621 | ' | |
622 | ||
623 | Instead of: | |
624 | ||
625 | test_expect_success 'test something' ' | |
626 | cat >expect <<\EOF && | |
627 | one | |
628 | two | |
629 | three | |
630 | EOF | |
631 | test_something > actual && | |
632 | test_cmp expect actual | |
633 | ' | |
634 | ||
635 | - Quote or escape the EOF delimiter that begins a here-document if | |
97509a34 | 636 | there is no parameter or other expansion in it, to signal readers |
18337d40 LL |
637 | that they can skim it more casually: |
638 | ||
639 | cmd <<-\EOF | |
640 | literal here-document text without any expansion | |
641 | EOF | |
642 | ||
643 | ||
441ee35d MD |
644 | Do's & don'ts |
645 | ------------- | |
20873f45 | 646 | |
6fd45295 | 647 | Here are a few examples of things you probably should and shouldn't do |
20873f45 ÆAB |
648 | when writing tests. |
649 | ||
97509a34 | 650 | The "do's:" |
20873f45 | 651 | |
6fd45295 | 652 | - Put all code inside test_expect_success and other assertions. |
20873f45 ÆAB |
653 | |
654 | Even code that isn't a test per se, but merely some setup code | |
6fd45295 | 655 | should be inside a test assertion. |
20873f45 ÆAB |
656 | |
657 | - Chain your test assertions | |
658 | ||
659 | Write test code like this: | |
660 | ||
661 | git merge foo && | |
662 | git push bar && | |
663 | test ... | |
664 | ||
665 | Instead of: | |
666 | ||
667 | git merge hla | |
668 | git push gh | |
669 | test ... | |
670 | ||
671 | That way all of the commands in your tests will succeed or fail. If | |
00648ba0 EN |
672 | you must ignore the return value of something, consider using a |
673 | helper function (e.g. use sane_unset instead of unset, in order | |
674 | to avoid unportable return value for unsetting a variable that was | |
675 | already unset), or prepending the command with test_might_fail or | |
676 | test_must_fail. | |
20873f45 | 677 | |
0c357544 ÆAB |
678 | - Check the test coverage for your tests. See the "Test coverage" |
679 | below. | |
680 | ||
63d32945 MW |
681 | Don't blindly follow test coverage metrics; if a new function you added |
682 | doesn't have any coverage, then you're probably doing something wrong, | |
e8b55f5c ÆAB |
683 | but having 100% coverage doesn't necessarily mean that you tested |
684 | everything. | |
685 | ||
686 | Tests that are likely to smoke out future regressions are better | |
687 | than tests that just inflate the coverage metrics. | |
688 | ||
95b104c8 JS |
689 | - When a test checks for an absolute path that a git command generated, |
690 | construct the expected value using $(pwd) rather than $PWD, | |
691 | $TEST_DIRECTORY, or $TRASH_DIRECTORY. It makes a difference on | |
692 | Windows, where the shell (MSYS bash) mangles absolute path names. | |
693 | For details, see the commit message of 4114156ae9. | |
694 | ||
441ee35d MD |
695 | - Remember that inside the <script> part, the standard output and |
696 | standard error streams are discarded, and the test harness only | |
697 | reports "ok" or "not ok" to the end user running the tests. Under | |
698 | --verbose, they are shown to help debug the tests. | |
699 | ||
7cc112dc JH |
700 | - Be careful when you loop |
701 | ||
702 | You may need to verify multiple things in a loop, but the | |
703 | following does not work correctly: | |
704 | ||
705 | test_expect_success 'test three things' ' | |
706 | for i in one two three | |
707 | do | |
708 | test_something "$i" | |
709 | done && | |
710 | test_something_else | |
711 | ' | |
712 | ||
713 | Because the status of the loop itself is the exit status of the | |
714 | test_something in the last round, the loop does not fail when | |
715 | "test_something" for "one" or "two" fails. This is not what you | |
716 | want. | |
717 | ||
718 | Instead, you can break out of the loop immediately when you see a | |
719 | failure. Because all test_expect_* snippets are executed inside | |
720 | a function, "return 1" can be used to fail the test immediately | |
721 | upon a failure: | |
722 | ||
723 | test_expect_success 'test three things' ' | |
724 | for i in one two three | |
725 | do | |
726 | test_something "$i" || return 1 | |
727 | done && | |
728 | test_something_else | |
729 | ' | |
730 | ||
731 | Note that we still &&-chain the loop to propagate failures from | |
732 | earlier commands. | |
733 | ||
7c4449eb PS |
734 | - Repeat tests with slightly different arguments in a loop. |
735 | ||
736 | In some cases it may make sense to re-run the same set of tests with | |
737 | different options or commands to ensure that the command behaves | |
738 | despite the different parameters. This can be achieved by looping | |
739 | around a specific parameter: | |
740 | ||
741 | for arg in '' "--foo" | |
742 | do | |
743 | test_expect_success "test command ${arg:-without arguments}" ' | |
744 | command $arg | |
745 | ' | |
746 | done | |
747 | ||
748 | Note that while the test title uses double quotes ("), the test body | |
749 | should continue to use single quotes (') to avoid breakage in case the | |
750 | values contain e.g. quoting characters. The loop variable will be | |
751 | accessible regardless of the single quotes as the test body is passed | |
752 | to `eval`. | |
753 | ||
7cc112dc | 754 | |
441ee35d | 755 | And here are the "don'ts:" |
20873f45 | 756 | |
441ee35d | 757 | - Don't exit() within a <script> part. |
20873f45 ÆAB |
758 | |
759 | The harness will catch this as a programming error of the test. | |
760 | Use test_done instead if you need to stop the tests early (see | |
761 | "Skipping tests" below). | |
762 | ||
441ee35d MD |
763 | - Don't use '! git cmd' when you want to make sure the git command |
764 | exits with failure in a controlled way by calling "die()". Instead, | |
ad78585e JH |
765 | use 'test_must_fail git cmd'. This will signal a failure if git |
766 | dies in an unexpected way (e.g. segfault). | |
767 | ||
f445500e | 768 | On the other hand, don't use test_must_fail for running regular |
53de7424 JH |
769 | platform commands; just use '! cmd'. We are not in the business |
770 | of verifying that the world given to us sanely works. | |
f445500e | 771 | |
a378fee5 MD |
772 | - Don't feed the output of a git command to a pipe, as in: |
773 | ||
774 | git -C repo ls-files | | |
775 | xargs -n 1 basename | | |
776 | grep foo | |
777 | ||
778 | which will discard git's exit code and may mask a crash. In the | |
779 | above example, all exit codes are ignored except grep's. | |
780 | ||
781 | Instead, write the output of that command to a temporary | |
782 | file with ">" or assign it to a variable with "x=$(git ...)" rather | |
783 | than pipe it. | |
784 | ||
785 | - Don't use command substitution in a way that discards git's exit | |
786 | code. When assigning to a variable, the exit code is not discarded, | |
787 | e.g.: | |
788 | ||
789 | x=$(git cat-file -p $sha) && | |
790 | ... | |
791 | ||
792 | is OK because a crash in "git cat-file" will cause the "&&" chain | |
793 | to fail, but: | |
794 | ||
795 | test "refs/heads/foo" = "$(git symbolic-ref HEAD)" | |
796 | ||
797 | is not OK and a crash in git could go undetected. | |
798 | ||
441ee35d MD |
799 | - Don't use perl without spelling it as "$PERL_PATH". This is to help |
800 | our friends on Windows where the platform Perl often adds CR before | |
ad78585e | 801 | the end of line, and they bundle Git with a version of Perl that |
a0e0ec9f JK |
802 | does not do so, whose path is specified with $PERL_PATH. Note that we |
803 | provide a "perl" function which uses $PERL_PATH under the hood, so | |
804 | you do not need to worry when simply running perl in the test scripts | |
805 | (but you do, for example, on a shebang line or in a sub script | |
806 | created via "write_script"). | |
ad78585e | 807 | |
441ee35d MD |
808 | - Don't use sh without spelling it as "$SHELL_PATH", when the script |
809 | can be misinterpreted by broken platform shell (e.g. Solaris). | |
ad78585e | 810 | |
441ee35d | 811 | - Don't chdir around in tests. It is not sufficient to chdir to |
ad78585e JH |
812 | somewhere and then chdir back to the original location later in |
813 | the test, as any intermediate step can fail and abort the test, | |
814 | causing the next test to start in an unexpected directory. Do so | |
815 | inside a subshell if necessary. | |
816 | ||
441ee35d MD |
817 | - Don't save and verify the standard error of compound commands, i.e. |
818 | group commands, subshells, and shell functions (except test helper | |
94201a2b SG |
819 | functions like 'test_must_fail') like this: |
820 | ||
821 | ( cd dir && git cmd ) 2>error && | |
822 | test_cmp expect error | |
823 | ||
824 | When running the test with '-x' tracing, then the trace of commands | |
825 | executed in the compound command will be included in standard error | |
826 | as well, quite possibly throwing off the subsequent checks examining | |
827 | the output. Instead, save only the relevant git command's standard | |
828 | error: | |
829 | ||
830 | ( cd dir && git cmd 2>../error ) && | |
831 | test_cmp expect error | |
832 | ||
441ee35d | 833 | - Don't break the TAP output |
20873f45 | 834 | |
6fd45295 JH |
835 | The raw output from your test may be interpreted by a TAP harness. TAP |
836 | harnesses will ignore everything they don't know about, but don't step | |
837 | on their toes in these areas: | |
20873f45 ÆAB |
838 | |
839 | - Don't print lines like "$x..$y" where $x and $y are integers. | |
840 | ||
841 | - Don't print lines that begin with "ok" or "not ok". | |
842 | ||
6fd45295 | 843 | TAP harnesses expect a line that begins with either "ok" and "not |
20873f45 ÆAB |
844 | ok" to signal a test passed or failed (and our harness already |
845 | produces such lines), so your script shouldn't emit such lines to | |
846 | their output. | |
847 | ||
848 | You can glean some further possible issues from the TAP grammar | |
c1d44cee | 849 | (see https://metacpan.org/pod/TAP::Parser::Grammar#TAP-GRAMMAR) |
20873f45 ÆAB |
850 | but the best indication is to just run the tests with prove(1), |
851 | it'll complain if anything is amiss. | |
852 | ||
20873f45 | 853 | |
b5500d16 ÆAB |
854 | Skipping tests |
855 | -------------- | |
856 | ||
681186ae | 857 | If you need to skip tests you should do so by using the three-arg form |
99d9050d ÆAB |
858 | of the test_* functions (see the "Test harness library" section |
859 | below), e.g.: | |
860 | ||
ad78585e | 861 | test_expect_success PERL 'I need Perl' ' |
a0e0ec9f | 862 | perl -e "hlagh() if unf_unf()" |
ad78585e | 863 | ' |
99d9050d ÆAB |
864 | |
865 | The advantage of skipping tests like this is that platforms that don't | |
866 | have the PERL and other optional dependencies get an indication of how | |
867 | many tests they're missing. | |
868 | ||
869 | If the test code is too hairy for that (i.e. does a lot of setup work | |
870 | outside test assertions) you can also skip all remaining tests by | |
871 | setting skip_all and immediately call test_done: | |
b5500d16 ÆAB |
872 | |
873 | if ! test_have_prereq PERL | |
874 | then | |
875 | skip_all='skipping perl interface tests, perl not available' | |
876 | test_done | |
877 | fi | |
14cd1ff3 | 878 | |
99d9050d ÆAB |
879 | The string you give to skip_all will be used as an explanation for why |
880 | the test was skipped. | |
881 | ||
986aa7f1 JH |
882 | End with test_done |
883 | ------------------ | |
884 | ||
885 | Your script will be a sequence of tests, using helper functions | |
886 | from the test harness library. At the end of the script, call | |
887 | 'test_done'. | |
888 | ||
889 | ||
890 | Test harness library | |
891 | -------------------- | |
892 | ||
893 | There are a handful helper functions defined in the test harness | |
add5240f PB |
894 | library for your script to use. Some of them are listed below; |
895 | see test-lib-functions.sh for the full list and their options. | |
986aa7f1 | 896 | |
9a897893 | 897 | - test_expect_success [<prereq>] <message> <script> |
986aa7f1 | 898 | |
72942a61 | 899 | Usually takes two strings as parameters, and evaluates the |
986aa7f1 JH |
900 | <script>. If it yields success, test is considered |
901 | successful. <message> should state what it is testing. | |
902 | ||
903 | Example: | |
904 | ||
905 | test_expect_success \ | |
906 | 'git-write-tree should be able to write an empty tree.' \ | |
907 | 'tree=$(git-write-tree)' | |
908 | ||
9a897893 | 909 | If you supply three parameters the first will be taken to be a |
72942a61 | 910 | prerequisite; see the test_set_prereq and test_have_prereq |
9a897893 ÆAB |
911 | documentation below: |
912 | ||
913 | test_expect_success TTY 'git --paginate rev-list uses a pager' \ | |
914 | ' ... ' | |
915 | ||
93a57246 ÆAB |
916 | You can also supply a comma-separated list of prerequisites, in the |
917 | rare case where your test depends on more than one: | |
918 | ||
919 | test_expect_success PERL,PYTHON 'yo dawg' \ | |
f0a39ba5 | 920 | ' test $(perl -E '\''print eval "1 +" . qx[python -c "print(2)"]'\'') = "4" ' |
93a57246 | 921 | |
9a897893 | 922 | - test_expect_failure [<prereq>] <message> <script> |
986aa7f1 | 923 | |
41ac414e JH |
924 | This is NOT the opposite of test_expect_success, but is used |
925 | to mark a test that demonstrates a known breakage. Unlike | |
926 | the usual test_expect_success tests, which say "ok" on | |
927 | success and "FAIL" on failure, this will say "FIXED" on | |
928 | success and "still broken" on failure. Failures from these | |
929 | tests won't cause -i (immediate) to stop. | |
986aa7f1 | 930 | |
9a897893 ÆAB |
931 | Like test_expect_success this function can optionally use a three |
932 | argument invocation with a prerequisite as the first argument. | |
933 | ||
986aa7f1 JH |
934 | - test_debug <script> |
935 | ||
936 | This takes a single argument, <script>, and evaluates it only | |
937 | when the test script is started with --debug command line | |
938 | argument. This is primarily meant for use during the | |
939 | development of a new test script. | |
940 | ||
01c38103 | 941 | - debug [options] <git-command> |
6a94088c JS |
942 | |
943 | Run a git command inside a debugger. This is primarily meant for | |
01c38103 PB |
944 | use when debugging a failing test script. With '-t', use your |
945 | original TERM instead of test-lib.sh's "dumb", so that your | |
946 | debugger interface has colors. | |
6a94088c | 947 | |
986aa7f1 JH |
948 | - test_done |
949 | ||
950 | Your test script must have test_done at the end. Its purpose | |
951 | is to summarize successes and failures in the test script and | |
952 | exit with an appropriate error code. | |
953 | ||
00884968 JS |
954 | - test_tick |
955 | ||
956 | Make commit and tag names consistent by setting the author and | |
63d32945 | 957 | committer times to defined state. Subsequent calls will |
00884968 JS |
958 | advance the times by a fixed amount. |
959 | ||
960 | - test_commit <message> [<filename> [<contents>]] | |
961 | ||
962 | Creates a commit with the given message, committing the given | |
963 | file with the given contents (default for both is to reuse the | |
964 | message string), and adds a tag (again reusing the message | |
965 | string as name). Calls test_tick to make the SHA-1s | |
966 | reproducible. | |
967 | ||
968 | - test_merge <message> <commit-or-tag> | |
969 | ||
970 | Merges the given rev using the given message. Like test_commit, | |
971 | creates a tag and calls test_tick before committing. | |
986aa7f1 | 972 | |
72942a61 | 973 | - test_set_prereq <prereq> |
9a897893 ÆAB |
974 | |
975 | Set a test prerequisite to be used later with test_have_prereq. The | |
be53deef ÆAB |
976 | test-lib will set some prerequisites for you, see the |
977 | "Prerequisites" section below for a full list of these. | |
978 | ||
979 | Others you can set yourself and use later with either | |
980 | test_have_prereq directly, or the three argument invocation of | |
981 | test_expect_success and test_expect_failure. | |
9a897893 | 982 | |
72942a61 | 983 | - test_have_prereq <prereq> |
9a897893 | 984 | |
4473060b ÆAB |
985 | Check if we have a prerequisite previously set with test_set_prereq. |
986 | The most common way to use this explicitly (as opposed to the | |
987 | implicit use when an argument is passed to test_expect_*) is to skip | |
988 | all the tests at the start of the test script if we don't have some | |
989 | essential prerequisite: | |
9a897893 ÆAB |
990 | |
991 | if ! test_have_prereq PERL | |
992 | then | |
993 | skip_all='skipping perl interface tests, perl not available' | |
994 | test_done | |
995 | fi | |
996 | ||
892e6f7e ÆAB |
997 | - test_expect_code <exit-code> <command> |
998 | ||
999 | Run a command and ensure that it exits with the given exit code. | |
1000 | For example: | |
1001 | ||
1002 | test_expect_success 'Merge with d/f conflicts' ' | |
1003 | test_expect_code 1 git merge "merge msg" B master | |
1004 | ' | |
1005 | ||
12e31a6b | 1006 | - test_must_fail [<options>] <git-command> |
c9667456 JN |
1007 | |
1008 | Run a git command and ensure it fails in a controlled way. Use | |
971ecbd1 BC |
1009 | this instead of "! <git-command>". When git-command dies due to a |
1010 | segfault, test_must_fail diagnoses it as an error; "! <git-command>" | |
1011 | treats it as just another expected failure, which would let such a | |
1012 | bug go unnoticed. | |
c9667456 | 1013 | |
12e31a6b SG |
1014 | Accepts the following options: |
1015 | ||
1016 | ok=<signal-name>[,<...>]: | |
1017 | Don't treat an exit caused by the given signal as error. | |
1018 | Multiple signals can be specified as a comma separated list. | |
1019 | Currently recognized signal names are: sigpipe, success. | |
1020 | (Don't use 'success', use 'test_might_fail' instead.) | |
1021 | ||
1022 | - test_might_fail [<options>] <git-command> | |
c9667456 JN |
1023 | |
1024 | Similar to test_must_fail, but tolerate success, too. Use this | |
1025 | instead of "<git-command> || :" to catch failures due to segv. | |
1026 | ||
12e31a6b SG |
1027 | Accepts the same options as test_must_fail. |
1028 | ||
c9667456 JN |
1029 | - test_cmp <expected> <actual> |
1030 | ||
1031 | Check whether the content of the <actual> file matches the | |
1032 | <expected> file. This behaves like "cmp" but produces more | |
1033 | helpful output when the test is run with "-v" option. | |
1034 | ||
5a052626 TG |
1035 | - test_cmp_rev <expected> <actual> |
1036 | ||
1037 | Check whether the <expected> rev points to the same commit as the | |
1038 | <actual> rev. | |
1039 | ||
fb3340a6 JN |
1040 | - test_line_count (= | -lt | -ge | ...) <length> <file> |
1041 | ||
1042 | Check whether a file has the length it is expected to. | |
1043 | ||
45a26864 ÆAB |
1044 | - test_path_is_file <path> |
1045 | test_path_is_dir <path> | |
1046 | test_path_is_missing <path> | |
2caf20c5 | 1047 | |
72942a61 ML |
1048 | Check if the named path is a file, if the named path is a |
1049 | directory, or if the named path does not exist, respectively, | |
45a26864 | 1050 | and fail otherwise. |
2caf20c5 | 1051 | |
c9667456 JN |
1052 | - test_when_finished <script> |
1053 | ||
1054 | Prepend <script> to a list of commands to run to clean up | |
1055 | at the end of the current test. If some clean-up command | |
1056 | fails, the test will not pass. | |
1057 | ||
1058 | Example: | |
1059 | ||
1060 | test_expect_success 'branch pointing to non-commit' ' | |
1061 | git rev-parse HEAD^{tree} >.git/refs/heads/invalid && | |
1062 | test_when_finished "git update-ref -d refs/heads/invalid" && | |
1063 | ... | |
1064 | ' | |
1065 | ||
900721e1 JS |
1066 | - test_atexit <script> |
1067 | ||
1068 | Prepend <script> to a list of commands to run unconditionally to | |
1069 | clean up before the test script exits, e.g. to stop a daemon: | |
1070 | ||
1071 | test_expect_success 'test git daemon' ' | |
1072 | git daemon & | |
1073 | daemon_pid=$! && | |
1074 | test_atexit 'kill $daemon_pid' && | |
1075 | hello world | |
1076 | ' | |
1077 | ||
1078 | The commands will be executed before the trash directory is removed, | |
1079 | i.e. the atexit commands will still be able to access any pidfiles or | |
1080 | socket files. | |
1081 | ||
1082 | Note that these commands will be run even when a test script run | |
1083 | with '--immediate' fails. Be careful with your atexit commands to | |
1084 | minimize any changes to the failed state. | |
1085 | ||
bb98b01e | 1086 | - test_write_lines <lines> |
ac9afcc3 | 1087 | |
bb98b01e | 1088 | Write <lines> on standard output, one line per argument. |
ac9afcc3 MT |
1089 | Useful to prepare multi-line files in a compact form. |
1090 | ||
1091 | Example: | |
1092 | ||
bb98b01e | 1093 | test_write_lines a b c d e f g >foo |
ac9afcc3 MT |
1094 | |
1095 | Is a more compact equivalent of: | |
1096 | cat >foo <<-EOF | |
1097 | a | |
1098 | b | |
1099 | c | |
1100 | d | |
1101 | e | |
1102 | f | |
1103 | g | |
1104 | EOF | |
1105 | ||
1106 | ||
add5240f | 1107 | - test_pause [options] |
c4d2539a JL |
1108 | |
1109 | This command is useful for writing and debugging tests and must be | |
1110 | removed before submitting. It halts the execution of the test and | |
1111 | spawns a shell in the trash directory. Exit the shell to continue | |
1112 | the test. Example: | |
1113 | ||
1114 | test_expect_success 'test' ' | |
1115 | git do-something >actual && | |
1116 | test_pause && | |
1117 | test_cmp expected actual | |
1118 | ' | |
1119 | ||
9ce415d9 JS |
1120 | - test_ln_s_add <path1> <path2> |
1121 | ||
1122 | This function helps systems whose filesystem does not support symbolic | |
1123 | links. Use it to add a symbolic link entry to the index when it is not | |
1124 | important that the file system entry is a symbolic link, i.e., instead | |
1125 | of the sequence | |
1126 | ||
1127 | ln -s foo bar && | |
1128 | git add bar | |
1129 | ||
1130 | Sometimes it is possible to split a test in a part that does not need | |
1131 | the symbolic link in the file system and a part that does; then only | |
1132 | the latter part need be protected by a SYMLINKS prerequisite (see below). | |
1133 | ||
d6546af7 | 1134 | - test_path_is_executable |
1135 | ||
1136 | This tests whether a file is executable and prints an error message | |
1137 | if not. This must be used only under the POSIXPERM prerequisite | |
1138 | (see below). | |
1139 | ||
2c02b110 | 1140 | - test_oid_init |
1141 | ||
1142 | This function loads facts and useful object IDs related to the hash | |
1143 | algorithm(s) in use from the files in t/oid-info. | |
1144 | ||
1145 | - test_oid_cache | |
1146 | ||
1147 | This function reads per-hash algorithm information from standard | |
1148 | input (usually a heredoc) in the format described in | |
1149 | t/oid-info/README. This is useful for test-specific values, such as | |
1150 | object IDs, which must vary based on the hash algorithm. | |
1151 | ||
1152 | Certain fixed values, such as hash sizes and common placeholder | |
1153 | object IDs, can be loaded with test_oid_init (described above). | |
1154 | ||
1155 | - test_oid <key> | |
1156 | ||
1157 | This function looks up a value for the hash algorithm in use, based | |
1158 | on the key given. The value must have been loaded using | |
1159 | test_oid_init or test_oid_cache. Providing an unknown key is an | |
1160 | error. | |
1161 | ||
11f470ae JH |
1162 | - yes [<string>] |
1163 | ||
1164 | This is often seen in modern UNIX but some platforms lack it, so | |
1165 | the test harness overrides the platform implementation with a | |
1166 | more limited one. Use this only when feeding a handful lines of | |
1167 | output to the downstream---unlike the real version, it generates | |
1168 | only up to 99 lines. | |
1169 | ||
43a2afee SG |
1170 | - test_bool_env <env-variable-name> <default-value> |
1171 | ||
1172 | Given the name of an environment variable with a bool value, | |
1173 | normalize its value to a 0 (true) or 1 (false or empty string) | |
1174 | return code. Return with code corresponding to the given default | |
1175 | value if the variable is unset. | |
1176 | Abort the test script if either the value of the variable or the | |
1177 | default are not valid bool values. | |
1178 | ||
11f470ae | 1179 | |
be53deef ÆAB |
1180 | Prerequisites |
1181 | ------------- | |
1182 | ||
1183 | These are the prerequisites that the test library predefines with | |
1184 | test_have_prereq. | |
1185 | ||
1186 | See the prereq argument to the test_* functions in the "Test harness | |
1187 | library" section above and the "test_have_prereq" function for how to | |
1188 | use these, and "test_set_prereq" for how to define your own. | |
1189 | ||
f8fc0ee3 | 1190 | - PYTHON |
be53deef | 1191 | |
f8fc0ee3 JN |
1192 | Git wasn't compiled with NO_PYTHON=YesPlease. Wrap any tests that |
1193 | need Python with this. | |
1194 | ||
1195 | - PERL | |
1196 | ||
1197 | Git wasn't compiled with NO_PERL=YesPlease. | |
1198 | ||
1199 | Even without the PERL prerequisite, tests can assume there is a | |
1200 | usable perl interpreter at $PERL_PATH, though it need not be | |
1201 | particularly modern. | |
be53deef ÆAB |
1202 | |
1203 | - POSIXPERM | |
1204 | ||
1205 | The filesystem supports POSIX style permission bits. | |
1206 | ||
1207 | - BSLASHPSPEC | |
1208 | ||
1209 | Backslashes in pathspec are not directory separators. This is not | |
1210 | set on Windows. See 6fd1106a for details. | |
1211 | ||
1212 | - EXECKEEPSPID | |
1213 | ||
1214 | The process retains the same pid across exec(2). See fb9a2bea for | |
1215 | details. | |
1216 | ||
20073274 AS |
1217 | - PIPE |
1218 | ||
1219 | The filesystem we're on supports creation of FIFOs (named pipes) | |
1220 | via mkfifo(1). | |
1221 | ||
be53deef ÆAB |
1222 | - SYMLINKS |
1223 | ||
1224 | The filesystem we're on supports symbolic links. E.g. a FAT | |
1225 | filesystem doesn't support these. See 704a3143 for details. | |
2fac6a4b | 1226 | |
c91cfd19 ÆAB |
1227 | - SANITY |
1228 | ||
1229 | Test is not run by root user, and an attempt to write to an | |
1230 | unwritable file is expected to fail correctly. | |
2fac6a4b | 1231 | |
3eb585c1 | 1232 | - PCRE |
8f852ce6 | 1233 | |
3eb585c1 | 1234 | Git was compiled with support for PCRE. Wrap any tests |
8f852ce6 MK |
1235 | that use git-grep --perl-regexp or git-grep -P in these. |
1236 | ||
ac39aa61 MG |
1237 | - CASE_INSENSITIVE_FS |
1238 | ||
1239 | Test is run on a case insensitive file system. | |
1240 | ||
5b0b5dd4 MG |
1241 | - UTF8_NFD_TO_NFC |
1242 | ||
1243 | Test is run on a filesystem which converts decomposed utf-8 (nfd) | |
1244 | to precomposed utf-8 (nfc). | |
1245 | ||
68c7d276 ÆAB |
1246 | - PTHREADS |
1247 | ||
1248 | Git wasn't compiled with NO_PTHREADS=YesPlease. | |
1249 | ||
c305e667 HWN |
1250 | - REFFILES |
1251 | ||
1252 | Test is specific to packed/loose ref storage, and should be | |
1253 | disabled for other ref storage backends | |
1254 | ||
1255 | ||
986aa7f1 JH |
1256 | Tips for Writing Tests |
1257 | ---------------------- | |
1258 | ||
1259 | As with any programming projects, existing programs are the best | |
1260 | source of the information. However, do _not_ emulate | |
1261 | t0000-basic.sh when writing your tests. The test is special in | |
788db145 | 1262 | that it tries to validate the very core of Git. For example, it |
986aa7f1 JH |
1263 | knows that there will be 256 subdirectories under .git/objects/, |
1264 | and it knows that the object ID of an empty tree is a certain | |
1265 | 40-byte string. This is deliberately done so in t0000-basic.sh | |
1266 | because the things the very basic core test tries to achieve is | |
788db145 | 1267 | to serve as a basis for people who are changing the Git internals |
986aa7f1 | 1268 | drastically. For these people, after making certain changes, |
97509a34 ŠN |
1269 | not seeing failures from the basic test _is_ a failure. Any |
1270 | Git core changes so drastic that they change even these | |
986aa7f1 JH |
1271 | otherwise supposedly stable object IDs should be accompanied by |
1272 | an update to t0000-basic.sh. | |
1273 | ||
1274 | However, other tests that simply rely on basic parts of the core | |
788db145 DL |
1275 | Git working properly should not have that level of intimate |
1276 | knowledge of the core Git internals. If all the test scripts | |
986aa7f1 JH |
1277 | hardcoded the object IDs like t0000-basic.sh does, that defeats |
1278 | the purpose of t0000-basic.sh, which is to isolate that level of | |
1279 | validation in one place. Your test also ends up needing | |
97509a34 | 1280 | an update whenever the internals change, so do _not_ |
986aa7f1 | 1281 | do it and leave the low level of validation to t0000-basic.sh. |
d15e9ebc | 1282 | |
0c357544 ÆAB |
1283 | Test coverage |
1284 | ------------- | |
1285 | ||
1286 | You can use the coverage tests to find code paths that are not being | |
1287 | used or properly exercised yet. | |
1288 | ||
1289 | To do that, run the coverage target at the top-level (not in the t/ | |
1290 | directory): | |
1291 | ||
1292 | make coverage | |
1293 | ||
1294 | That'll compile Git with GCC's coverage arguments, and generate a test | |
1295 | report with gcov after the tests finish. Running the coverage tests | |
1296 | can take a while, since running the tests in parallel is incompatible | |
1297 | with GCC's coverage mode. | |
1298 | ||
1299 | After the tests have run you can generate a list of untested | |
1300 | functions: | |
1301 | ||
1302 | make coverage-untested-functions | |
1303 | ||
1304 | You can also generate a detailed per-file HTML report using the | |
1305 | Devel::Cover module. To install it do: | |
1306 | ||
1307 | # On Debian or Ubuntu: | |
1308 | sudo aptitude install libdevel-cover-perl | |
1309 | ||
1310 | # From the CPAN with cpanminus | |
d05b08cd | 1311 | curl -L https://cpanmin.us/ | perl - --sudo --self-upgrade |
0c357544 ÆAB |
1312 | cpanm --sudo Devel::Cover |
1313 | ||
1314 | Then, at the top-level: | |
1315 | ||
1316 | make cover_db_html | |
1317 | ||
1318 | That'll generate a detailed cover report in the "cover_db_html" | |
1319 | directory, which you can then copy to a webserver, or inspect locally | |
1320 | in a browser. |