Eclipse/Testing/JUnit4 Changes

Introduction

This page describes steps taken to provide support for running JUnit4-style tests within the Eclipse Test Framework (ETF). Included is a brief description of why each of the main changes was made. More information about the development process can be found in the bug report. A few simple steps are required on the part of the user to run tests which require JUnit 4.x. As for JUnit 3.x tests, the Framework is fully backwards compatible.

For the duration of this page, tests which utilize any of the new features provided by JUnit 4.x (annotations, static imports, etc.) will be referred to as "JUnit4 tests". Tests that do not utilize JUnit 4's features will be referred to as "JUnit3 tests".

Changes

JUnit4 Bundle Rename

Because we wanted to retain backwards compatibility of the Framework, having the org.eclipse.test bundle depend on org.junit4 simply wasn't an option. This would mean that users running with a JVM <1.5 would not be able to resolve the org.eclipse.test bundle. So it was decided that by renaming the JUnit4 bundle to "org.junit" (same as the JUnit3 bundle name), the EclipseTestRunner (ETR) could just run with the highest version of org.junit that gets resolved.

By doing a quick version check on the resolved org.junit bundle, ETR determines what type of tests it should be expecting then loads and runs them appropriately.

org.junit4 is now "empty", and simply re-exports the packages exported by the org.junit version 4.x bundle.

JUnit Bundle Configuration

With both the JUnit 3 and 4 bundles both named org.junit, we run into a problem of backwards compatibility. Let's say that our user would like to run his/her tests that depend on org.junit and specify a version less than 4.0.0. This user has also decided to run with a Java 1.5 VM. So now the ETR will attempt to run JUnit 3 tests with the org.junit version 4.x bundle resolved. This shouldn't be a problem as JUnit4 is backwards compatible, except that the user's bundle requires JUnit <4. So we run into an issue of org.junit packages being equal but not identical; ETR is using junit.framework version 4.x but the user's bundle is bound to junit.framework version 3.x. There are two solutions to this: have everyone change their dependencies, or uninstall JUnit4 if a dependency upon JUnit3 is specified. The latter was chosen.

A new bundle, org.eclipse.test.dispatcher was created and now contains the ETF's application classes. When one of the applications is called, the test bundle's dependencies and required bundles are checked. If JUnit 3.x is specified in either, org.junit version 4.x is uninstalled and a refresh is called on the PackageAdmin. Once this is complete, a call is then made to the ETR (which is still in org.eclipse.test) to run the tests. By doing this JUnit bundle configuration before calling the ETR, we avoid having the ETR bind itself to the org.junit 4.x bundle before it can be uninstalled.

Loading Tests

Once the type (JUnit3 vs. JUnit4) of the tests has been determined, a different method of loading them is employed for each type. For JUnit4 tests, the test class is loaded and wrapped in a JUnit4TestAdapter object. In the case of JUnit3 tests, the class is loaded and the test suite method is returned as a TestSuite object. As both JUnit4TestAdapter and TestSuite implement the Test interface's run method, it is invoked and the JUnit framework takes over from there to run the tests.

Steps to Run JUnit4 Tests

1) Run the Eclipse Test Framework with a Java 1.5+ VM

2) Ensure that you specify that your bundle requires org.junit version 4.0.0+, either in the bundle dependencies or required imports.