JUnit Rules

[resplin]

Obsolete Pages{{Obsolete}}

The official documentation is at: http://docs.alfresco.com

Table of Contents

• 1 JUnit Rules


• 2 Using Alfresco-provided JUnit Rules
  
  
  
  • 2.1 ApplicationContextInit.java
  
  
  • 2.2 TemporaryNodes.java
  
  
  • 2.3 AlfrescoPerson.java
  
  
  • 2.4 TemporarySites.java
  
  
  • 2.5 LoadTestRule.java
  
  

JUnit Rules

JUnit Rules are a fairly recent addition to the JUnit library. They represent an evolution of the setUp() and tearDown() methods and the more modern @Before and @After annotations. (Note that they have nothing to with Alfresco's own Actions_and_Rules.)

JUnit Rules can be used to do everything that @Before and @After do. They are particularly useful when writing integration tests where you will often need the same boilerplate code to be run for many tests.

They are also significantly more powerful than @Before and @After and can be used to do things that are simply impossible with those annotations.

Using Alfresco-provided JUnit Rules

Since approximately version 4.1 of Alfresco, the source has included a number of Alfresco-specific JUnit Rules. These are available in the Repository project in the package org.alfresco.util.test.junitrules. For up-to-date information on these rules you should refer to the javadoc for those classes, however we will briefly introduce some of them below.

They can all be added to your test code by simply adding a field of the appropriate type and by giving it the JUnit annotation @Rule (for per @Test method rules) or @ClassRule for static per test class rules). Consider this example based on a class in the Alfresco code base:

   public class RatingServiceIntegrationTest
   {
       // Simplified slightly for easier explanation
       @ClassRule public static ApplicationContextInit APP_CONTEXT_INIT = new ApplicationContextInit();
       @Rule public TemporaryNodes testNodes = new TemporaryNodes(APP_CONTEXT_INIT);
       
       @Test public void testOne() {}
       @Test public void testTwo() {}
       // etc.
   }

This example shows a static Rule which initialises the default Spring application context once for the whole test class, followed by a non-static Rule which helps with the management of temporary nodes created within the @Test methods.

Note that unlike @Test, @Before and @After which are applied to methods, JUnit Rules are added to a test class as annotated fields. This has significant advantages as we will see below.

ApplicationContextInit.java

This JUnit rule can be used to initialise the default Alfresco spring application context. It has helper methods that make it easier to include additional contexts as overrides.

TemporaryNodes.java

This JUnit rule can be used to help with the management of temporary nodes created during test execution. It has helper methods createNode() which can be used to create simple content nodes that are typically used in integration testing.

When the Rule finishes, which is after each @Test method for @Rules and after the class for @ClassRules, any nodes which TemporaryNodes is aware of will be deleted. It will do the right thing with various corner cases, including st:site nodes and nodes which have been checked out.

AlfrescoPerson.java

This JUnit Rule can be used to set up and tear down a single Alfresco user for test purposes. If you do not specify a user name, a GUID-based name will be generated for you. Within your test code you will be able to get that test user's username, password and cmerson NodeRef.

This is a very useful rule as it lessens the temptation to run your test as the admin user. It makes it very easy to ensure that a realistic non-admin user is available within your test. You can declare multiple fields of type AlfrescoPerson to get multiple test users.

TemporarySites.java

This JUnit Rule can be used to set up and tear down Alfresco Share Sites for test purposes. There are helper methods to create a simple site or to create a site along with four test users - one for each of the standard Share Roles: SiteManager etc. The Rule ensures that these sites are deleted correctly along with any test users associated with them.

This can be a real boon when you want to write tests which explore how users having different Share roles access data within Alfresco.

LoadTestRule.java

This JUnit Rule should be considered experimental, but it does show the power of JUnit Rules and how they can be used to do things that are simply impossible with @Before and @After.
It can be used to turn almost any existing @Test method into a load test. By adding these fields to your test class

   // A rule to initialise the default Alfresco spring configuration
   public static ApplicationContextInit APP_CONTEXT_INIT = new ApplicationContextInit();
   
   // A rule to create multiple test users.
   public static AlfrescoPeople TEST_USERS = new AlfrescoPeople(APP_CONTEXT_INIT, 10);
   
   // Tie them together in a static Rule Chain - this is needed due to the inter-rule dependency
   @ClassRule public static RuleChain ruleChain = RuleChain.outerRule(APP_CONTEXT_INIT)
                                                           .around(TEST_USERS);
   
   // A rule to turn the test class into a Load Test.
   @Rule public LoadTestRule loadTest = new LoadTestRule(TEST_USERS);

and by adding a marker aspect to each @Test method you want to load

   // A normal test method
   @Test public void testSomething() {}
   
   // A test method with 'loading' enabled
   @LoadTest @Test public void testThisUnderLoad() {}

JUnit will create, in this example, 10 Alfresco users. It will then consider each @Test method in turn. If the method is marked with @LoadTest, it will create and start 10 threads, it will authenticate as one of the 10 test users in each of those threads and it will concurrently execute the current test method in those threads. If all 10 threads successfully complete, that test is passed and you get the green bar.
If one or more of those threads fail (or time out), those errors will be collected together and reported by JUnit as a single failed test with aggregated stack traces and failure messages.
Testing
4.1