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 Detail

      • onTimeoutDetected

        void onTimeoutDetected​(ForkedProcessTimeoutContext context)
                        throws java.lang.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:
        java.lang.Exception - any failure is logged by Surefire and suppressed
      • onForkExited

        void onForkExited​(ForkedProcessTimeoutContext context,
                          org.apache.maven.surefire.api.suite.RunResult runResult)
                   throws java.lang.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:
        java.lang.Exception - any failure is logged by Surefire and suppressed