Some initial documentation on JUnit Rules samples.

git-svn-id: https://svn.alfresco.com/repos/alfresco-enterprise/alfresco/HEAD/root@34317 c4b6b30b-aa2e-2d43-bbcb-ca4b014f7261

source/java/org/alfresco/util/test/junitrules/AlfrescoPeople.java

@@ -33,6 +33,24 @@ import org.springframework.context.ApplicationContext;
 
 /**
  * This JUnit rule can be used to setup and teardown a set of Alfresco users for test purposes.
+ * <p/>
+ * Example usage:
+ * <pre>
+ * public class YourTestClass
+ * {
+ *     // Normally we would initialise the spring application context in another rule.
+ *     &#64;ClassRule public static final ApplicationContextInit APP_CONTEXT_RULE = new ApplicationContextInit();
+ *     
+ *     // This rule will give us 8 GUID-named users.
+ *     &#64;Rule public final AlfrescoPeople testPeople = new AlfrescoPeople(APP_CONTEXT_RULE, 8);
+ *     
+ *     &#64;Test public void aTestMethod()
+ *     {
+ *         Set&#60;String&#62; userNames = testPeople.getUsernames();
+ *         // etc
+ *     }
+ * }
+ * </pre>
  * 
  * @author Neil Mc Erlean
  * @since Odin

source/java/org/alfresco/util/test/junitrules/AlfrescoPerson.java

@@ -27,8 +27,27 @@ import org.springframework.context.ApplicationContext;
 
 /**
  * This JUnit rule can be used to setup and teardown a single Alfresco user for test purposes.
- * 
- * TODO Sample usage.
+ * <p/>
+ * Example usage:
+ * <pre>
+ * public class YourTestClass
+ * {
+ *     // Normally we would initialise the spring application context in another rule.
+ *     &#64;ClassRule public static final ApplicationContextInit APP_CONTEXT_RULE = new ApplicationContextInit();
+ *     
+ *     // We pass the rule that creates the spring application context.
+ *     // This rule will give us a user with username 'NeilM'.
+ *     &#64;Rule public final AlfrescoPerson namedPerson = new AlfrescoPerson(APP_CONTEXT_RULE, "NeilM");
+ *     // This rule with give us a user with a GUID-generated name.
+ *     &#64;Rule public final AlfrescoPerson guidPerson = new AlfrescoPerson(APP_CONTEXT_RULE);
+ *     
+ *     &#64;Test public void aTestMethod()
+ *     {
+ *         AuthenticationUtil.setFullyAuthenticatedUser(namedPerson.getUsername());
+ *         // etc
+ *     }
+ * }
+ * </pre>
  * 
  * @author Neil Mc Erlean
  * @since Odin

source/java/org/alfresco/util/test/junitrules/ApplicationContextInit.java

@@ -30,8 +30,21 @@ import org.springframework.context.ApplicationContext;
 
 /**
  * This JUnit rule can be used to bring up a {@link ApplicationContext spring application context}.
- * 
- * TODO Sample usage.
+ * <p/>
+ * Example usage:
+ * <pre>
+ * public class YourTestClass
+ * {
+ *     // Parameterless construction brings up the default Alfresco spring configuration.
+ *     &#64;ClassRule public static final ApplicationContextInit APP_CONTEXT_RULE = new ApplicationContextInit();
+ *     private static NodeService NODE_SERVICE;
+ *     
+ *     &#64;BeforeClass public static void initSpringServices() throws Exception
+ *     {
+ *         NODE_SERVICE = (NodeService) APP_CONTEXT_RULE.getApplicationContext().getBean("nodeService");
+ *     }
+ * }
+ * </pre>
  * 
  * @author Neil Mc Erlean
  * @since Odin

source/java/org/alfresco/util/test/junitrules/RunAsFullyAuthenticatedRule.java

@@ -28,6 +28,8 @@ import java.lang.annotation.Target;
 import java.lang.reflect.InvocationTargetException;
 import java.util.Collection;
 
+import junit.framework.Test;
+
 import org.alfresco.repo.security.authentication.AuthenticationUtil;
 import org.alfresco.util.ParameterCheck;
 import org.apache.commons.logging.Log;
@@ -38,8 +40,30 @@ import org.junit.runners.model.Statement;
 
 /**
  * This JUnit rule can be used to make test methods run as a particular user.
- * 
- * TODO Example usage.
+ * A username can be provided on construction to the rule and then all <code>@Test</code> methods will be
+ * run as that user.
+ * <p/>
+ * Furthermore, if an individual test method is annotated like this <code>@RunAsUser(userName="John")</code> than that
+ * method (and only that method) will be run as "John".
+ * <p/>
+ * Example usage:
+ * <pre>
+ * public class YourTestClass
+ * {
+ *     &#64;ClassRule public static final ApplicationContextInit APP_CONTEXT_RULE = new ApplicationContextInit();
+ *     &#64;Rule public RunAsFullyAuthenticatedRule runAsGuidPerson = new RunAsFullyAuthenticatedRule("NeilM");
+ *     
+ *     &#64;Test public void doSomething() throws Exception
+ *     {
+ *         // This will run as NeilM
+ *     }
+ *     
+ *     &#64;Test &#64;RunAsUser(userName="DaveC") public void doSomething() throws Exception
+ *     {
+ *         // This will run as DaveC
+ *     }
+ * }
+ * </pre>
  * 
  * @author Neil Mc Erlean
  * @since Odin