Core Test Operations

/**
 * Main entry point for discovering and executing tests
 */
interface Launcher {
    /**
     * Register discovery listeners for this launcher
     * @param listeners - LauncherDiscoveryListener instances to register
     */
    void registerLauncherDiscoveryListeners(LauncherDiscoveryListener... listeners);
    
    /**
     * Register test execution listeners for this launcher
     * @param listeners - TestExecutionListener instances to register
     */
    void registerTestExecutionListeners(TestExecutionListener... listeners);
    
    /**
     * Discover tests based on the supplied request
     * @param launcherDiscoveryRequest - LauncherDiscoveryRequest specifying discovery parameters
     * @return TestPlan representing the discovered tests
     */
    TestPlan discover(LauncherDiscoveryRequest launcherDiscoveryRequest);
    
    /**
     * Execute tests from a discovery request with optional listeners
     * @param launcherDiscoveryRequest - LauncherDiscoveryRequest specifying what to execute
     * @param listeners - Additional TestExecutionListener instances
     */
    void execute(LauncherDiscoveryRequest launcherDiscoveryRequest, TestExecutionListener... listeners);
    
    /**
     * Execute a pre-built test plan with optional listeners
     * @param testPlan - TestPlan to execute
     * @param listeners - Additional TestExecutionListener instances
     */
    void execute(TestPlan testPlan, TestExecutionListener... listeners);
}

import org.junit.platform.launcher.*;
import org.junit.platform.launcher.core.*;
import static org.junit.platform.engine.discovery.DiscoverySelectors.*;

// Create launcher
Launcher launcher = LauncherFactory.create();

// Register global listeners
launcher.registerTestExecutionListeners(new SummaryGeneratingListener());

// Build discovery request
LauncherDiscoveryRequest request = LauncherDiscoveryRequestBuilder.request()
    .selectors(selectPackage("com.example.tests"))
    .build();

// Discover tests first, then execute
TestPlan testPlan = launcher.discover(request);
launcher.execute(testPlan);

// Or execute directly from request
launcher.execute(request, new MyCustomListener());

/**
 * Entry point for repeatedly discovering and executing tests
 * Implements AutoCloseable for proper resource management
 */
interface LauncherSession extends AutoCloseable {
    /**
     * Get the associated launcher for this session
     * @return Launcher instance for this session
     */
    Launcher getLauncher();
    
    /**
     * Close this session and notify all registered listeners
     */
    void close();
}

import org.junit.platform.launcher.*;
import org.junit.platform.launcher.core.*;

// Session-based usage with try-with-resources
try (LauncherSession session = LauncherFactory.openSession()) {
    Launcher launcher = session.getLauncher();
    
    // Multiple discovery/execution cycles within the same session
    for (String testPackage : testPackages) {
        LauncherDiscoveryRequest request = LauncherDiscoveryRequestBuilder.request()
            .selectors(selectPackage(testPackage))
            .build();
            
        launcher.execute(request);
    }
} // Session automatically closed here

/**
 * Listener interface for launcher session events
 * @since 1.10
 * @apiNote This interface is marked as @API(status = STABLE)
 */
interface LauncherSessionListener {
    /** No-op implementation of LauncherSessionListener */
    LauncherSessionListener NOOP = new LauncherSessionListener() {};
    /**
     * Called when a launcher session is opened
     * @param session - The LauncherSession that was opened
     */
    default void launcherSessionOpened(LauncherSession session) {}
    
    /**
     * Called when a launcher session is closed
     * @param session - The LauncherSession that was closed
     */
    default void launcherSessionClosed(LauncherSession session) {}
}

/**
 * Interceptor for test discovery and execution in launcher sessions
 * @since 1.10
 * @apiNote ⚠️ EXPERIMENTAL API - This interface is marked as @API(status = EXPERIMENTAL)
 * and may change in future releases without notice.
 */
interface LauncherInterceptor {
    /**
     * Intercept invocations during launcher operations
     * @param invocation - The Invocation to potentially modify or monitor
     * @return Result of the invocation
     */
    <T> T intercept(Invocation<T> invocation);
    
    /**
     * Represents an invocation in the interceptor chain
     */
    interface Invocation<T> {
        /**
         * Proceed with the invocation
         * @return Result of the invocation
         */
        T proceed();
    }
    
    /**
     * Close this interceptor and release any resources
     */
    void close();
}