The TestExecutionExceptionHandler defines the API for Extensions that wish to handle exceptions thrown during test execution. If an extension ignores the exception (by not rethrowing it), the test is considered successful. If it rethrows the exception, the test fails.

Java source and doc

Definition of TestExecutionExceptionHandler

 package org.junit.jupiter.api.extension;
 @FunctionalInterface
 @API(status = STABLE, since = "5.0")
 public interface TestExecutionExceptionHandler extends Extension {
     void handleTestExecutionException(ExtensionContext context, 1
                                       Throwable throwable)
                                       throws Throwable;
 }

Example

In this example, we create an IgnoreIOExceptionExtension. It intercepts any IOException thrown by a test method and logs a message instead of letting the test fail. Any other exception type will still cause a failure.

package com.logicbig.example;

import org.junit.jupiter.api.extension.ExtensionContext;
import org.junit.jupiter.api.extension.TestExecutionExceptionHandler;
import java.io.IOException;

public class IgnoreIOExceptionExtension implements TestExecutionExceptionHandler {

    @Override
    public void handleTestExecutionException(ExtensionContext context, 
                                               Throwable throwable) throws Throwable {
        if (throwable instanceof IOException) {
            System.err.println("Ignoring IOException in test: " + context.getDisplayName());
            return; 
        }
        throw throwable;
    }
}

Test Class

package com.logicbig.example;

import org.junit.jupiter.api.Test;
import org.junit.jupiter.api.extension.ExtendWith;
import java.io.IOException;

@ExtendWith(IgnoreIOExceptionExtension.class)
public class ExceptionHandlerTest {

    @Test
    void testWithIOException() throws IOException {
        System.out.println("Throwing IOException...");
        throw new IOException("Simulated network failure");
    }

    @Test
    void testWithRuntimeException() {
        System.out.println("This test should still fail...");
        throw new RuntimeException("Unexpected error");
    }
}

Output

$ mvn test -Dtest=ExceptionHandlerTest
[INFO] Scanning for projects...
[INFO] 
[INFO] -----------< com.logicbig.example:junit-5-exception-handler >-----------
[INFO] Building junit-5-exception-handler 1.0-SNAPSHOT
[INFO]   from pom.xml
[INFO] --------------------------------[ jar ]---------------------------------
[INFO] 
[INFO] --- resources:3.3.1:resources (default-resources) @ junit-5-exception-handler ---
[WARNING] Using platform encoding (Cp1252 actually) to copy filtered resources, i.e. build is platform dependent!
[INFO] skip non existing resourceDirectory D:\example-projects\junit-5\junit-5-extensions\junit-5-exception-handler\src\main\resources
[INFO] 
[INFO] --- compiler:3.13.0:compile (default-compile) @ junit-5-exception-handler ---
[INFO] No sources to compile
[INFO] 
[INFO] --- resources:3.3.1:testResources (default-testResources) @ junit-5-exception-handler ---
[WARNING] Using platform encoding (Cp1252 actually) to copy filtered resources, i.e. build is platform dependent!
[INFO] skip non existing resourceDirectory D:\example-projects\junit-5\junit-5-extensions\junit-5-exception-handler\src\test\resources
[INFO] 
[INFO] --- compiler:3.13.0:testCompile (default-testCompile) @ junit-5-exception-handler ---
[INFO] Nothing to compile - all classes are up to date.
[INFO] 
[INFO] --- surefire:3.5.0:test (default-test) @ junit-5-exception-handler ---
[INFO] Using auto detected provider org.apache.maven.surefire.junitplatform.JUnitPlatformProvider
[INFO] 
[INFO] -------------------------------------------------------
[INFO]  T E S T S
[INFO] -------------------------------------------------------
This test should still fail...
Throwing IOException...
[INFO] +--com.logicbig.example.ExceptionHandlerTest - 0.103 ss
[INFO] |  +-- [XX] testWithRuntimeException - 0.049 ss
[INFO] |  '-- [OK] testWithIOException - 0.020 ss
[INFO] 
[INFO] Results:
[INFO] 
[ERROR] Errors: 
[ERROR]   ExceptionHandlerTest.testWithRuntimeException:19 Runtime Unexpected error
[INFO] 
[ERROR] Tests run: 2, Failures: 0, Errors: 1, Skipped: 0
[INFO] 
[INFO] ------------------------------------------------------------------------
[INFO] BUILD FAILURE
[INFO] ------------------------------------------------------------------------
[INFO] Total time:  3.177 s
[INFO] Finished at: 2025-12-31T19:52:28+08:00
[INFO] ------------------------------------------------------------------------
[ERROR] Failed to execute goal org.apache.maven.plugins:maven-surefire-plugin:3.5.0:test (default-test) on project junit-5-exception-handler: 
[ERROR] 
[ERROR] Please refer to D:\example-projects\junit-5\junit-5-extensions\junit-5-exception-handler\target\surefire-reports for the individual test results.
[ERROR] Please refer to dump files (if any exist) [date].dump, [date]-jvmRun[N].dump and [date].dumpstream.
[ERROR] -> [Help 1]
[ERROR] 
[ERROR] To see the full stack trace of the errors, re-run Maven with the -e switch.
[ERROR] Re-run Maven using the -X switch to enable full debug logging.
[ERROR] 
[ERROR] For more information about the errors and possible solutions, please read the following articles:
[ERROR] [Help 1] http://cwiki.apache.org/confluence/display/MAVEN/MojoFailureException
Ignoring IOException in test: testWithIOException()

The test results show that testWithIOException passed successfully despite explicitly throwing an exception. This confirms that the IgnoreIOExceptionExtension intercepted the throw and handled it by returning normally. This extension point provides a robust way to implement custom recovery logic or specialized filtering for flaky environment-related errors.

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