| 1 | Git version interoperability tests |
| 2 | ================================== |
| 3 | |
| 4 | This directory has interoperability tests for git. Each script is |
| 5 | similar to the normal test scripts found in t/, but with the added twist |
| 6 | that two special versions of git, "git.a" and "git.b", are available in |
| 7 | the PATH. Individual tests can then check the interaction between the |
| 8 | two versions. |
| 9 | |
| 10 | When you add a feature that handles backwards compatibility between git |
| 11 | versions, it's encouraged to add a test here to make sure it behaves as |
| 12 | you expect. |
| 13 | |
| 14 | |
| 15 | Running Tests |
| 16 | ------------- |
| 17 | |
| 18 | The easiest way to run tests is to say "make". This runs all |
| 19 | the tests against their default versions. |
| 20 | |
| 21 | You can run a single test like: |
| 22 | |
| 23 | $ ./i0000-basic.sh |
| 24 | ok 1 - bare git is forbidden |
| 25 | ok 2 - git.a version (v1.6.6.3) |
| 26 | ok 3 - git.b version (v2.11.1) |
| 27 | # passed all 3 test(s) |
| 28 | 1..3 |
| 29 | |
| 30 | Each test contains default versions to run against. You may override |
| 31 | these by setting `GIT_TEST_VERSION_A` and `GIT_TEST_VERSION_B` in the |
| 32 | environment. Note that not all combinations will give sensible outcomes |
| 33 | for all tests (e.g., a test checking for a specific old/new interaction |
| 34 | may want something "old" enough" and something "new" enough; see |
| 35 | individual tests for details). |
| 36 | |
| 37 | Version names should be resolvable as revisions in the current |
| 38 | repository. They will be exported and built as needed using the |
| 39 | config.mak files found at the root of your working tree. |
| 40 | |
| 41 | The exception is the special version "." which uses the currently-built |
| 42 | contents of your working tree. |
| 43 | |
| 44 | You can set the following variables (in the environment or in your config.mak): |
| 45 | |
| 46 | GIT_INTEROP_MAKE_OPTS |
| 47 | Options to pass to `make` when building a git version (e.g., |
| 48 | `-j8`). |
| 49 | |
| 50 | You can also pass any command-line options taken by ordinary git tests (e.g., |
| 51 | "-v"). |
| 52 | |
| 53 | |
| 54 | Naming Tests |
| 55 | ------------ |
| 56 | |
| 57 | The interop test files are named like: |
| 58 | |
| 59 | iNNNN-short-description.sh |
| 60 | |
| 61 | where N is a decimal digit. The same conventions for choosing NNNN as |
| 62 | for normal tests apply. |
| 63 | |
| 64 | |
| 65 | Writing Tests |
| 66 | ------------- |
| 67 | |
| 68 | An interop test script starts like a normal script, declaring a few |
| 69 | variables and then including interop-lib.sh (which includes test-lib.sh). |
| 70 | Besides test_description, you should also set the $VERSION_A and $VERSION_B |
| 71 | variables to give the default versions to test against. See t0000-basic.sh for |
| 72 | an example. |
| 73 | |
| 74 | You can then use test_expect_success as usual, with a few differences: |
| 75 | |
| 76 | 1. The special commands "git.a" and "git.b" correspond to the |
| 77 | two versions. |
| 78 | |
| 79 | 2. You cannot call a bare "git". This is to prevent accidents where |
| 80 | you meant "git.a" or "git.b". |
| 81 | |
| 82 | 3. The trash directory is _not_ a git repository by default. You |
| 83 | should create one with the appropriate version of git. |
| 84 | |
| 85 | At the end of the script, call test_done as usual. |
| 86 | |
| 87 | Some older versions may need a few build knobs tweaked (e.g., ancient |
| 88 | versions of Git no longer build with modern OpenSSL). Your script can |
| 89 | set MAKE_OPTS_A and MAKE_OPTS_B, which will be passed alongside |
| 90 | GIT_INTEROP_MAKE_OPTS. Users can override them per-script by setting |
| 91 | GIT_INTEROP_MAKE_OPTS_{A,B} in the environment, just like they can set |
| 92 | GIT_TEST_VERSION_{A,B}. |