The following methods are used to fail a test if the execution of a given code block exceeds a specified duration.

public static void assertTimeout(Duration timeout, Executable executable);
public static void assertTimeout(Duration timeout, Executable executable, String message);
public static void assertTimeout(Duration timeout, Executable executable, Supplier<String> messageSupplier);
public static <T> T assertTimeout(Duration timeout, ThrowingSupplier<T> supplier);
public static <T> T assertTimeout(Duration timeout, ThrowingSupplier<T> supplier, String message);
public static <T> T assertTimeout(Duration timeout, ThrowingSupplier<T> supplier, Supplier<String> messageSupplier);
public static void assertTimeoutPreemptively(Duration timeout, Executable executable);
public static void assertTimeoutPreemptively(Duration timeout, Executable executable, String message);
public static void assertTimeoutPreemptively(Duration timeout, Executable executable, Supplier<String> messageSupplier);
public static <T> T assertTimeoutPreemptively(Duration timeout, ThrowingSupplier<T> supplier);
public static <T> T assertTimeoutPreemptively(Duration timeout, ThrowingSupplier<T> supplier, String message);
public static <T> T assertTimeoutPreemptively(Duration timeout, ThrowingSupplier<T> supplier, Supplier<String> messageSupplier);

assertTimeout(...)
Executes the code in the current thread
Does NOT kill the code if it exceeds the timeout
Test fails after completion if the timeout was exceeded

assertTimeoutPreemptively(...)
Executes the code in a separate thread
Forcefully stops the code when it exceeds the timeout
More strict, but may interfere with thread-local context

Example

package com.logicbig.example;

import org.junit.jupiter.api.Test;

import java.time.Duration;
import static org.junit.jupiter.api.Assertions.*;

class TimeoutTest {

  @Test
  void testWithAssertTimeout() {
      // >> Verifying the code runs within the given time (200 milliseconds)
      assertTimeout(Duration.ofMillis(200), () -> {
          // Simulate some work
          Thread.sleep(100); // Sleep for 100ms
      });
  }

  @Test
  void testMethodReturnsObjectWithinTimeout() {
      // >> Verifying that the code executes within the given time (500 milliseconds)
      String result = assertTimeout(Duration.ofMillis(500), () -> {
          // Simulate some work that returns a value after a delay
          Thread.sleep(200); // Sleep for 200ms
          return "Hello, World!"; // Returning the result after the delay
      });

      // >> Verifying that the returned result is as expected
      assertEquals("Hello, World!", result);
  }

  @Test
  void testMethodReturnsObjectWithinTimeoutPreemptively() {
      // >> Verifying that the method completes within 500 milliseconds
      String result = assertTimeoutPreemptively(Duration.ofMillis(500), () -> {
          // Simulate some work that returns a value after a delay
          Thread.sleep(200); // Simulate a delay of 200ms
          return "Hello, World!"; // Return the result after the delay
      });

      // >> Verifying that the returned result is as expected
      assertEquals("Hello, World!", result);
  }
}

mvn test -Dtest=TimeoutTest

Output

D:\example-projects\junit-5\junit-5-assertions\junit-5-timeout-assertions>mvn test -Dtest=TimeoutTest
[INFO] Scanning for projects...
[INFO] 
[INFO] ----------< com.logicbig.example:junit-5-timeout-assertions >-----------
[INFO] Building junit-5-timeout-assertions 1.0-SNAPSHOT
[INFO]   from pom.xml
[INFO] --------------------------------[ jar ]---------------------------------
[INFO] 
[INFO] --- resources:3.3.1:resources (default-resources) @ junit-5-timeout-assertions ---
[WARNING] Using platform encoding (UTF-8 actually) to copy filtered resources, i.e. build is platform dependent!
[INFO] skip non existing resourceDirectory D:\example-projects\junit-5\junit-5-assertions\junit-5-timeout-assertions\src\main\resources
[INFO] 
[INFO] --- compiler:3.14.1:compile (default-compile) @ junit-5-timeout-assertions ---
[INFO] Nothing to compile - all classes are up to date.
[INFO] 
[INFO] --- resources:3.3.1:testResources (default-testResources) @ junit-5-timeout-assertions ---
[WARNING] Using platform encoding (UTF-8 actually) to copy filtered resources, i.e. build is platform dependent!
[INFO] skip non existing resourceDirectory D:\example-projects\junit-5\junit-5-assertions\junit-5-timeout-assertions\src\test\resources
[INFO] 
[INFO] --- compiler:3.14.1:testCompile (default-testCompile) @ junit-5-timeout-assertions ---
[INFO] Recompiling the module because of added or removed source files.
[INFO] Compiling 1 source file with javac [debug target 25] to target\test-classes
[INFO] 
[INFO] --- surefire:3.2.5:test (default-test) @ junit-5-timeout-assertions ---
[INFO] Using auto detected provider org.apache.maven.surefire.junitplatform.JUnitPlatformProvider
[INFO] 
[INFO] -------------------------------------------------------
[INFO]  T E S T S
[INFO] -------------------------------------------------------
[INFO] Running com.logicbig.example.TimeoutTest
[INFO] Tests run: 3, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 0.612 s -- in com.logicbig.example.TimeoutTest
[INFO] 
[INFO] Results:
[INFO] 
[INFO] Tests run: 3, Failures: 0, Errors: 0, Skipped: 0
[INFO] 
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time:  3.989 s
[INFO] Finished at: 2025-12-01T13:20:55+08:00
[INFO] ------------------------------------------------------------------------

Example Project

Dependencies and Technologies Used:

• junit-jupiter-engine 6.0.1 (Module "junit-jupiter-engine" of JUnit)
   Version Compatibility: 5.0.0 - 6.0.1Version List
  ×

  Version compatibilities of junit-jupiter-engine with this example:

  • 5.0.0
  • 5.0.1
  • 5.0.2
  • 5.0.3
  • 5.1.0
  • 5.1.1
  • 5.2.0
  • 5.3.0
  • 5.3.1
  • 5.3.2
  • 5.4.0
  • 5.4.1
  • 5.4.2
  • 5.5.0
  • 5.5.1
  • 5.5.2
  • 5.6.0
  • 5.6.1
  • 5.6.2
  • 5.6.3
  • 5.7.0
  • 5.7.1
  • 5.7.2
  • 5.8.0
  • 5.8.1
  • 5.8.2
  • 5.9.0
  • 5.9.1
  • 5.9.2
  • 5.9.3
  • 5.10.0
  • 5.10.1
  • 5.10.2
  • 5.10.3
  • 5.10.4
  • 5.10.5
  • 5.11.0
  • 5.11.1
  • 5.11.2
  • 5.11.3
  • 5.11.4
  • 5.12.0
  • 5.12.1
  • 5.12.2
  • 5.13.0
  • 5.13.1
  • 5.13.2
  • 5.13.3
  • 5.13.4
  • 5.14.0
  • 5.14.1
  • 6.0.0
  • 6.0.1

  Versions in green have been tested.

• JDK 25
• Maven 3.9.11