Some notes in the library.yarn

1 files changed, 31 insertions, 20 deletions

diff --git a/testing/library.yarn b/testing/library.yarn
index 7d72ffb..2ce4436 100644
--- a/testing/library.yarn
+++ b/testing/library.yarn
@@ -14,9 +14,32 @@ be called `testinstance` and the keyset which they get to use in order to
 access the repository will be called `adminkey`.  This is important when it
 comes to cloning, pushing, etc.
 
+General instance management
+---------------------------
+
+    IMPLEMENTS GIVEN a standard instance
+    $GTT createunixuser testinstance
+    $GTT createsshkey testinstance adminkey
+    $GTT createsshkey testinstance bypasskey
+    $GTT setupstandard testinstance adminkey bypasskey
+    if [ "$GTT_PROTO" = http ]; then
+        printf "%s" admin | GTT_PROTO=ssh $GTT runcommand \
+            testinstance adminkey as admin passwd \
+            >> $DATADIR/stdout 2>> $DATADIR/stderr
+        printf "%s" gitano-bypass | GTT_PROTO=ssh $GTT runcommand \
+            testinstance bypasskey as gitano-bypass passwd \
+            >> $DATADIR/stdout 2>> $DATADIR/stderr
+    fi
+
+    IMPLEMENTS FINALLY the instance is torn down
+    $GTT teardownstandard
+
 Managing the fake unix users
 ----------------------------
 
+The `gitano-test-tool` utility helps us manage fake UNIX users and give them
+SSH keys.  Sometimes it's helpful to be able to work with these...
+
     IMPLEMENTS GIVEN a unix user called ([a-z][a-z0-9]*)
     $GTT createunixuser $MATCH_1
 
@@ -26,6 +49,10 @@ Managing the fake unix users
     IMPLEMENTS WHEN ([a-z][a-z0-9]*) uses their ssh public key called ([a-z][a-z0-9]*) as stdin
     cp "$DATADIR/user-home-$MATCH_1/.ssh/$MATCH_2.pub" "$DATADIR/stdin"
 
+A lot of tests need a user which isn't `gitano-admin` to work with, this GIVEN
+rolls up the creation of a unix user, allocation of an SSH key, and creation
+of the user inside Gitano.
+
     IMPLEMENTS GIVEN ([a-z][a-z0-9]*),? using ([a-z][a-z0-9_-]*),? adds a new user ([a-z][a-z0-9_-]*), with a key called ([a-z][a-z0-9_-]*)
     $GTT createunixuser $MATCH_3
     $GTT createsshkey $MATCH_3 $MATCH_4
@@ -41,26 +68,6 @@ Managing the fake unix users
     fi
 
 
-General instance management
----------------------------
-
-    IMPLEMENTS GIVEN a standard instance
-    $GTT createunixuser testinstance
-    $GTT createsshkey testinstance adminkey
-    $GTT createsshkey testinstance bypasskey
-    $GTT setupstandard testinstance adminkey bypasskey
-    if [ "$GTT_PROTO" = http ]; then
-        printf "%s" admin | GTT_PROTO=ssh $GTT runcommand \
-            testinstance adminkey as admin passwd \
-            >> $DATADIR/stdout 2>> $DATADIR/stderr
-        printf "%s" gitano-bypass | GTT_PROTO=ssh $GTT runcommand \
-            testinstance bypasskey as gitano-bypass passwd \
-            >> $DATADIR/stdout 2>> $DATADIR/stderr
-    fi
-
-    IMPLEMENTS FINALLY the instance is torn down
-    $GTT teardownstandard
-
 Repository access
 -----------------
 
@@ -246,5 +253,9 @@ Generic utility methods
 GPG Keyring related helpers
 ---------------------------
 
+Since the test suite runs with a `GNUPG_HOME` set up for us which the test tool
+can access, these implementations use that `GNUPG_HOME` rather than one inside
+`DATADIR`.
+
     IMPLEMENTS GIVEN gpg key ([0-9A-Fa-f]+) on stdin
     $GTT gpg --armor --export $MATCH_1 > $DATADIR/stdin