How to run your JUnit 4 tests using the old JUnit 3 GUI runners

Although the usual way for running JUnit tests is inside an IDE like Eclipse or NetBeans, both with an integrated debugger that directly points you to the place where the error is located when a test fails, sometimes can be better a lightweight tool for running your tests.

The popular JUnit testing framework, in its version 3, came with Java-based GUI runners which allowed developers to see the test results in a graphical window instead of having them printed in the text console, so it was nice to run them even without having an IDE.

Instead, the next version of the framework, JUnit 4, didn't come with any GUI runners (for unknown reasons for me, perhaps because the features and API are in constant change or to encourage developers to use IDEs for debugging), so developers not using an IDE now must see the results of their tests in the text console, having to read the large exception's trace output when an error appears, hidding also any other debugging messages added by the developer to catch the bug.

In the first releases of the JUnit 4 series, the JUnit team developed a backwards compatibility feature for allowing the JUnit 4 tests to be run with a JUnit 3 runner, so certain older applications having such a runner could run JUnit 4 test classes just adding to them the following method (changing the SimpleTest.class to the file name in which the code is pasted):

public static junit.framework.Test suite() {
    return new junit.framework.JUnit4TestAdapter(SimpleTest.class);
}

For achieving this the JUnit 4 framework provides some code under the old junit.framework package (although the new version uses the new org.junit package to allow coexistence), so the code showed before can be compiled with the JUnit 4 framework and also be able to run in a JUnit 3 runner needing to call the suite() method.

Recently, however, it seems that support for this hack has been reduced as more applications are ported to the new framework version, so you cannot find the JavaDoc documentation of this package in the latest JavaDoc JUnit 4 API link from JUnit main page, but only in the outdated previous version of the JUnit 4 API. Also, if you download the last JUnit 3 version from the old JUnit hosting site at SourceForge, the old GUI runners seem not to run properly, perhaps because of the problem of having both junit.framework versions of the package.

After many days searching around this, I discovered that the people from JUnit 4 Extensions have been maintaining the isolated GUI runners of JUnit 3, so they can coexists with the JUnit 4 packages without problem. By adding their prebuilt junit-ui-runners-3.8.2.jar file to your CLASSPATH environment variable you will be able to run any individual JUnit 4 modified test class in the old Swing GUI runner of JUnit 3 introducing the following command (changing the SimpleTest name to the name of the class test that you want to run):

java junit.swingui.TestRunner SimpleTest

Keep in mind that this is a temporary solution, because JUnit 4 will not support this for a long time (although having a simple standalone GUI runner for JUnit 4 would be much better). Until then, when all those suite() methods will be removed, we can keep using this alternative. Happy testing!