JUnit Test Timeout – JUnit 5 Timeout Example

Learn to write JUnit tests with timeout behavior. If any test does not complete execution in given time limit then it’s execution will stop by JUnit. Also learn to use JUnit 5 test timeout using assertions.

1. Why to write JUnit timeout tests?

Sometimes, we have to write JUnit tests where we have to access some external systems on network. This is never 100% certainty that these external systems will be available while executing the test cases. That’s why it is advisable to use timeout property of JUnit framework while writing test cases with external dependencies.

This is also considered JUnit best practice to be followed.

Each JUnit test is run in a new thread. If the specified timeout elapses before the test completes, its execution is interrupted via Thread.interrupt().

2. JUnit test timeout example – ‘timeout’ attribute

To specify timeout period of a certain test case, “timeout” attribute is mentioned on annotation @Test. For example, @Test(timeout = 1000).

Timeout time is specified in milliseconds.

@Test(timeout = 500)
public void testInfiniteTametakingLoop() throws InterruptedException 
{
	while (true)
	{
		Thread.currentThread().sleep(1000);
	}
}

In above test, execution will timeout after 5 seconds with below message.

java.lang.Exception: test timed out after 5000 milliseconds

2. JUnit global timeout example – Timeout Rule

Rather than specifying timeout attribute for all tests separately, we can define JUnit Rule for all tests in a class.

@Rule
public Timeout globalTimeout = Timeout.seconds(2);

@Test 	//Pass
public void testInfiniteTametakingLoop1() throws InterruptedException 
{
	while (true)
	{
		Thread.currentThread().sleep(1000);
	}
}

@Test 	//Fail
public void testInfiniteTametakingLoop2() throws InterruptedException 
{
	while (true)
	{
		Thread.currentThread().sleep(5000);
	}
}

In above example, first test will pass while second test will fail.

4. JUnit 5 timeout using assertion

In JUnit 5, we can force timeout of tests using assertions.

import static java.time.Duration.ofMillis;
import static java.time.Duration.ofMinutes;
import static org.junit.jupiter.api.Assertions.assertTimeout;

@Test
void timeoutNotExceeded() 
{
    //The following assertion succeeds.
    assertTimeout(ofMinutes(2), () -> {
        // Perform task that takes less than 2 minutes.
    });
}

@Test
void timeoutExceeded() 
{
    // The following assertion fails with an error message similar to:
    // execution exceeded timeout of 10 ms by 91 ms
    assertTimeout(ofMillis(10), () -> {
        // Simulate task that takes more than 10 ms.
        Thread.sleep(100);
    });
}

Happy Learning !!