gitolite/t/README.mkd

## notes on the testing setup

**WARNING: PLEASE use a dedicated user for doing this**.  Various files and
directories get overwritten and it's much simpler this way.

In this document:

  * <a href="#_terminology">terminology</a>
  * <a href="#_notes_and_background">notes and background</a>
  * <a href="#_playing_with_gitolite">playing with gitolite</a>
  * <a href="#_testing_gitolite">testing gitolite</a>
  * <a href="#_instructions_for_adding_new_tests">instructions for adding new tests</a>

<a name="_terminology"></a>

### terminology

    #define PW "patches welcome!"
    #define TODO PW

<a name="_notes_and_background"></a>

### notes and background

All testing is done on one **brand new** userid.  We use ssh host alias tricks
to simulate multiple gitolite users within this, so `ssh gitolite info` gets
you different results than `ssh u1 info`.

The test suite is mainly meant for testing **the core (access control)
functionality**.  It doesn't test anything else, like say the install or
upgrade operations.  Other big features NOT covered by the test suite are
mirroring, smart http, and password-based access.

Note that the test driver has evolved as new scripts were added; you will see
that older scripts are a little less sophisticated.

<a name="_playing_with_gitolite"></a>

### playing with gitolite

(Please heed the warning at the top of this document and use a dedicated user
for this).

Playing with gitolite is easy.

  * Create a userid (doesn't matter what it's called; we'll pretend it's
    "gl-test" in this document).

  * Make sure sshd allows incoming ssh to this userid at least from localhost.
    (Out of scope for this document: sshd config, 'AllowUsers', etc...)

  * Now log in as this user (doesn't matter how), and run the following
    commands:

        cd $HOME        # if not already in $HOME
        git clone git://github.com/sitaramc/gitolite
        gitolite/t/install

    This installs the "testbed" in the userid you chose.  No other user is
    affected in any way.

This is what you get when you do this:

  * A gitolite user called "tester", tied to an ssh host alias called
    "gitolite".  This user has RW+ rights to the admin repo; running `ssh
    gitolite info` should get you the expected results.

  * Six gitolite users called "u1" through "u6", all done through ssh host
    aliases.  Running `ssh u1 info` etc. should show you only the "testing"
    repo accessible to them.

  * A clone of the admin repo in `~/gitolite-admin`, created by `git clone
    gitolite:gitolite-admin`.  If you `cd ~/gitolite-admin`, you will see the
    keys for the users mentioned above (tester, u1, ..., u6).

  * The rest of a gitolite installation, such as the rc file in `~/.gitolite.rc` etc.

Don't forget that the client and the server are all on the same user on the
same machine.

And don't forget, too, that we are simulating 7 gitolite users using ssh keys!
(How?  Maybe `~/.ssh/config` will give you a hint).  You can now use those 7
users in any way you please in the config file and test out different user's
access simply using a different URL.  For example, `git clone u1:testing` and
`git clone u2:testing` may give you different results depending on what rights
you gave users "u1" and "u2" in your config.

<a name="_testing_gitolite"></a>

### testing gitolite

First, do what the "playing with gitolite" section says.  That is a
pre-requisite.

Once that is done, run this command (still in `$HOME` of the gl-test userid):

    prove gitolite/t/test-driver.sh

(note: to make it work easier with prove, I ended up making the "subtest"
numbers be the actual test numbers, making it look like I have over 2000
tests, when in reality I have about 600)

<a name="_instructions_for_adding_new_tests"></a>

### instructions for adding new tests

(TODO)