Split up the user yarn a little

1 files changed, 49 insertions, 7 deletions

diff --git a/testing/02-commands-user.yarn b/testing/02-commands-user.yarn
index 9ff95c4..54f402b 100644
--- a/testing/02-commands-user.yarn
+++ b/testing/02-commands-user.yarn
@@ -1,6 +1,16 @@
 <!-- -*- markdown -*- -->
 
-    SCENARIO user management
+Users
+=====
+
+A core concept in Gitano is that of users.  Users have usernames, real names,
+email addresses, ssh keys, and membership of groups.  All this can be
+administered via the `user` command which is convenient and delegable.
+
+Creating users
+==============
+
+    SCENARIO user creation
 
     GIVEN a standard instance
       AND testinstance, using adminkey, adds a new user alice, with a key called main
@@ -16,8 +26,19 @@ Privileged users may create other users though.
      AND testinstance adminkey runs user list
     THEN stdout contains ^bob
 
+    FINALLY the instance is torn down
+
+Manipulating user information
+=============================
+
+    SCENARIO user manipulation
+
+    GIVEN a standard instance
+
 The e-mail address and real name provided in the create command are also listed.
 
+    WHEN testinstance adminkey runs user add bob bob@testinstance Bob Bobertson
+     AND testinstance adminkey runs user list
     THEN stdout contains ^bob.*bob@testinstance
      AND stdout contains ^bob.*Bob Bobertson
 
@@ -34,22 +55,43 @@ A user's real name may also be changed.
      AND testinstance adminkey runs user list
     THEN stdout contains ^bob.*Robert Robertson
 
-Privileged users may also rename other users.
+    FINALLY the instance is torn down
 
-    WHEN testinstance adminkey runs user rename bob robert --force
+Renaming users
+==============
+
+Since usernames can be used in rules, it's not something one might do lightly,
+but it is possible to rename users.
+
+    SCENARIO rename user
+    GIVEN a standard instance
+
+    WHEN testinstance adminkey runs user add bob bob@testinstance Bob Bobertson
+     AND testinstance adminkey runs user rename bob robert --force
     THEN the output contains SSH authorised key file updated
      AND the output contains Committed: Rename user bob to robert
     WHEN testinstance adminkey runs user list
     THEN stdout contains ^robert
     THEN stdout does not contain ^bob
 
-Privileged users may delete other users.
+    FINALLY the instance is torn down
 
-    WHEN testinstance adminkey runs user del robert --force
+Deleting users
+==============
+
+Removing users from the system is sometimes necessary.  If the user is removed
+then they cannot authenticate and thus cannot do anything they were previously
+able to do which an anonymous user cannot.
+
+    SCENARIO delete user
+    GIVEN a standard instance
+
+    WHEN testinstance adminkey runs user add robert bob@testinstance Bob Bobertson
+     AND testinstance adminkey runs user del robert --force
     THEN the output contains SSH authorised key file updated
-    THEN the output contains Committed: Delete user robert
+     AND the output contains Committed: Delete user robert
     WHEN testinstance adminkey runs user list
-    THEN stdout does not contain ^bob
+    THEN stdout does not contain ^robert
 
     FINALLY the instance is torn down