0
# JUnit Platform Suite
1

2
JUnit Platform Suite provides a comprehensive framework for creating declarative test suites on the JUnit 5 platform. It enables developers to compose sophisticated test suites using annotations for test selection, filtering, configuration, and lifecycle management with powerful and flexible control over test discovery and execution.
3

4
## Package Information
5

6
- **Package Name**: org.junit.platform:junit-platform-suite
7
- **Package Type**: Maven
8
- **Language**: Java
9
- **Installation**: Maven dependency or Gradle implementation
10
- **Module**: `org.junit.platform.suite` (aggregates `org.junit.platform.suite.api` and `org.junit.platform.suite.engine`)
11

12
## Core Imports
13

14
```java
15
import org.junit.platform.suite.api.Suite;
16
import org.junit.platform.suite.api.SelectClasses;
17
import org.junit.platform.suite.api.SelectPackages;
18
```
19

20
For specific capabilities:
21

22
```java
23
// Configuration annotations
24
import org.junit.platform.suite.api.ConfigurationParameter;
25
import org.junit.platform.suite.api.BeforeSuite;
26
import org.junit.platform.suite.api.AfterSuite;
27

28
// Selection annotations
29
import org.junit.platform.suite.api.SelectMethod;
30
import org.junit.platform.suite.api.SelectFiles;
31
import org.junit.platform.suite.api.SelectDirectories;
32

33
// Filter annotations
34
import org.junit.platform.suite.api.IncludeClassNamePatterns;
35
import org.junit.platform.suite.api.ExcludeClassNamePatterns;
36
import org.junit.platform.suite.api.IncludeTags;
37
import org.junit.platform.suite.api.ExcludeTags;
38
```
39

40
## Basic Usage
41

42
```java
43
import org.junit.platform.suite.api.*;
44

45
// Basic test suite with class selection
46
@Suite
47
@SelectClasses({UserTest.class, ProductTest.class, OrderTest.class})
48
class BasicSuite {
49
}
50

51
// Package-based suite with filtering
52
@Suite
53
@SelectPackages("com.example.integration")
54
@IncludeClassNamePatterns(".*IntegrationTest")
55
@ExcludeTags("slow")
56
class IntegrationSuite {
57
}
58

59
// Configuration with lifecycle
60
@Suite
61
@SelectPackages("com.example")
62
@ConfigurationParameter(key = "junit.jupiter.execution.parallel.enabled", value = "true")
63
@SuiteDisplayName("Parallel Test Suite")
64
class ParallelSuite {
65
    
66
    @BeforeSuite
67
    static void setupSuite() {
68
        // Suite initialization
69
        System.setProperty("test.environment", "suite");
70
    }
71
    
72
    @AfterSuite
73
    static void cleanupSuite() {
74
        // Suite cleanup
75
        System.clearProperty("test.environment");
76
    }
77
}
78
```
79

80
## Architecture
81

82
JUnit Platform Suite is built around several key architectural components:
83

84
- **Suite Declaration**: `@Suite` annotation marks classes as declarative test suites
85
- **Test Selection**: Multiple `@Select*` annotations specify which tests to include using classes, packages, methods, files, URIs, modules, or directories
86
- **Filtering System**: `@Include*` and `@Exclude*` annotations provide fine-grained control over test inclusion using class name patterns, packages, tags, and engines
87
- **Configuration Management**: `@ConfigurationParameter` and `@ConfigurationParametersResource` annotations manage suite-specific configuration
88
- **Lifecycle Integration**: `@BeforeSuite` and `@AfterSuite` annotations provide suite-level setup and teardown capabilities
89
- **Suite Engine**: Internal `SuiteTestEngine` integrates with JUnit Platform launcher for execution
90

91
The framework supports both explicit selection (selecting specific classes/methods) and discovery-based selection (selecting packages with filters), enabling flexible test organization and execution strategies.
92

93
## Capabilities
94

95
### Core Suite Declaration
96

97
Primary `@Suite` annotation and suite configuration for declaring and configuring test suites with display names and failure policies.
98

99
```java { .api }
100
@Suite
101
public @interface Suite {
102
    boolean failIfNoTests() default true;
103
}
104

105
@SuiteDisplayName
106
public @interface SuiteDisplayName {
107
    String value();
108
}
109
```
110

111
[Core Suite Declaration](./core-suite.md)
112

113
### Test Selection
114

115
Comprehensive test selection capabilities including classes, packages, methods, files, directories, URIs, modules, and classpath resources with flexible selector parsing.
116

117
```java { .api }
118
@SelectClasses
119
public @interface SelectClasses {
120
    Class<?>[] value() default {};
121
    String[] names() default {};
122
}
123

124
@SelectPackages
125
public @interface SelectPackages {
126
    String[] value();
127
}
128

129
@SelectMethod
130
public @interface SelectMethod {
131
    String value() default "";
132
    Class<?> type() default Class.class;
133
    String typeName() default "";
134
    String name() default "";
135
    Class<?>[] parameterTypes() default {};
136
    String parameterTypeNames() default "";
137
}
138
```
139

140
[Test Selection](./test-selection.md)
141

142
### Test Filtering
143

144
Powerful filtering system for including and excluding tests based on class name patterns, packages, tags, and test engines with regex pattern matching and tag expressions.
145

146
```java { .api }
147
@IncludeClassNamePatterns
148
public @interface IncludeClassNamePatterns {
149
    String[] value() default "^(Test.*|.+[.$]Test.*|.*Tests?)$";
150
}
151

152
@ExcludeClassNamePatterns  
153
public @interface ExcludeClassNamePatterns {
154
    String[] value();
155
}
156

157
@IncludeTags
158
public @interface IncludeTags {
159
    String[] value();
160
}
161

162
@ExcludeTags
163
public @interface ExcludeTags {
164
    String[] value();
165
}
166
```
167

168
[Test Filtering](./test-filtering.md)
169

170
### Configuration and Lifecycle
171

172
Suite configuration management through parameters and properties files, plus lifecycle hooks for suite setup and teardown operations.
173

174
```java { .api }
175
@ConfigurationParameter
176
public @interface ConfigurationParameter {
177
    String key();
178
    String value();
179
}
180

181
@BeforeSuite
182
public @interface BeforeSuite {
183
}
184

185
@AfterSuite
186
public @interface AfterSuite {
187
}
188

189
@DisableParentConfigurationParameters
190
public @interface DisableParentConfigurationParameters {
191
}
192
```
193

194
[Configuration and Lifecycle](./configuration-lifecycle.md)