| Git version interoperability tests |
| ================================== |
| |
| This directory has interoperability tests for git. Each script is |
| similar to the normal test scripts found in t/, but with the added twist |
| that two special versions of git, "git.a" and "git.b", are available in |
| the PATH. Individual tests can then check the interaction between the |
| two versions. |
| |
| When you add a feature that handles backwards compatibility between git |
| versions, it's encouraged to add a test here to make sure it behaves as |
| you expect. |
| |
| |
| Running Tests |
| ------------- |
| |
| The easiest way to run tests is to say "make". This runs all |
| the tests against their default versions. |
| |
| You can run a single test like: |
| |
| $ ./i0000-basic.sh |
| ok 1 - bare git is forbidden |
| ok 2 - git.a version (v1.6.6.3) |
| ok 3 - git.b version (v2.11.1) |
| # passed all 3 test(s) |
| 1..3 |
| |
| Each test contains default versions to run against. You may override |
| these by setting `GIT_TEST_VERSION_A` and `GIT_TEST_VERSION_B` in the |
| environment. Note that not all combinations will give sensible outcomes |
| for all tests (e.g., a test checking for a specific old/new interaction |
| may want something "old" enough" and something "new" enough; see |
| individual tests for details). |
| |
| Version names should be resolvable as revisions in the current |
| repository. They will be exported and built as needed using the |
| config.mak files found at the root of your working tree. |
| |
| The exception is the special version "." which uses the currently-built |
| contents of your working tree. |
| |
| You can set the following variables (in the environment or in your config.mak): |
| |
| GIT_INTEROP_MAKE_OPTS |
| Options to pass to `make` when building a git version (e.g., |
| `-j8`). |
| |
| You can also pass any command-line options taken by ordinary git tests (e.g., |
| "-v"). |
| |
| |
| Naming Tests |
| ------------ |
| |
| The interop test files are named like: |
| |
| iNNNN-short-description.sh |
| |
| where N is a decimal digit. The same conventions for choosing NNNN as |
| for normal tests apply. |
| |
| |
| Writing Tests |
| ------------- |
| |
| An interop test script starts like a normal script, declaring a few |
| variables and then including interop-lib.sh (which includes test-lib.sh). |
| Besides test_description, you should also set the $VERSION_A and $VERSION_B |
| variables to give the default versions to test against. See t0000-basic.sh for |
| an example. |
| |
| You can then use test_expect_success as usual, with a few differences: |
| |
| 1. The special commands "git.a" and "git.b" correspond to the |
| two versions. |
| |
| 2. You cannot call a bare "git". This is to prevent accidents where |
| you meant "git.a" or "git.b". |
| |
| 3. The trash directory is _not_ a git repository by default. You |
| should create one with the appropriate version of git. |
| |
| At the end of the script, call test_done as usual. |
| |
| Some older versions may need a few build knobs tweaked (e.g., ancient |
| versions of Git no longer build with modern OpenSSL). Your script can |
| set MAKE_OPTS_A and MAKE_OPTS_B, which will be passed alongside |
| GIT_INTEROP_MAKE_OPTS. Users can override them per-script by setting |
| GIT_INTEROP_MAKE_OPTS_{A,B} in the environment, just like they can set |
| GIT_TEST_VERSION_{A,B}. |