TestWatcher for reporting in JUnit

Introduction

TestWatcher helps you see what happened during tests. It reports when tests start, succeed, fail, or skip.

You want to log messages when tests pass or fail.

You need to perform actions after each test, like taking a screenshot.

You want to track test results for better reports.

You want to debug why a test failed by adding extra info.

You want to clean up resources after tests based on their result.

Syntax

JUnit

public class MyTestWatcher extends TestWatcher {
    @Override
    protected void succeeded(Description description) {
        // code when test passes
    }

    @Override
    protected void failed(Throwable e, Description description) {
        // code when test fails
    }

    @Override
    protected void starting(Description description) {
        // code when test starts
    }

    @Override
    protected void finished(Description description) {
        // code when test finishes
    }
}

Override only the methods you need.

Use Description to get test method name and class.

Examples

This prints a message when a test passes.

JUnit

public class MyWatcher extends TestWatcher {
    @Override
    protected void succeeded(Description description) {
        System.out.println(description.getMethodName() + " passed");
    }
}

This prints the failure reason when a test fails.

JUnit

public class MyWatcher extends TestWatcher {
    @Override
    protected void failed(Throwable e, Description description) {
        System.out.println(description.getMethodName() + " failed: " + e.getMessage());
    }
}

This shows messages when tests start and finish.

JUnit

public class MyWatcher extends TestWatcher {
    @Override
    protected void starting(Description description) {
        System.out.println("Starting test: " + description.getMethodName());
    }

    @Override
    protected void finished(Description description) {
        System.out.println("Finished test: " + description.getMethodName());
    }
}

Sample Program

This test class uses TestWatcher to print messages for each test event. One test passes, the other fails.

JUnit

import org.junit.Rule;
import static org.junit.Assert.*;
import org.junit.Test;
import org.junit.rules.TestWatcher;
import org.junit.runner.Description;

public class SampleTest {

    @Rule
    public TestWatcher watcher = new TestWatcher() {
        @Override
        protected void starting(Description description) {
            System.out.println("Starting: " + description.getMethodName());
        }

        @Override
        protected void succeeded(Description description) {
            System.out.println("Passed: " + description.getMethodName());
        }

        @Override
        protected void failed(Throwable e, Description description) {
            System.out.println("Failed: " + description.getMethodName() + " - " + e.getMessage());
        }

        @Override
        protected void finished(Description description) {
            System.out.println("Finished: " + description.getMethodName());
        }
    };

    @Test
    public void testSuccess() {
        // This test will pass
        int a = 1 + 1;
        assertEquals(2, a);
    }

    @Test
    public void testFailure() {
        // This test will fail
        int a = 1 + 1;
        assertEquals(3, a);
    }
}

Important Notes

TestWatcher works with JUnit 4 rules.

Use Description methods like getMethodName() to identify tests.

TestWatcher helps add custom logging without changing test code.

Summary

TestWatcher lets you react to test events like start, success, failure, and finish.

It helps add useful reports and logs during test runs.

Override only the methods you need for simple and clear code.