JUnit Platform Console

The JUnit Platform Console provides a stand-alone command-line application for launching JUnit Platform tests directly from the console. It serves as an executable frontend to the JUnit Platform, enabling developers to run JUnit 5 tests outside of IDEs or build tools with comprehensive test discovery, execution, and reporting capabilities.

Package Information

• Package Name: org.junit.platform:junit-platform-console
• Package Type: Maven
• Language: Java
• License: Eclipse Public License v2.0
• Installation: Add to your build file:

Maven:

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

Gradle:

implementation 'org.junit.platform:junit-platform-console:1.12.2'

Core Imports

import org.junit.platform.console.ConsoleLauncher;
import org.junit.platform.console.ConsoleLauncherToolProvider;

Basic Usage

Command Line Execution

# Using as executable JAR
java -jar junit-platform-console.jar --scan-classpath

# Using with java -m (when on module path)
java -m org.junit.platform.console --scan-classpath

# Execute specific test classes
java -jar junit-platform-console.jar --select-class=com.example.MyTest

# Execute tests with detailed output
java -jar junit-platform-console.jar --scan-classpath --details=tree

Programmatic Usage

import org.junit.platform.console.ConsoleLauncher;
import org.junit.platform.console.ConsoleLauncherToolProvider;
import java.io.PrintWriter;
import java.io.StringWriter;
import java.util.spi.ToolProvider;

// Using main method (basic usage)
ConsoleLauncher.main("--scan-classpath", "--details=tree");

// Using ToolProvider interface (recommended for programmatic usage)
ToolProvider provider = new ConsoleLauncherToolProvider();
StringWriter outWriter = new StringWriter();
StringWriter errWriter = new StringWriter();
int exitCode = provider.run(
    new PrintWriter(outWriter), 
    new PrintWriter(errWriter), 
    "--scan-classpath"
);

Architecture

The JUnit Platform Console follows a "tool-first" design philosophy with minimal public APIs:

• ConsoleLauncher: Main entry point providing static methods for console execution
• ConsoleLauncherToolProvider: Java ToolProvider SPI implementation for tool integration
• Internal Implementation: All configuration, discovery, and execution logic is internal and not exposed as public API

This design prioritizes command-line usage over programmatic embedding, making it ideal for CI/CD pipelines and standalone test execution.

Capabilities

Main Console Launcher

The primary entry point for command-line test execution.

@API(status = MAINTAINED, since = "1.0")
public class ConsoleLauncher {
    // Main entry point for console launcher
    public static void main(String... args);
    
    // Internal execution method - NOT for external use
    @API(status = INTERNAL, since = "1.0")
    public static CommandResult<?> run(PrintWriter out, PrintWriter err, String... args);
}

Parameters:

• args: Command-line arguments for test execution configuration

Usage: The main method is the standard entry point when running the console launcher as an executable application. The run method is internal and should not be used by external consumers - use the ToolProvider interface instead for programmatic access.

Tool Provider Integration

Provides JUnit Console Launcher as a service via Java's ToolProvider SPI.

@API(status = STABLE, since = "1.10")
public class ConsoleLauncherToolProvider implements ToolProvider {
    // Returns the tool name
    @Override
    public String name();
    
    // Executes the console launcher with custom output streams
    @Override
    public int run(PrintWriter out, PrintWriter err, String... args);
}

Methods:

• name(): Returns "junit" as the tool identifier
• run(PrintWriter out, PrintWriter err, String... args): Executes the launcher with specified output streams

Returns: Exit code (0 for success, non-zero for failure)

Usage: This interface allows integration with tools that use Java's ToolProvider service, enabling invocation through java -m or custom tool frameworks.

Command Line Options

The console launcher supports extensive command-line configuration options for test discovery, execution, and reporting:

Test Discovery Options

• --scan-classpath: Scan entire classpath for tests
• --scan-modules: Scan module path for tests
• --select-class=CLASS: Select specific test classes
• --select-method=METHOD: Select specific test methods
• --select-package=PACKAGE: Select tests in specific packages
• --include-classname=PATTERN: Include classes matching pattern
• --exclude-classname=PATTERN: Exclude classes matching pattern
• --include-package=PATTERN: Include packages matching pattern
• --exclude-package=PATTERN: Exclude packages matching pattern
• --include-tag=TAG: Include tests with specific tags
• --exclude-tag=TAG: Exclude tests with specific tags

Execution Options

• --config=KEY=VALUE: Set configuration parameters
• --enable-preview: Enable preview features
• --disable-ansi-colors: Disable colored output
• --disable-banner: Disable startup banner
• --fail-if-no-tests: Fail if no tests found

Output Options

• --details=MODE: Set output detail level (none, summary, flat, tree, verbose, testfeed)
• --reports-dir=PATH: Specify directory for XML test reports

Common Usage Patterns

# Basic test execution with tree output
java -jar junit-platform-console.jar --scan-classpath --details=tree

# Execute specific package with reports
java -jar junit-platform-console.jar --select-package=com.example.tests --reports-dir=./reports

# Execute with tag filtering and no colors
java -jar junit-platform-console.jar --scan-classpath --include-tag=integration --disable-ansi-colors

# Parallel execution with custom configuration
java -jar junit-platform-console.jar --scan-classpath --config=junit.jupiter.execution.parallel.enabled=true

Types

// Tool provider interface implementation
@API(status = STABLE, since = "1.10")
public class ConsoleLauncherToolProvider implements java.util.spi.ToolProvider {
    @Override
    String name();
    @Override
    int run(PrintWriter out, PrintWriter err, String... args);
}

// Main launcher class  
@API(status = MAINTAINED, since = "1.0")
public class ConsoleLauncher {
    public static void main(String... args);
    
    // Internal method - not for external use
    @API(status = INTERNAL, since = "1.0")
    public static CommandResult<?> run(PrintWriter out, PrintWriter err, String... args);
}

// Internal types referenced but not part of public API
@API(status = INTERNAL, since = "1.10")
class CommandResult<T> {
    // Exit code indicating successful execution
    public static final int SUCCESS = 0;
    
    int getExitCode();
    // Other methods are internal implementation details
}

Error Handling

The console launcher uses exit codes to indicate execution status:

• Exit Code 0: Successful execution (CommandResult.SUCCESS)
• Exit Code -1: Execution failure (CommandResult.FAILURE)

Note: Specific exit codes for different failure types (test failures, no tests found, etc.) depend on the execution context and internal implementation details.

When using the ToolProvider interface, these same exit codes are returned from the run() method rather than terminating the JVM.

Exceptions

When using the programmatic APIs:

• Invalid command-line arguments result in execution failures indicated by non-zero exit codes
• I/O errors during test execution are handled internally and reflected in exit codes
• The public APIs do not throw checked exceptions but may propagate runtime exceptions from underlying components

Integration Patterns

CI/CD Pipeline Integration

#!/bin/bash
# Example CI script
java -jar junit-platform-console.jar \
  --scan-classpath \
  --reports-dir=./test-reports \
  --details=tree \
  --fail-if-no-tests

exit_code=$?
if [ $exit_code -eq 0 ]; then
    echo "All tests passed"
else
    echo "Tests failed with exit code: $exit_code"
    exit $exit_code
fi

Build Tool Integration

The console launcher is commonly used in build scripts where direct IDE integration is not available:

# Gradle custom task
./gradlew build
java -jar build/libs/junit-platform-console.jar --scan-classpath

# Maven integration
mvn compile test-compile
java -jar ~/.m2/repository/org/junit/platform/junit-platform-console/1.12.2/junit-platform-console.jar --scan-classpath

Limitations and Considerations

1. Minimal Programmatic API: Designed primarily for command-line usage rather than embedding in applications
2. Internal Implementation: Most classes are marked as internal and should not be used programmatically
3. Alternative APIs: For programmatic test execution, consider using the JUnit Platform Launcher API directly
4. Classpath Requirements: Requires JUnit Platform Engine implementations on the classpath to execute tests
5. Java Module System: Supports both classpath and module path execution modes

Dependencies

The console launcher requires the following JUnit Platform modules:

• org.junit.platform.commons
• org.junit.platform.engine
• org.junit.platform.launcher
• org.junit.platform.reporting

Test engines (e.g., JUnit Jupiter, JUnit Vintage) must be available on the classpath for test execution.