docs/testing.mkd

   1 # testing gitolite
   2
   3 <font color="red">**WARNING: this will clobber [these files and
   4 directories][clobber] in your `$HOME`.  Ideally, you should use a throwaway
   5 userid**.</font>
   6
   7 ----
   8
   9 Running gitolite's test suite is really just a superset of [trying it out
  10 safely][trying].
  11
  12 [trying]: install#trying-out-gitolite-safely
  13
  14 To run the full test suite, create a **throw-away userid**, log in to it, then
  15 run these commands:
  16
  17     git config --global include.path ~/.gitconfig.local
  18     git clone https://github.com/sitaramc/gitolite
  19     cd gitolite
  20     prove
  21
  22 You will get an error that forces you to read `t/README` and set an env var
  23 before the test can proceed.  This is intentional; I've had people who don't
  24 pay attention to the "data loss" warning, and then complain that it was not
  25 prominent enough.  Forcing them to read a much smaller page appears to focus
  26 their attention better!
  27
  28 The test suite should run fine on most recent Linuxes and Unixes.  Although
  29 gitolite itself should work fine with any git after 1.6.6 or so, the test
  30 suite generally requires a more recent git.
  31
  32 Make sure:
  33
  34   * `$HOME/bin` is in `$PATH`
  35   * sshd allows incoming ssh to this userid, at least from localhost
  36
  37 Gitolite's test suite is mostly written using [tsh][] -- the "testing shell".
  38 Take a look at some of the scripts and you will see what it looks like.  It
  39 has a few quirks and nuances, but it's fine for what I need here.
  40
  41 [tsh]: https://github.com/sitaramc/tsh
  42
  43 The tests also use a somewhat convoluted system of environment variables in
  44 order to run *entirely* as a local user, without going through ssh at all.
  45 This lets a complete test suite run in about a lot less time than it would
  46 otherwise take.
  47
  48 If you think that defeats the purpose of the testing, you haven't read
  49 [this][auth] yet.
  50
  51 # appendix 1 -- the clobber list
  52
  53 When you [try out gitolite][trying] or run the test suite, the following files
  54 and directories in your \$HOME are potentially clobbered.
  55
  56     .gitconfig
  57     .gitolite/
  58     .gitolite.rc
  59     projects.list
  60     repositories/
  61     .ssh/
  62
  63 [auth]: concepts#authentication-and-authorisation
  64 [clobber]: testing#appendix-1-the-clobber-list