JUnit rules!

Apologies for the shouty title, I couldn’t stop myself. In JUnit 4.7 a new feature was introduced – rules. They enable us to modify how test methods are executed to provide more flexible and powerful tests. I think the name was chosen so that people would have to search for “junit rules” and google trends seem to (weakly) support this theory. In your face TestNG!

Google Trends for “junit rules” search term

The functionality is implemented by annotating a field (of class TestRule or MethodRule) with the @Rule annotation.

This is a quick tour of the most useful rules.

What’s your name again?

Would you like to know your test method’s name while executing it? Simple, use TestName.

public TestName name = new TestName();

public void printTestMethodName() {
        "Test method name: " + name.getMethodName());
Test method name: printTestMethodName

We want quick tests!

Quick as in “not slow”. Let’s say you need to deal with a class full of badly written integration tests, each of which unnecessarily taking several seconds to run. Bad bad panda. You can set up a timeout (Timeout) in your test class which will fail lengthy tests (just note you’re dealing with milliseconds). Another good thing is that it will actually interrupt the test execution thread so your test method will be time-boxed by the timeout.

public Timeout timeout = new Timeout(20);

public void slowTestAskingForTrouble() throws InterruptedException {
    Thread.sleep(1000 * 60);
java.lang.Exception: test timed out after 20 milliseconds

Exceptions expected

Sometimes you want to check if an exception is thrown. You can do it without the rules but then you can’t check for the message.

@Test(expected = IllegalArgumentException.class)
public void exceptionExpected(){
    throw new IllegalArgumentException("catch me if you can");

Exception messages are important. Sometimes they can tell the whole story, i.e. would you prefer to simply catch UserNotFoundException or would you also like to see the message “Can not load user with id ‘null'” in the production log? Right, let’s check for the exception message with ExpectedException.

public ExpectedException thrown = ExpectedException.none();

public void exceptionWithMessageExpected(){
    thrown.expectMessage("catch me if you can");
    throw new IllegalArgumentException("catch me if you can");

This rule is initialised with ExpectedException.none() as by default we don’t expect methods to end up with an exception. We state this behaviour as per method basis.

Note that you can use Timeout and ExpectedException together and have a passing test

public void slowTestWithExpectedException()
         throws InterruptedException {
        "test timed out after 20 milliseconds");
    Thread.sleep(1000 * 60);

Collect your errors (all of them)

Sometimes you end up having several assertions to verify that the returned object is ok. Let’s say you load a user object and the first assertion is for user’s first name and it fails. Fix it, run again to discover that the date of birth assertion fails too. Repeat to discover that their work phone number is empty (who uses these anyway?)… Wouldn’t it be nice to find out all failing assertions after the first execution? This is when ErrorCollector comes in silver armour and on a white horse to rescue the situation.

public ErrorCollector collector = new ErrorCollector();

public void errorCollectorExample() {
        new Throwable("trouble here"));
        new Throwable("trouble there"));
        new Throwable("trouble everywhere"));
java.lang.Throwable: trouble here
	at com.czeczotka.junit.JUnitRulesTest.errorCollectorExample(JUnitRulesTest.java:52)

java.lang.Throwable: trouble there
	at com.czeczotka.junit.JUnitRulesTest.errorCollectorExample(JUnitRulesTest.java:53)

java.lang.Throwable: trouble everywhere
	at com.czeczotka.junit.JUnitRulesTest.errorCollectorExample(JUnitRulesTest.java:54)

Watch your tests

Should you be interested in being able to get you hands on test’s lifecycle events you can use TestWatcher. It will not let you change the test but you can register callbacks for different events such as failed, finished, skipped, starting, succeeded. Useful for reporting or if you wanted to take some extra actions, i.e. feedback the problem to you continuous delivery pipeline.

private static StringBuilder report = new StringBuilder();

public TestWatcher watcher = new TestWatcher() {
    protected void failed(Throwable e, Description description) {
        report.append("  FAILURE: ").append(

    protected void succeeded(Description description) {
        report.append("  Success: ").append(

public static void tearDownClass() {
    System.out.println("@AfterClass report");
    System.out.println(report.toString ());
@AfterClass report
    Success: exceptionExpected
    Success: printTestMethodName
    FAILURE: errorCollectorExample
    Success: slowTestWithExpectedException
    Success: exceptionWithMessageExpected
    FAILURE: slowTestAskingForTrouble

Other useful stuff

  • TemporaryFolder – enables you to create files and directories (newFile(), newFolder() methods) that will be removed after test execution
  • ExternalResource – useful to access an external resource such as a database or ssh connection (methods before() and after()) but I think I’d prefer to use BeforeClass and AfterClass annotations to do the job
  • Verifier – to potentially fail a test which would otherwise be successful after some extra assertions, i.e.: temporary folder was too big (in conjunction with TemporaryFolder rule)

The code

The code of this post is on github so follow the link below to browse it. Note that it contains failing tests to demonstrate presented ideas.


You can easily clone and play with it locally by simply following these steps.

$ git clone https://github.com/czeczotka/junit-rules.git
$ cd junit-rules
$ mvn test