]>
Commit | Line | Data |
---|---|---|
986aa7f1 JH |
1 | Core GIT Tests |
2 | ============== | |
3 | ||
4 | This directory holds many test scripts for core GIT tools. The | |
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 *** | |
5c94f87e | 21 | * ok 1: .git/objects should be empty after git-init in an empty repo. |
986aa7f1 | 22 | * ok 2: .git/objects should have 256 subdirectories. |
215a7ad1 | 23 | * ok 3: git-update-index without --add should fail adding. |
986aa7f1 | 24 | ... |
215a7ad1 | 25 | * ok 23: no diff after checkout and git-update-index --refresh. |
986aa7f1 JH |
26 | * passed all 23 test(s) |
27 | *** t0100-environment-names.sh *** | |
28 | * ok 1: using old names should issue warnings. | |
29 | * ok 2: using old names but having new names should not issue warnings. | |
30 | ... | |
31 | ||
32 | Or you can run each test individually from command line, like | |
33 | this: | |
34 | ||
14cd1ff3 | 35 | $ sh ./t3001-ls-files-killed.sh |
215a7ad1 | 36 | * ok 1: git-update-index --add to add various paths. |
986aa7f1 JH |
37 | * ok 2: git-ls-files -k to show killed files. |
38 | * ok 3: validate git-ls-files -k output. | |
39 | * passed all 3 test(s) | |
40 | ||
41 | You can pass --verbose (or -v), --debug (or -d), and --immediate | |
4e1be63c JS |
42 | (or -i) command line argument to the test, or by setting GIT_TEST_OPTS |
43 | appropriately before running "make". | |
986aa7f1 JH |
44 | |
45 | --verbose:: | |
46 | This makes the test more verbose. Specifically, the | |
47 | command being run and their output if any are also | |
48 | output. | |
49 | ||
50 | --debug:: | |
51 | This may help the person who is developing a new test. | |
52 | It causes the command defined with test_debug to run. | |
53 | ||
54 | --immediate:: | |
55 | This causes the test to immediately exit upon the first | |
56 | failed test. | |
57 | ||
5e2c08c6 LW |
58 | --long-tests:: |
59 | This causes additional long-running tests to be run (where | |
60 | available), for more exhaustive testing. | |
61 | ||
4e1be63c JS |
62 | --valgrind:: |
63 | Execute all Git binaries with valgrind and exit with status | |
64 | 126 on errors (just like regular tests, this will only stop | |
65 | the test script when running under -i). Valgrind errors | |
66 | go to stderr, so you might want to pass the -v option, too. | |
986aa7f1 | 67 | |
3da93652 JS |
68 | Since it makes no sense to run the tests with --valgrind and |
69 | not see any output, this option implies --verbose. For | |
70 | convenience, it also implies --tee. | |
71 | ||
44138559 JS |
72 | --tee:: |
73 | In addition to printing the test output to the terminal, | |
74 | write it to files named 't/test-results/$TEST_NAME.out'. | |
75 | As the names depend on the tests' file names, it is safe to | |
76 | run the tests with this option in parallel. | |
77 | ||
e160da7f MO |
78 | You can also set the GIT_TEST_INSTALLED environment variable to |
79 | the bindir of an existing git installation to test that installation. | |
80 | You still need to have built this git sandbox, from which various | |
81 | test-* support programs, templates, and perl libraries are used. | |
82 | If your installed git is incomplete, it will silently test parts of | |
83 | your built version instead. | |
84 | ||
85 | When using GIT_TEST_INSTALLED, you can also set GIT_TEST_EXEC_PATH to | |
86 | override the location of the dashed-form subcommands (what | |
87 | GIT_EXEC_PATH would be used for during normal operation). | |
88 | GIT_TEST_EXEC_PATH defaults to `$GIT_TEST_INSTALLED/git --exec-path`. | |
89 | ||
90 | ||
fbd458a3 JN |
91 | Skipping Tests |
92 | -------------- | |
93 | ||
94 | In some environments, certain tests have no way of succeeding | |
95 | due to platform limitation, such as lack of 'unzip' program, or | |
96 | filesystem that do not allow arbitrary sequence of non-NUL bytes | |
97 | as pathnames. | |
98 | ||
99 | You should be able to say something like | |
100 | ||
101 | $ GIT_SKIP_TESTS=t9200.8 sh ./t9200-git-cvsexport-commit.sh | |
102 | ||
103 | and even: | |
104 | ||
105 | $ GIT_SKIP_TESTS='t[0-4]??? t91?? t9200.8' make | |
106 | ||
107 | to omit such tests. The value of the environment variable is a | |
108 | SP separated list of patterns that tells which tests to skip, | |
109 | and either can match the "t[0-9]{4}" part to skip the whole | |
110 | test, or t[0-9]{4} followed by ".$number" to say which | |
111 | particular test to skip. | |
112 | ||
113 | Note that some tests in the existing test suite rely on previous | |
114 | test item, so you cannot arbitrarily disable one and expect the | |
115 | remainder of test to check what the test originally was intended | |
116 | to check. | |
117 | ||
118 | ||
f50c9f76 PB |
119 | Naming Tests |
120 | ------------ | |
121 | ||
122 | The test files are named as: | |
123 | ||
124 | tNNNN-commandname-details.sh | |
125 | ||
126 | where N is a decimal digit. | |
127 | ||
128 | First digit tells the family: | |
129 | ||
130 | 0 - the absolute basics and global stuff | |
131 | 1 - the basic commands concerning database | |
132 | 2 - the basic commands concerning the working tree | |
133 | 3 - the other basic commands (e.g. ls-files) | |
134 | 4 - the diff commands | |
135 | 5 - the pull and exporting commands | |
136 | 6 - the revision tree commands (even e.g. merge-base) | |
8f4a9b62 | 137 | 7 - the porcelainish commands concerning the working tree |
8757749e JN |
138 | 8 - the porcelainish commands concerning forensics |
139 | 9 - the git tools | |
f50c9f76 PB |
140 | |
141 | Second digit tells the particular command we are testing. | |
142 | ||
143 | Third digit (optionally) tells the particular switch or group of switches | |
144 | we are testing. | |
145 | ||
77656600 JH |
146 | If you create files under t/ directory (i.e. here) that is not |
147 | the top-level test script, never name the file to match the above | |
148 | pattern. The Makefile here considers all such files as the | |
149 | top-level test script and tries to run all of them. A care is | |
150 | especially needed if you are creating a common test library | |
151 | file, similar to test-lib.sh, because such a library file may | |
152 | not be suitable for standalone execution. | |
153 | ||
f50c9f76 | 154 | |
986aa7f1 JH |
155 | Writing Tests |
156 | ------------- | |
157 | ||
158 | The test script is written as a shell script. It should start | |
159 | with the standard "#!/bin/sh" with copyright notices, and an | |
160 | assignment to variable 'test_description', like this: | |
161 | ||
162 | #!/bin/sh | |
163 | # | |
164 | # Copyright (c) 2005 Junio C Hamano | |
165 | # | |
166 | ||
14cd1ff3 | 167 | test_description='xxx test (option --frotz) |
986aa7f1 JH |
168 | |
169 | This test registers the following structure in the cache | |
170 | and tries to run git-ls-files with option --frotz.' | |
171 | ||
f50c9f76 | 172 | |
986aa7f1 JH |
173 | Source 'test-lib.sh' |
174 | -------------------- | |
175 | ||
176 | After assigning test_description, the test script should source | |
177 | test-lib.sh like this: | |
178 | ||
179 | . ./test-lib.sh | |
180 | ||
181 | This test harness library does the following things: | |
182 | ||
183 | - If the script is invoked with command line argument --help | |
184 | (or -h), it shows the test_description and exits. | |
185 | ||
186 | - Creates an empty test directory with an empty .git/objects | |
9231e3a9 | 187 | database and chdir(2) into it. This directory is 't/trash directory' |
986aa7f1 JH |
188 | if you must know, but I do not think you care. |
189 | ||
190 | - Defines standard test helper functions for your scripts to | |
191 | use. These functions are designed to make all scripts behave | |
192 | consistently when command line arguments --verbose (or -v), | |
193 | --debug (or -d), and --immediate (or -i) is given. | |
194 | ||
14cd1ff3 | 195 | |
986aa7f1 JH |
196 | End with test_done |
197 | ------------------ | |
198 | ||
199 | Your script will be a sequence of tests, using helper functions | |
200 | from the test harness library. At the end of the script, call | |
201 | 'test_done'. | |
202 | ||
203 | ||
204 | Test harness library | |
205 | -------------------- | |
206 | ||
207 | There are a handful helper functions defined in the test harness | |
208 | library for your script to use. | |
209 | ||
210 | - test_expect_success <message> <script> | |
211 | ||
212 | This takes two strings as parameter, and evaluates the | |
213 | <script>. If it yields success, test is considered | |
214 | successful. <message> should state what it is testing. | |
215 | ||
216 | Example: | |
217 | ||
218 | test_expect_success \ | |
219 | 'git-write-tree should be able to write an empty tree.' \ | |
220 | 'tree=$(git-write-tree)' | |
221 | ||
222 | - test_expect_failure <message> <script> | |
223 | ||
41ac414e JH |
224 | This is NOT the opposite of test_expect_success, but is used |
225 | to mark a test that demonstrates a known breakage. Unlike | |
226 | the usual test_expect_success tests, which say "ok" on | |
227 | success and "FAIL" on failure, this will say "FIXED" on | |
228 | success and "still broken" on failure. Failures from these | |
229 | tests won't cause -i (immediate) to stop. | |
986aa7f1 JH |
230 | |
231 | - test_debug <script> | |
232 | ||
233 | This takes a single argument, <script>, and evaluates it only | |
234 | when the test script is started with --debug command line | |
235 | argument. This is primarily meant for use during the | |
236 | development of a new test script. | |
237 | ||
238 | - test_done | |
239 | ||
240 | Your test script must have test_done at the end. Its purpose | |
241 | is to summarize successes and failures in the test script and | |
242 | exit with an appropriate error code. | |
243 | ||
00884968 JS |
244 | - test_tick |
245 | ||
246 | Make commit and tag names consistent by setting the author and | |
247 | committer times to defined stated. Subsequent calls will | |
248 | advance the times by a fixed amount. | |
249 | ||
250 | - test_commit <message> [<filename> [<contents>]] | |
251 | ||
252 | Creates a commit with the given message, committing the given | |
253 | file with the given contents (default for both is to reuse the | |
254 | message string), and adds a tag (again reusing the message | |
255 | string as name). Calls test_tick to make the SHA-1s | |
256 | reproducible. | |
257 | ||
258 | - test_merge <message> <commit-or-tag> | |
259 | ||
260 | Merges the given rev using the given message. Like test_commit, | |
261 | creates a tag and calls test_tick before committing. | |
986aa7f1 JH |
262 | |
263 | Tips for Writing Tests | |
264 | ---------------------- | |
265 | ||
266 | As with any programming projects, existing programs are the best | |
267 | source of the information. However, do _not_ emulate | |
268 | t0000-basic.sh when writing your tests. The test is special in | |
269 | that it tries to validate the very core of GIT. For example, it | |
270 | knows that there will be 256 subdirectories under .git/objects/, | |
271 | and it knows that the object ID of an empty tree is a certain | |
272 | 40-byte string. This is deliberately done so in t0000-basic.sh | |
273 | because the things the very basic core test tries to achieve is | |
274 | to serve as a basis for people who are changing the GIT internal | |
275 | drastically. For these people, after making certain changes, | |
276 | not seeing failures from the basic test _is_ a failure. And | |
277 | such drastic changes to the core GIT that even changes these | |
278 | otherwise supposedly stable object IDs should be accompanied by | |
279 | an update to t0000-basic.sh. | |
280 | ||
281 | However, other tests that simply rely on basic parts of the core | |
282 | GIT working properly should not have that level of intimate | |
283 | knowledge of the core GIT internals. If all the test scripts | |
284 | hardcoded the object IDs like t0000-basic.sh does, that defeats | |
285 | the purpose of t0000-basic.sh, which is to isolate that level of | |
286 | validation in one place. Your test also ends up needing | |
287 | updating when such a change to the internal happens, so do _not_ | |
288 | do it and leave the low level of validation to t0000-basic.sh. |