Package org.apache.maven.surefire.extensions

Interface ForkedProcessTimeoutExtension

public interface ForkedProcessTimeoutExtension
Extension point invoked when a forked Surefire test JVM exceeds its configured forkedProcessTimeoutInSeconds.

Implementations are discovered via the standard ServiceLoader mechanism from the plugin classpath. To register an extension, add a file META-INF/services/org.apache.maven.surefire.extensions.ForkedProcessTimeoutExtension to your extension JAR and declare it as a <dependency> of maven-surefire-plugin (or maven-failsafe-plugin) in the project POM.

The primary motivation is to capture diagnostic information (for example, a jstack thread dump) about a test JVM that is about to be killed so the root cause of a deadlock or hang can be investigated.

Lifecycle:

  1. onTimeoutDetected(ForkedProcessTimeoutContext) is invoked synchronously immediately after Surefire detects the timeout but before the KILL shutdown command is sent. The forked JVM is therefore still alive at this point, which makes utilities such as jstack usable.
  2. onForkExited(ForkedProcessTimeoutContext, RunResult) is invoked from the plugin after the forked JVM has actually exited.
Any Throwable raised by a callback is caught by Surefire, logged at warn level, and does not affect the test result.

Callbacks are executed on Surefire-managed daemon threads and are subject to an internal time limit; implementations should complete quickly and must not block indefinitely.

Since:
3.6.0

  • Method Details

    • onTimeoutDetected

      void onTimeoutDetected(ForkedProcessTimeoutContext context) throws Exception
      Invoked when Surefire detects that a forked JVM has exceeded its timeout, before the JVM is killed.

      At this point the forked JVM is still running; tools that require a live target process (such as jstack) may be invoked here.

      Parameters:
      context - diagnostic information about the forked process; never null
      Throws:
      Exception - any failure is logged by Surefire and suppressed

    • onForkExited

      void onForkExited(ForkedProcessTimeoutContext context, RunResult runResult) throws Exception
      Invoked after the forked JVM has exited following a timeout.

      Useful for cleanup, archival of dumps, or notifying external systems. The forked JVM is no longer alive when this method is invoked.

      Parameters:
      context - diagnostic information about the forked process; never null
      runResult - the final RunResult for the fork; never null
      Throws:
      Exception - any failure is logged by Surefire and suppressed