JUnit 4 Documentation

JUnit 4 is a simple framework for writing repeatable tests, based on the xUnit architecture for unit testing frameworks.

Note: JUnit 4 is in maintenance mode. Only critical bugs and security issues are addressed. For active development and new features, use the junit-framework repository instead.

In JUnit 4.5, you can annotate test classes or individual test methods with @Category to group them. This allows you to run specific subsets of tests (e.g., only UI tests or only integration tests).

To run tests belonging to a specific category, you must create a custom Request using JUnitCore.

public static class SomeUITests {
    @Category(UserAvailable.class)
    @Test
    public void askUserToPressAKey() { }
    
    @Test
    public void simulatePressingKey() { }
}
    
@Category(InternetConnected.class)
public static class InternetTests {
    @Test
    public void pingServer() { }
}

// To run only UserAvailable tests:
new JUnitCore().run(Request.aClass(SomeUITests.class).inCategories(UserAvailable.class));

To build the JUnit project from the source code, you must have Maven installed. After cloning the repository and navigating to the project root, you can clean the previous build, build the project, and install the new artifacts into your local repository (~/.m2/repository) using the clean install goal.

Ensure you set the M2_HOME and PATH environment variables if you plan to build frequently via the command line.

In JUnit 4.13.2, the Timeout rule only creates a new ThreadGroup if lookForStuckThread(true) is explicitly called via the builder. If your tests rely on the behavior introduced in JUnit 4.12 where a new ThreadGroup was always created (which may be necessary for tests interacting with java.beans.ThreadGroupContext), you must use the Timeout.Builder to enable this feature.

To restore the JUnit 4.12 behavior in version 4.13.2, use Timeout.Builder.lookForStuckThread(true).

To write a basic test in JUnit 4:

1. Annotate a method with @org.junit.Test.
2. Use org.junit.Assert.* (specifically assertTrue()) to verify results by passing a boolean expression that evaluates to true if the test succeeds.

@Test
public void simpleAdd() {
    Money m12CHF= new Money(12, "CHF");
    Money m14CHF= new Money(14, "CHF");
    Money expected= new Money(26, "CHF");
    Money result= m12CHF.add(m14CHF);
    assertTrue(expected.equals(result));
}

When using Maven, you should use the junit:junit artifact.

Previously, junit:junit-dep was used to avoid including Hamcrest classes in the artifact, but junit:junit is now the standard. If you still reference junit:junit-dep, Maven will automatically relocate you to junit:junit and issue a warning.

By default, the TemporaryFolder rule does not fail a test if some temporary resources cannot be deleted. You can enable strict verification by using the TemporaryFolder.builder() method with the assureDeletion() parameter. If enabled, an AssertionError will be thrown if resource deletion fails.

@Rule public TemporaryFolder folder = TemporaryFolder.builder().assureDeletion().build();

For detailed information on using JUnit 4, refer to the following resources:

• Wiki: General project information.
• Download and Install guide: Instructions for obtaining and setting up the framework.
• Getting Started: Initial steps to begin writing tests.

You can run tests and view results on the console using org.junit.runner.JUnitCore.

From a Java program:

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

From the command line (ensure both your test class and JUnit are on the classpath):

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

Compatibility with older TestRunners: To make JUnit 4 test classes accessible to TestRunners designed for earlier versions, declare a static suite() method that returns a junit.framework.Test using a JUnit4TestAdapter.

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

To generate the sources.jar and javadoc.jar during the Maven build process, use the generate-docs profile.

mvn -Pgenerate-docs install