Johannes Link

How to Use It

The mechanism is simple. Just create a new project in Eclipse and add all projects that contain tests you want to run to its build path. Now create a class like that:

import org.junit.extensions.cpsuite.ClasspathSuite;
import org.junit.runner.RunWith;
@RunWith(ClasspathSuite.class)
public class MySuite {}

This will execute all JUnit4 testclasses (those containing methods with the @Test annotation) in the projects classpath.

JAR Files

By default jar files are being ignored but you can include them in the search for tests by adding another annotation:

import org.junit.extensions.cpsuite.ClasspathSuite.*;
...
@IncludeJars(true)
public class MySuite...

Filtering

And you don't have to run all tests. Instead you can use another annotation to restrict the tests to run by regex expressions which will be applied onto the class name before adding a test class to the suite:

import org.junit.extensions.cpsuite.ClasspathSuite.*;
...
@ClassnameFilters({"mytests.*", ".*Test"})
public class MySuite...

The filter patterns work disjunctively; if any one filter matches, the class will be added to the suite of tests.

Negation Filters

Excluding tests from the test suite can be done by regular expressions but that is very cumbersome to write and read. Therefore I added the feature to have filters that specify a regular expression to exclude certain tests:

@ClassnameFilters({"mytests.*", "!.*AllTests"})

Negation expressions are preceded by a "!". In the previous example all tests that match "mytests.*" will be run except those matching ".*AllTests".

You can have as many positive and negative filters as you like. The positve filters still work disjunctively whereas the negated filters will subtract all matching tests after the maximum set of tests to run has been determined. Having only negated filters starts with the full set of tests.

Abstract Test Classes

ClasspathSuite solves another problem (bug?) in the JUnit 4 integration of Eclipse 3.2: test classes derived from an abstract test class which do not have test methods of their own are being ignored by Eclipse's test runner. When using RunWith(ClasspathSuite.class) you will catch those test classes as well.

Running other RunWith-Suites

So far you would only run "normal" test classes. What about including other test suites that use JUnit's RunWith-Feature? Since version 0.9.5 ClasspathSuites has another annotation in its bag that helps you around that problem: @SuiteTypes(...). Look at the following example:

import org.junit.extensions.cpsuite.ClasspathSuite.*;
import static org.junit.extensions.cpsuite.SuiteType.*;
...
@RunWith(ClasspathSuite.class)
@SuiteTypes(RUN_WITH_CLASSES)
public class AllRunWithSuites {}

This class will execute all test suites in the class path, i.e. classes using the @RunWith annotation. Normal test classes will not be run - unless they are in one of the test suites. If you want both test suites and test class being run use the following expression instead :

@SuiteTypes({RUN_WITH_CLASSES, TEST_CLASSES})

Filtering works the same way it does without the @SuiteTypes annotation (see above).

Running JUnit 3.8 style tests

Since version 1.1.0 ClasspathSuite can also be used to run tests in JUnit 3.8 style, using test classes that are derived from junit.org.TestCase. This feature is disabled by default and you have to tell ClasspathSuite that you want to consider JUnit 3.8 test cases as well:

import org.junit.extensions.cpsuite.ClasspathSuite.*;
import static org.junit.extensions.cpsuite.SuiteType.*;
...
@RunWith(ClasspathSuite.class)
@SuiteTypes(JUNIT38_TEST_CLASSES)
public class AllJUnit38Tests {}

If you want to you can combine JUnit4 and JUnit38 style by specifying more than one suite type, e.g. by using "@SuiteTypes({ JUNIT38_TEST_CLASSES, TEST_CLASSES })". Of course, filtering works here as well.

Open Issues

• You cannot use RUN_WITH_CLASSES to collect other suites that use @RunWith(ClasspathSuite.class). Those will boldly be ignored to circumvent JUnit4's problems with circular test suites. In other words: only the top level suite can use ClasspathSuite.class as argument in @RunWith(..).
  Note: The circular test suite problem has been solved by JUnit 4.3 but as long as it's not the predominant version I will stick to the current approach.
• ClasspathSuite does currently not work with Plugin-Tests (PDE Test). I'm looking into ways to resolve this.

Release Notes

Version 1.1.0 2008-01-18

• Added support for JUnit 3.8 style tests. Thanks to Jeanne Boyarsky for suggesting the feature and providing implementation hints.
• Added support for JUnit 4.4.1. Thanks to Jeanne Boyarsky for providing the code fix.

Version 1.0.0 2007-05-17

• Added negation filters which were suggested by Jason Hitt.
• Additionally tested with JUnit 4.3.1.

Version 0.9.6 2007-02-01

• Fixed a bug that occurred when an empty directory in the classpath contained itself another empty directory. Thanx to David Saff who pointed that out and sent a test revealing the bug.

Version 0.9.5 2006-12-21

• Added the functionality to run other tests suites that use the RunWith attribute as well. See @SuiteTypes.
• Tested with JUnit 4.1 and 4.2.
• Added more documentation to this website.

Version 0.9.1 2006-11-15

• Added GPL license information to all files.