org.junit
Annotation Type Test

@Retention(value=RUNTIME)
@Target(value=METHOD)
public @interface Test

The Test annotation tells JUnit that the public void method to which it is attached can be run as a test case. To run the method, JUnit first constructs a fresh instance of the class then invokes the annotated method. Any exceptions thrown by the test will be reported by JUnit as a failure. If no exceptions are thrown, the test is assumed to have succeeded.

A simple test looks like this:

 public class Example {
    @Test
    public void method() {
       org.junit.Assert.assertTrue( new ArrayList().isEmpty() );
    }
 }
 

The Test annotation supports two optional parameters for exception testing and for limiting test execution time.

Exception Testing

The parameter expected declares that a test method should throw an exception. If it doesn't throw an exception or if it throws a different exception than the one declared, the test fails. For example, the following test succeeds:

    @Test(expected=IndexOutOfBoundsException.class)
    public void outOfBounds() {
       new ArrayList<Object>().get(1);
    }
 

Using the parameter expected for exception testing comes with some limitations: only the exception's type can be checked and it is not possible to precisely specify the code that throws the exception. Therefore JUnit 4 has improved its support for exception testing with Assert.assertThrows(Class, ThrowingRunnable) and the ExpectedException rule. With assertThrows the code that throws the exception can be precisely specified. If the exception's message or one of its properties should be verified, the ExpectedException rule can be used. Further information about exception testing can be found at the JUnit Wiki.

Timeout

The parameter timeout causes a test to fail if it takes longer than a specified amount of clock time (measured in milliseconds). The following test fails:

    @Test(timeout=100)
    public void infinity() {
       while(true);
    }
 

Warning: while timeout is useful to catch and terminate infinite loops, it should not be considered deterministic. The following test may or may not fail depending on how the operating system schedules threads:

    @Test(timeout=100)
    public void sleep100() {
       Thread.sleep(100);
    }
 

THREAD SAFETY WARNING: Test methods with a timeout parameter are run in a thread other than the thread which runs the fixture's @Before and @After methods. This may yield different behavior for code that is not thread safe when compared to the same test method without a timeout parameter. Consider using the Timeout rule instead, which ensures a test method is run on the same thread as the fixture's @Before and @After methods.

Since:

4.0

Optional Element Summary

Class<? extends Throwable>	expected Optionally specify expected, a Throwable, to cause a test method to succeed if and only if an exception of the specified class is thrown by the method.
long	timeout Optionally specify timeout in milliseconds to cause a test method to fail if it takes longer than that number of milliseconds.

expected

public abstract Class<? extends Throwable> expected

Optionally specify expected, a Throwable, to cause a test method to succeed if and only if an exception of the specified class is thrown by the method. If the Throwable's message or one of its properties should be verified, the ExpectedException rule can be used instead.

Default:

org.junit.Test.None.class

timeout

public abstract long timeout

Optionally specify timeout in milliseconds to cause a test method to fail if it takes longer than that number of milliseconds.

THREAD SAFETY WARNING: Test methods with a timeout parameter are run in a thread other than the thread which runs the fixture's @Before and @After methods. This may yield different behavior for code that is not thread safe when compared to the same test method without a timeout parameter. Consider using the Timeout rule instead, which ensures a test method is run on the same thread as the fixture's @Before and @After methods.

Default:

0L