TestableThread - a Simple Way to Test Multi-Threaded Code

Multi-threaded code is hard to write and hard to test. For years, I have been missing simple tools for testing multi-threaded Java applications. Anyway, for certain types of test situations the TestableThread class can be used. See below and the TestableThread class at the java-cut repo.

The idea is simple. By introducing named "breakpoints" in code run by threads, the test management code can control the execution of a thread by telling it to go to a certain breakpoint. Breakpoints are added to normal code using statements like:

assert TestableThread.breakpoint("breakA");

By using an assert, the breakpoint code will not incur any performance penalty when the software is run in production (the default way to run Java software is without -ea, that is, without enabling assertions).

Given defined breakpoints, test code can let threads execute till they reach a given named breakpoint, for example, the code:

t1.goTo("breakA");

will enable the t1 thread to run until it reaches breakpoint "breakA". When the breakpoint is reached, the t1 thread will stop executing until it gets another goTo() request.


The implementation below is only 50 LOCs or something, but still have been shown to be useful. There are, of course, lots of improvements / additions to be made including conditional breakpoints.

Code:

public class TestableThread extends Thread {

    private final Object sync = new Object();
    private volatile String breakName;
    
    public TestableThread(Runnable r) {
        super(r);
    }
    
    /**
     * Run thread until it hits the named breakpoint or exits.
     */
    public void goTo(String breakName) {
        synchronized (sync) {
            this.breakName = breakName;
            sync.notifyAll();
        }
        
        if (getState() == Thread.State.NEW) {
            start();
        }
    }
    
    /**
     * Run thread, not stopping at any break points.
     */
    public void go() {
        goTo(null);
    }
    
    public static boolean breakpoint(String breakName) {
        if (breakName == null) {
            throw new IllegalArgumentException("breakName == null not allowed");
        }
        
        Thread thread = Thread.currentThread();
        if (thread instanceof TestableThread) {
            TestableThread tt = (TestableThread) thread;
            synchronized (tt.sync) {
                while (tt.breakName != null && tt.breakName.equals(breakName)) {
                    try {
                        tt.sync.wait();
                    } catch (InterruptedException e) {
                        throw new Error("not expected: " + e);
                    }
                }
            }
        }
        
        return true;
    }

 }