t/interop/README

   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.