Translate

Tuesday, November 20, 2012

JUnit Rules

Source: http://www.codeaffine.com/2012/09/24/junit-rules/


JUnit Rules

Monday, September 24th, 2012 by 

The first time I stumbled over a JUnit @Rule annotation I was a bit irritated of the concept. Having a public field in a test case seemed somewhat odd and so I was reluctant to use it regularly. But after a while I got used to that and it turned out that rules can ease writing tests in many ways. This post gives a quick introduction of the concept and some short examples of what rules are good for.

What are JUnit Rules?
Let’s start with a look at a JUnit out-of-the-box rule. The TemporaryFolder is a test helper that can be used to create files and folders located under the file system directory for temporary content1. The interesting thing with the TemporaryFolder is that it guarantees to delete its files and folders when the test method finishes2. To work as expected the temporary folder instance must be assigned to an @Ruleannotated field that must be public, not static, and a subtype of TestRule:
01public class MyTest {
02     
03  @Rule
04  public TemporaryFolder temporaryFolder = new TemporaryFolder();
05
06  @Test
07  public void testRun() throws IOException {
08    assertTrue( temporaryFolder.newFolder().exists() );
09  }
10}
How does it work?
Rules provide a possibility to intercept test method calls similar as an AOP framework would do. Comparable to an around advice in AspectJ you can do useful things before and/or after the actual test execution3. Although this sounds complicated it is quite easy to achieve.
The API part of a rule definition has to implement TestRule. The only method of this interface called apply returns a Statement. Statements represent – simply spoken – your tests within the JUnit runtime and Statement#evaluate() executes them. Now the basic idea is to provide wrapper extensions of Statement that can do the actual contributions by overriding Statement#evaluate():
01public class MyRule implements TestRule {
02
03  @Override
04  public Statement apply( Statement base, Description description ) {
05    return new MyStatement( base );
06  }
07}
08
09public class MyStatement extends Statement {
10
11  private final Statement base;
12
13  public MyStatement( Statement base ) {
14    this.base = base;
15  }
16
17  @Override
18  public void evaluate() throws Throwable {
19    System.out.println( "before" );
20    try {
21      base.evaluate();
22    } finally {
23      System.out.println( "after" );
24    }
25  }
26}
MyStatement is implemented as wrapper that is used inMyRule#apply(Statement,Destination) to wrap the original statement given as argument. It is easy to see that the wrapper overrides Statement#evaluate() to do something before and after the actual evaluation of the test4.
The next snippet shows how MyRule can be used exactly the same way as theTemporaryFolder above:
01public class MyTest {
02
03  @Rule
04  public MyRule myRule = new MyRule();
05     
06  @Test
07  public void testRun() {
08    System.out.println( "during" );
09  }
10}
Launching the test case leads to the following console output which proves that our example rule works as expected. The test execution gets intercepted and modified by our rule to print ‘before’ and ‘after’ around the ‘during’ of the test:
before
during
after
Now that the basics are understood let’s have a look at slightly more useful things you could do with rules.
Test Fixtures
Quoted from the according wikipedia section a test fixture ‘is all the things that must be in place in order to run a test and expect a particular outcome. Frequently fixtures are created by handling setUp() and tearDown() events of the unit testing framework’.
With JUnit this often looks somewhat like this:
01public class MyTest {
02
03  private MyFixture myFixture;
04
05  @Test
06  public void testRun1() {
07    myFixture.configure1();
08    // do some testing here
09  }
10     
11  @Test
12  public void testRun2() {
13    myFixture.configure2();
14    // do some testing here
15  }
16     
17  @Before
18  public void setUp() {
19    myFixture = new MyFixture();
20  }
21
22  @After
23  public void tearDown() {
24    myFixture.dispose();
25  }
26}
Consider you use a particular fixture the way shown above in many of your tests. In that case it could be nice to get rid of the setUp() and tearDown() methods. Given the sections above we now know that this can be done by changing MyFixture to implement TestRule. An appropriate Statement implementation would have to ensure that it calls MyFixture#dispose() and could look like this:
01public class MyFixtureStatement extends Statement {
02
03  private final Statement base;
04  private final MyFixture fixture;
05
06  public MyFixtureStatement( Statement base, MyFixture fixture ) {
07    this.base = base;
08    this.fixture = fixture;
09  }
10
11  @Override
12  public void evaluate() throws Throwable {
13    try {
14      base.evaluate();
15    } finally {
16      fixture.dispose();
17    }
18  }
19}
With this in place the test above can be rewritten as:
01public class MyTest {
02
03  @Rule
04  public MyFixture myFixture = new MyFixture();
05
06  @Test
07  public void testRun1() {
08    myFixture.configure1();
09    // do some testing here
10  }
11     
12  @Test
13  public void testRun2() {
14    myFixture.configure2();
15    // do some testing here
16  }
17}
I come to appreciate the more compact form of writing tests using rules in a lot of cases, but surely this is also a question of taste and what you consider better to read5.
Fixture Configuration with Method Annotations
So far I have silently ignored the Description argument ofTestRule#apply(Statement,Description). In general a Description describes a test which is about to run or has been run. But it also allows access to some reflective information about the underlying java method. Among others it is possible to read the annotations attached to such a method. This enables us to combine rules with method annotations for convenience configuration of a TestRule.
Consider this annotation type:
1@Retention(RetentionPolicy.RUNTIME)
2@Target({ElementType.METHOD})
3public @interface Configuration {
4  String value();
5}
Combined with the following snippet inside MyFixture#apply(Statement,Destination)that reads the configuration value annotated to a certain test method…
1Configuration annotation
2  = description.getAnnotation( Configuration.class );
3String value = annotation.value();
4// do something useful with value
… the test case above that demonstrates the usage of the MyFixture rule can be rewritten to:
01public class MyTest {
02
03  @Rule
04  public MyFixture myFixture = new MyFixture();
05
06  @Test
07  @Configuration( value = "configuration1" )
08  public void testRun1() {
09    // do some testing here
10  }
11     
12  @Test
13  @Configuration( value = "configuration2" )
14  public void testRun2() {
15    // do some testing here
16  }
17}
Of course there are limitations to the latter approach due to the fact that annotations only allow Enums, Classes or String literals as parameters. But there are use cases where this is completely sufficient. A nice example using rules combined with method annotations is provided by the restfuse library. If you are interested in a real world example you should have a look at the library’s implementation of the Destinationrule6.
Comming to the end the only thing left to say is that I would love to hear from you about other useful examples of JUnit rules you might use to ease your daily testing work
  1. The directory which is in general returned by System.getProperty( "java.io.tmpdir" ); ↩
  2. Looking at the implementation of TemporaryFolder I must note that it does not check if the deletion of a file is successful. This might be a weak point in case of open file handles ↩
  3. And for what it’s worth you even could replace the complete test method by something else ↩
  4. The delegation to the wrapped statement is put into a try...finally block to ensure that the functionality after the test gets executed, even if the test would fail. In that case an AssertionError would be thrown and all statements that are not in the finally block would be skipped ↩
  5. You probably noted that the TemporaryFolder example at the beginning is also nothing else but a fixture use case ↩
  6. Note that restfuse’s Destination class implements MethodRule instead of TestRule. This post is based on the latest JUnit version where MethodRule has been marked as@Deprecated. TestRule is the replacement for MethodRule. But given the knowledge of this post it should be nevertheless easily possible to understand the implementation
By at
Labels: , , ,