Test runners

IDE support - graphical runners

NetBeans, Eclipse and IntelliJ IDEA have native graphical test runners built in.

Console based Test runner

JUnit provides tools to define the suite to be run and to display its results. To run tests and see the results on the console, run this from a Java program:

    org.junit.runner.JUnitCore.runClasses(TestClass1.class, ...);

or this from the command line, with both your test class and junit on the classpath:

    java org.junit.runner.JUnitCore TestClass1 [...other test classes...]

This usage is documented further here: http://junit.org/javadoc/latest/org/junit/runner/JUnitCore.html

Using older runners with Adapter

JUnit4TestAdapter enables running JUnit-4-style tests using a JUnit-3-style test runner. To use it, add the following to a test class:

      public static Test suite() {
            return new JUnit4TestAdapter('YourJUnit4TestClass'.class);
      }

Caveat: See #1189 for issues with including a JUnit-4-style suite that contains a JUnit-3-style suite.

@RunWith annotation

When a class is annotated with @RunWith or extends a class annotated with @RunWith, JUnit will invoke the class it references to run the tests in that class instead of the runner built into JUnit.

• JavaDoc for @RunWith http://junit.org/javadoc/latest/org/junit/runner/RunWith.html
• The default runner is BlockJUnit4ClassRunner which supersedes the older JUnit4ClassRunner
• Annotating a class with @RunWith(JUnit4.class) will always invoke the default JUnit 4 runner in the current version of JUnit, this class aliases the current default JUnit 4 class runner.

Specialized Runners

Suite

• Suite is a standard runner that allows you to manually build a suite containing tests from many classes.
• More information at Aggregating tests in Suites page.
• JavaDoc: http://junit.org/javadoc/latest/org/junit/runners/Suite.html

Parameterized

• Parameterized is a standard runner that implements parameterized tests. When running a parameterized test class, instances are created for the cross-product of the test methods and the test data elements.
• More information at Parameterized Tests page.
• JavaDoc: http://junit.org/javadoc/latest/org/junit/runners/Parameterized.html

Categories

You can specify groups of tests to be excluded or included by using the Categories runner. Once you have annotated certain methods with @Category(MyCategory.class), you can use the --filter option to restrict which tests will be run:

java org.junit.runner.JUnitCore --filter=org.junit.experimental.categories.IncludeCategories=MyCat1,MyCat2 --filter=org.junit.experimental.categories.ExcludeCategories=MyCat3,MyCat4

You may filter tests according to any instance of FilterFactory. The --filter option takes the general form:

java [Runner] --filter=[FilterFactory]=[Categories,]

• Categories is a standard runner enabling subsets of tests tagged with certain categories to execute/be excluded from a given test run.
• More information at Categories page.

Experimental Runners

Enclosed

• Enclosed - If you put tests in inner classes, Ant, for example, won't find them. By running the outer class with Enclosed, the tests in the inner classes will be run. You might put tests in inner classes to group them for convenience or to share constants.
• JavaDoc: http://junit.org/javadoc/latest/org/junit/experimental/runners/Enclosed.html
• Working Example of use on the 'Enclosed'-test-runner-example page

Third Party Runners

Some popular third party implementations of runners for use with @RunWith include:

• SpringJUnit4ClassRunner
• MockitoJUnitRunner
• HierarchicalContextRunner
• Avh4's Nested
• NitorCreation's NestedRunner
• Others...