0
# JUnit Platform Console
1

2
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.
3

4
## Package Information
5

6
- **Package Name**: org.junit.platform:junit-platform-console
7
- **Package Type**: Maven
8
- **Language**: Java
9
- **License**: Eclipse Public License v2.0
10
- **Installation**: Add to your build file:
11

12
Maven:
13
```xml
14
<dependency>
15
    <groupId>org.junit.platform</groupId>
16
    <artifactId>junit-platform-console</artifactId>
17
    <version>1.12.2</version>
18
</dependency>
19
```
20

21
Gradle:
22
```gradle
23
implementation 'org.junit.platform:junit-platform-console:1.12.2'
24
```
25

26
## Core Imports
27

28
```java
29
import org.junit.platform.console.ConsoleLauncher;
30
import org.junit.platform.console.ConsoleLauncherToolProvider;
31
```
32

33
## Basic Usage
34

35
### Command Line Execution
36

37
```bash
38
# Using as executable JAR
39
java -jar junit-platform-console.jar --scan-classpath
40

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

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

47
# Execute tests with detailed output
48
java -jar junit-platform-console.jar --scan-classpath --details=tree
49
```
50

51
### Programmatic Usage
52

53
```java
54
import org.junit.platform.console.ConsoleLauncher;
55
import org.junit.platform.console.ConsoleLauncherToolProvider;
56
import java.io.PrintWriter;
57
import java.io.StringWriter;
58
import java.util.spi.ToolProvider;
59

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

63
// Using ToolProvider interface (recommended for programmatic usage)
64
ToolProvider provider = new ConsoleLauncherToolProvider();
65
StringWriter outWriter = new StringWriter();
66
StringWriter errWriter = new StringWriter();
67
int exitCode = provider.run(
68
    new PrintWriter(outWriter), 
69
    new PrintWriter(errWriter), 
70
    "--scan-classpath"
71
);
72
```
73

74
## Architecture
75

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

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

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

84
## Capabilities
85

86
### Main Console Launcher
87

88
The primary entry point for command-line test execution.
89

90
```java { .api }
91
@API(status = MAINTAINED, since = "1.0")
92
public class ConsoleLauncher {
93
    // Main entry point for console launcher
94
    public static void main(String... args);
95
    
96
    // Internal execution method - NOT for external use
97
    @API(status = INTERNAL, since = "1.0")
98
    public static CommandResult<?> run(PrintWriter out, PrintWriter err, String... args);
99
}
100
```
101

102
**Parameters:**
103
- `args`: Command-line arguments for test execution configuration
104

105
**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.
106

107
### Tool Provider Integration
108

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

111
```java { .api }
112
@API(status = STABLE, since = "1.10")
113
public class ConsoleLauncherToolProvider implements ToolProvider {
114
    // Returns the tool name
115
    @Override
116
    public String name();
117
    
118
    // Executes the console launcher with custom output streams
119
    @Override
120
    public int run(PrintWriter out, PrintWriter err, String... args);
121
}
122
```
123

124
**Methods:**
125
- `name()`: Returns `"junit"` as the tool identifier
126
- `run(PrintWriter out, PrintWriter err, String... args)`: Executes the launcher with specified output streams
127

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

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

132
## Command Line Options
133

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

136
### Test Discovery Options
137
- `--scan-classpath`: Scan entire classpath for tests
138
- `--scan-modules`: Scan module path for tests  
139
- `--select-class=CLASS`: Select specific test classes
140
- `--select-method=METHOD`: Select specific test methods
141
- `--select-package=PACKAGE`: Select tests in specific packages
142
- `--include-classname=PATTERN`: Include classes matching pattern
143
- `--exclude-classname=PATTERN`: Exclude classes matching pattern
144
- `--include-package=PATTERN`: Include packages matching pattern
145
- `--exclude-package=PATTERN`: Exclude packages matching pattern
146
- `--include-tag=TAG`: Include tests with specific tags
147
- `--exclude-tag=TAG`: Exclude tests with specific tags
148

149
### Execution Options
150
- `--config=KEY=VALUE`: Set configuration parameters
151
- `--enable-preview`: Enable preview features
152
- `--disable-ansi-colors`: Disable colored output
153
- `--disable-banner`: Disable startup banner
154
- `--fail-if-no-tests`: Fail if no tests found
155

156
### Output Options
157
- `--details=MODE`: Set output detail level (`none`, `summary`, `flat`, `tree`, `verbose`, `testfeed`)
158
- `--reports-dir=PATH`: Specify directory for XML test reports
159

160
### Common Usage Patterns
161

162
```bash
163
# Basic test execution with tree output
164
java -jar junit-platform-console.jar --scan-classpath --details=tree
165

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

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

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

176
## Types
177

178
```java { .api }
179
// Tool provider interface implementation
180
@API(status = STABLE, since = "1.10")
181
public class ConsoleLauncherToolProvider implements java.util.spi.ToolProvider {
182
    @Override
183
    String name();
184
    @Override
185
    int run(PrintWriter out, PrintWriter err, String... args);
186
}
187

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

198
// Internal types referenced but not part of public API
199
@API(status = INTERNAL, since = "1.10")
200
class CommandResult<T> {
201
    // Exit code indicating successful execution
202
    public static final int SUCCESS = 0;
203
    
204
    int getExitCode();
205
    // Other methods are internal implementation details
206
}
207
```
208

209
## Error Handling
210

211
The console launcher uses exit codes to indicate execution status:
212

213
- **Exit Code 0**: Successful execution (CommandResult.SUCCESS)
214
- **Exit Code -1**: Execution failure (CommandResult.FAILURE)
215

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

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

220
### Exceptions
221

222
When using the programmatic APIs:
223
- Invalid command-line arguments result in execution failures indicated by non-zero exit codes
224
- I/O errors during test execution are handled internally and reflected in exit codes
225
- The public APIs do not throw checked exceptions but may propagate runtime exceptions from underlying components
226

227
## Integration Patterns
228

229
### CI/CD Pipeline Integration
230

231
```bash
232
#!/bin/bash
233
# Example CI script
234
java -jar junit-platform-console.jar \
235
  --scan-classpath \
236
  --reports-dir=./test-reports \
237
  --details=tree \
238
  --fail-if-no-tests
239

240
exit_code=$?
241
if [ $exit_code -eq 0 ]; then
242
    echo "All tests passed"
243
else
244
    echo "Tests failed with exit code: $exit_code"
245
    exit $exit_code
246
fi
247
```
248

249
### Build Tool Integration
250

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

253
```bash
254
# Gradle custom task
255
./gradlew build
256
java -jar build/libs/junit-platform-console.jar --scan-classpath
257

258
# Maven integration
259
mvn compile test-compile
260
java -jar ~/.m2/repository/org/junit/platform/junit-platform-console/1.12.2/junit-platform-console.jar --scan-classpath
261
```
262

263
## Limitations and Considerations
264

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

271
## Dependencies
272

273
The console launcher requires the following JUnit Platform modules:
274
- `org.junit.platform.commons`
275
- `org.junit.platform.engine`
276
- `org.junit.platform.launcher`  
277
- `org.junit.platform.reporting`
278

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