or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

configuration.mdcore-operations.mddiscovery-requests.mdfilters.mdindex.mdlisteners.mdtest-plan.md
tile.json

tessl/maven-org-junit-platform--junit-platform-launcher

JUnit Platform Launcher provides APIs for discovering and executing tests on the JUnit Platform, typically used by IDEs and build tools

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
mavenpkg:maven/org.junit.platform/junit-platform-launcher@1.12.x

To install, run

npx @tessl/cli install tessl/maven-org-junit-platform--junit-platform-launcher@1.12.0

index.mddocs/

JUnit Platform Launcher

JUnit Platform Launcher provides programmatic APIs for discovering and executing tests on the JUnit Platform. It serves as the foundational layer that enables test frameworks to register test engines, discover test cases, and execute them in a controlled manner. This API is primarily used by IDEs, build tools, and custom test runners to integrate with the JUnit 5 testing framework.

Package Information

  • Package Name: org.junit.platform:junit-platform-launcher
  • Package Type: maven
  • Language: Java
  • Installation: Add to your Maven or Gradle dependencies

Maven:

<dependency>
    <groupId>org.junit.platform</groupId>
    <artifactId>junit-platform-launcher</artifactId>
    <version>1.12.2</version>
</dependency>

Gradle:

implementation("org.junit.platform:junit-platform-launcher:1.12.2")

Core Imports

import org.junit.platform.launcher.Launcher;
import org.junit.platform.launcher.LauncherSession;
import org.junit.platform.launcher.TestPlan;
import org.junit.platform.launcher.TestExecutionListener;
import org.junit.platform.launcher.core.LauncherFactory;
import org.junit.platform.launcher.core.LauncherDiscoveryRequestBuilder;

Basic Usage

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

// Create a launcher and discovery request
Launcher launcher = LauncherFactory.create();

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

// Discover and execute tests
TestPlan testPlan = launcher.discover(request);
launcher.execute(testPlan, new MyTestExecutionListener());

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

Architecture

The JUnit Platform Launcher is built around several key components:

  • Launcher Interface: Main entry point for test discovery and execution operations
  • Session Management: LauncherSession provides lifecycle management for repeated test operations
  • Discovery System: Request builders and listeners for flexible test discovery configuration
  • Execution System: Event-driven test execution with comprehensive listener support
  • Filtering System: Multiple filter types for precise test selection (engines, tags, methods)
  • Factory Pattern: LauncherFactory provides clean instantiation with configuration support

Capabilities

Core Test Operations

Primary interfaces for discovering and executing tests, including both one-shot operations and session-based repeated execution patterns.

// Main launcher interface
interface Launcher {
    void registerLauncherDiscoveryListeners(LauncherDiscoveryListener... listeners);
    void registerTestExecutionListeners(TestExecutionListener... listeners);
    TestPlan discover(LauncherDiscoveryRequest request);
    void execute(LauncherDiscoveryRequest request, TestExecutionListener... listeners);
    void execute(TestPlan testPlan, TestExecutionListener... listeners);
}

// Session-based operations
interface LauncherSession extends AutoCloseable {
    Launcher getLauncher();
    void close();
}

Core Test Operations

Discovery and Request Building

Comprehensive APIs for building discovery requests with selectors, filters, and configuration parameters. Supports flexible test selection patterns.

class LauncherDiscoveryRequestBuilder {
    static LauncherDiscoveryRequestBuilder request();
    LauncherDiscoveryRequestBuilder selectors(DiscoverySelector... selectors);
    LauncherDiscoveryRequestBuilder filters(Filter<?>... filters);
    LauncherDiscoveryRequestBuilder configurationParameter(String key, String value);
    LauncherDiscoveryRequest build();
}

interface LauncherDiscoveryRequest extends EngineDiscoveryRequest {
    List<EngineFilter> getEngineFilters();
    List<PostDiscoveryFilter> getPostDiscoveryFilters();
    LauncherDiscoveryListener getDiscoveryListener();
}

Discovery and Request Building

Event Listeners and Monitoring

Rich listener interfaces for monitoring test discovery and execution events. Supports custom reporting and integration with external systems.

interface TestExecutionListener {
    void testPlanExecutionStarted(TestPlan testPlan);
    void testPlanExecutionFinished(TestPlan testPlan);
    void executionStarted(TestIdentifier testIdentifier);
    void executionFinished(TestIdentifier testIdentifier, TestExecutionResult result);
    void executionSkipped(TestIdentifier testIdentifier, String reason);
    void dynamicTestRegistered(TestIdentifier testIdentifier);
}

interface LauncherDiscoveryListener extends EngineDiscoveryListener {
    void launcherDiscoveryStarted(LauncherDiscoveryRequest request);
    void launcherDiscoveryFinished(LauncherDiscoveryRequest request);
}

Event Listeners and Monitoring

Test Plan and Identification

Comprehensive test plan representation with hierarchical test structure support and metadata access.

class TestPlan {
    Set<TestIdentifier> getRoots();
    Optional<TestIdentifier> getParent(TestIdentifier child);
    Set<TestIdentifier> getChildren(TestIdentifier parent);
    Set<TestIdentifier> getDescendants(TestIdentifier parent);
    boolean containsTests();
    long countTestIdentifiers(Predicate<? super TestIdentifier> predicate);
}

class TestIdentifier implements Serializable {
    String getUniqueId();
    String getDisplayName();
    boolean isTest();
    boolean isContainer();
    Optional<TestSource> getSource();
    Set<TestTag> getTags();
}

Test Plan and Identification

Filtering and Selection

Advanced filtering capabilities for precise test selection including engine filters, tag expressions, and method patterns.

class EngineFilter implements Filter<TestEngine> {
    static EngineFilter includeEngines(String... engineIds);
    static EngineFilter excludeEngines(String... engineIds);
    FilterResult apply(TestEngine testEngine);
}

class TagFilter {
    static PostDiscoveryFilter includeTags(String... tagExpressions);
    static PostDiscoveryFilter excludeTags(String... tagExpressions);
}

interface MethodFilter extends PostDiscoveryFilter {
    static MethodFilter includeMethodNamePatterns(String... patterns);
    static MethodFilter excludeMethodNamePatterns(String... patterns);
}

Filtering and Selection

Configuration and Factory

Flexible launcher configuration and factory patterns supporting both default and custom configurations with auto-registration control.

class LauncherFactory {
    static LauncherSession openSession();
    static LauncherSession openSession(LauncherConfig config);
    static Launcher create();
    static Launcher create(LauncherConfig config);
}

interface LauncherConfig {
    boolean isTestEngineAutoRegistrationEnabled();
    boolean isLauncherSessionListenerAutoRegistrationEnabled();
    Collection<TestEngine> getAdditionalTestEngines();
    Collection<TestExecutionListener> getAdditionalTestExecutionListeners();
    static Builder builder();
}

Configuration and Factory