Timeout annotations in JUnit - Build an Automation Script

Verify that a test method fails if it exceeds the specified timeout

Preconditions (2)

Step 1: Annotate the test method with @Timeout(2) to set a 2-second timeout

Step 2: Inside the test method, add a delay of 3 seconds using Thread.sleep(3000)

Step 3: Run the test method

Step 4: Observe the test result

✅ Expected Result: The test fails due to exceeding the 2-second timeout

Automation Requirements - JUnit 5

Assertions Needed:

Verify that the test fails when execution time exceeds the timeout

Best Practices:

Use @Timeout annotation on test methods

Avoid using Thread.sleep in production code; only for testing delays

Keep timeout values reasonable to avoid flaky tests

Automated Solution

JUnit

import org.junit.jupiter.api.Test;
import org.junit.jupiter.api.Timeout;
import java.util.concurrent.TimeUnit;

public class TimeoutTest {

    @Test
    @Timeout(value = 2, unit = TimeUnit.SECONDS)
    void testTimeoutExceeded() throws InterruptedException {
        // Simulate long running task
        Thread.sleep(3000); // 3 seconds sleep
    }
}

The test method testTimeoutExceeded is annotated with @Timeout(2 seconds). This means JUnit will fail the test if it runs longer than 2 seconds.

Inside the test, Thread.sleep(3000) pauses execution for 3 seconds, which exceeds the timeout.

When running this test, JUnit detects the timeout breach and fails the test automatically.

This example shows how to use the @Timeout annotation to prevent tests from running too long.

Common Mistakes - 3 Pitfalls

{'mistake': 'Not specifying the time unit in @Timeout annotation', 'why_bad': 'JUnit defaults to seconds, but this can cause confusion or errors if the developer expects milliseconds', 'correct_approach': "Always specify the time unit explicitly using the 'unit' parameter, e.g., @Timeout(value = 2, unit = TimeUnit.SECONDS)"}

Using Thread.sleep with a duration shorter than the timeout

Using @Timeout on non-test methods or setup methods

Bonus Challenge

Now add data-driven testing with 3 different timeout values and corresponding sleep durations to verify timeout behavior

Show Hint

Practice

1. What is the main purpose of the @Timeout annotation in JUnit tests?

easy

A. To mark a test as expected to fail

B. To repeat a test multiple times automatically

C. To skip a test during execution

D. To stop a test if it runs longer than a specified time limit

Solution

1. Step 1: Understand the role of @Timeout

   The @Timeout annotation sets a maximum time limit for a test method to run.

2. Step 2: Identify what happens when time limit is exceeded

   If the test runs longer than the specified time, it is stopped and marked as failed.

3. Final Answer:

   To stop a test if it runs longer than a specified time limit -> Option D

4. Quick Check:

   @Timeout stops long tests = A [OK]

Hint: Timeout means stop test if too slow [OK]

Common Mistakes:

• Confusing timeout with repeating tests
• Thinking timeout skips tests
• Assuming timeout marks tests as expected failures

2. Which of the following is the correct way to set a timeout of 5 seconds on a JUnit 5 test method?

easy

A. @Timeout(5)

B. @Timeout(5, SECONDS)

C. @Timeout(value = 5, unit = TimeUnit.SECONDS)

D. @Timeout(value = 5, unit = SECONDS)

Solution

1. Step 1: Recall JUnit 5 @Timeout syntax

   The @Timeout annotation requires a value and a time unit specified as an enum from java.util.concurrent.TimeUnit.

2. Step 2: Match correct syntax

   @Timeout(value = 5, unit = TimeUnit.SECONDS) uses named parameters with value=5 and unit=TimeUnit.SECONDS, which is correct syntax.

3. Final Answer:

   @Timeout(value = 5, unit = TimeUnit.SECONDS) -> Option C

4. Quick Check:

   Use named params with TimeUnit enum = C [OK]

Hint: Use named params and TimeUnit enum for timeout [OK]

Common Mistakes:

• Omitting the time unit
• Using wrong enum or missing TimeUnit prefix
• Passing timeout as single unnamed parameter

3. Consider this JUnit 5 test method:

@Test
@Timeout(value = 2, unit = TimeUnit.SECONDS)
void testSleep() throws InterruptedException {
    Thread.sleep(3000);
}

What will happen when this test runs?

medium

A. The test will fail due to timeout after 2 seconds

B. The test will pass after sleeping 3 seconds

C. The test will fail immediately with an exception

D. The test will be skipped because of timeout

Solution

1. Step 1: Analyze the timeout and sleep duration

   The test has a timeout of 2 seconds but sleeps for 3 seconds, which is longer than allowed.

2. Step 2: Understand test behavior on timeout

   JUnit will stop the test after 2 seconds and mark it as failed due to timeout.

3. Final Answer:

   The test will fail due to timeout after 2 seconds -> Option A

4. Quick Check:

   Sleep longer than timeout causes failure = B [OK]

Hint: Sleep longer than timeout causes fail [OK]

Common Mistakes:

• Thinking test passes despite long sleep
• Assuming test fails immediately without waiting
• Believing test is skipped instead of failed

4. This JUnit 5 test uses @Timeout(1) but does not compile. What is the error?

@Test
@Timeout(1)
void testMethod() {
    // test code
}

medium

A. Missing import for @Timeout annotation

B. Timeout annotation requires a time unit parameter

C. Timeout value must be a string, not an integer

D. Timeout annotation cannot be used on void methods

Solution

1. Step 1: Check @Timeout annotation parameters

   The @Timeout annotation requires both a value and a time unit parameter in JUnit 5.

2. Step 2: Identify missing time unit

   Using @Timeout(1) without specifying the time unit causes a compilation error.

3. Final Answer:

   Timeout annotation requires a time unit parameter -> Option B

4. Quick Check:

   Missing time unit parameter = A [OK]

Hint: Specify time unit with @Timeout [OK]

Common Mistakes:

• Forgetting to specify time unit
• Using @Timeout without time unit
• Thinking @Timeout only works on non-void methods

5. You want to apply a timeout of 500 milliseconds to all test methods in a JUnit 5 test class. Which is the best way to do this?

hard

A. Add @Timeout(value = 500, unit = TimeUnit.MILLISECONDS) on the test class

B. Use Thread.sleep(500) in each test method

C. Set a global timeout property in the JUnit configuration file

D. Add @Timeout(value = 500, unit = TimeUnit.MILLISECONDS) on each test method

Solution

1. Step 1: Understand class-level @Timeout usage

   JUnit 5 allows applying @Timeout at the class level to set a timeout for all test methods inside.

2. Step 2: Compare options for efficiency

   Adding @Timeout on the class is simpler and ensures all tests have the timeout without repeating annotation.

3. Final Answer:

   Add @Timeout(value = 500, unit = TimeUnit.MILLISECONDS) on the test class -> Option A

4. Quick Check:

   Class-level @Timeout applies to all tests = D [OK]

Hint: Put @Timeout on class to affect all tests [OK]

Common Mistakes:

• Adding @Timeout repeatedly on each method
• Trying to set timeout via sleep calls
• Assuming global config sets timeout automatically