0
# JUnit Platform Suite API
1

2
JUnit Platform Suite API provides a comprehensive set of annotations for creating and configuring test suites on the JUnit Platform. It enables declarative test suite configuration with flexible test selection, advanced filtering, and extensive configuration capabilities for organizing and executing collections of tests across the JUnit Platform ecosystem.
3

4
## Package Information
5

6
- **Package Name**: org.junit.platform:junit-platform-suite-api
7
- **Package Type**: maven
8
- **Language**: Java
9
- **Installation**: 
10
  ```xml
11
  <dependency>
12
    <groupId>org.junit.platform</groupId>
13
    <artifactId>junit-platform-suite-api</artifactId>
14
    <version>1.12.2</version>
15
  </dependency>
16
  ```
17

18
## Core Imports
19

20
```java
21
import org.junit.platform.suite.api.Suite;
22
import org.junit.platform.suite.api.SelectClasses;
23
import org.junit.platform.suite.api.SelectPackages;
24
import org.junit.platform.suite.api.IncludeTags;
25
import org.junit.platform.suite.api.ExcludeTags;
26
```
27

28
## Basic Usage
29

30
```java
31
import org.junit.platform.suite.api.*;
32

33
@Suite
34
@SelectPackages("com.example.tests")
35
@IncludeTags("integration")
36
@ExcludeTags("slow")
37
@SuiteDisplayName("Integration Test Suite")
38
public class IntegrationTestSuite {
39
    // Suite configuration through annotations only
40
    
41
    @BeforeSuite
42
    static void setUp() {
43
        // Optional setup before all tests in suite
44
        System.out.println("Starting integration tests");
45
    }
46
    
47
    @AfterSuite
48
    static void tearDown() {
49
        // Optional cleanup after all tests in suite
50
        System.out.println("Integration tests completed");
51
    }
52
}
53
```
54

55
## Architecture
56

57
The JUnit Platform Suite API is built around several key architectural components:
58

59
- **Annotation-Driven Configuration**: All suite configuration is done through annotations applied to suite classes
60
- **Test Selection Engine**: Sophisticated test selection using various criteria (classes, packages, methods, files, resources, etc.)
61
- **Filtering System**: Powerful include/exclude filtering based on engines, packages, tags, and class name patterns
62
- **Configuration Management**: Support for configuration parameters from annotations, resources, and parent discovery requests
63
- **Lifecycle Integration**: Suite-level setup and teardown capabilities with @BeforeSuite and @AfterSuite
64
- **JUnit Platform Integration**: Seamless integration with JUnit Platform's discovery and execution engines
65

66
## Capabilities
67

68
### Core Suite Framework
69

70
Central annotations for defining and configuring test suites with display names and failure behavior.
71

72
```java { .api }
73
@Suite
74
public @interface Suite {
75
    boolean failIfNoTests() default true;
76
}
77

78
@SuiteDisplayName("Custom Display Name")
79
public @interface SuiteDisplayName {
80
    String value();
81
}
82
```
83

84
[Core Suite Framework](./core-framework.md)
85

86
### Suite Lifecycle Management
87

88
Annotations for controlling execution flow with setup and teardown methods that run before and after all tests in a suite.
89

90
```java { .api }
91
@BeforeSuite
92
static void setUp() { /* setup logic */ }
93

94
@AfterSuite  
95
static void tearDown() { /* cleanup logic */ }
96
```
97

98
[Suite Lifecycle](./lifecycle.md)
99

100
### Test Selection
101

102
Comprehensive test selection capabilities supporting classes, packages, methods, files, resources, directories, modules, and URIs with flexible selector syntax.
103

104
```java { .api }
105
@SelectClasses({TestClass1.class, TestClass2.class})
106
@SelectPackages({"com.example.unit", "com.example.integration"})
107
@SelectMethod(type = MyTest.class, name = "testMethod")
108
@Select({"class:com.example.TestClass", "method:com.example.TestClass#testMethod"})
109
```
110

111
[Test Selection](./selection.md)
112

113
### Test Filtering  
114

115
Advanced filtering system for including and excluding tests based on engines, packages, tags, and class name patterns with support for complex tag expressions.
116

117
```java { .api }
118
@IncludeEngines({"junit-jupiter", "junit-vintage"})
119
@ExcludeEngines("junit-platform-suite")
120
@IncludeTags({"unit", "integration"})
121
@ExcludeTags({"slow | flaky"})
122
@IncludeClassNamePatterns(".*Test")
123
@ExcludeClassNamePatterns(".*IT")
124
```
125

126
[Test Filtering](./filtering.md)
127

128
### Configuration Management
129

130
Configuration parameter management with support for inline parameters, properties files, and inheritance control from parent discovery requests.
131

132
```java { .api }
133
@ConfigurationParameter(key = "junit.jupiter.displayname.generator.default", 
134
                       value = "org.junit.jupiter.api.DisplayNameGenerator$ReplaceUnderscores")
135
@ConfigurationParametersResource("/test-config.properties")
136
@DisableParentConfigurationParameters
137
```
138

139
[Configuration](./configuration.md)
140

141
## Types
142

143
```java { .api }
144
// Container annotations for repeatable annotations
145
public @interface Selects {
146
    Select[] value();
147
}
148

149
public @interface SelectFiles {
150
    SelectFile[] value();
151
}
152

153
public @interface SelectClasspathResources {
154
    SelectClasspathResource[] value();
155
}
156

157
public @interface SelectMethods {
158
    SelectMethod[] value();
159
}
160

161
public @interface ConfigurationParameters {
162
    ConfigurationParameter[] value();
163
}
164

165
public @interface ConfigurationParametersResources {
166
    ConfigurationParametersResource[] value();
167
}
168

169
// Deprecated annotation
170
@Deprecated
171
@API(status = DEPRECATED, since = "1.8")
172
public @interface UseTechnicalNames {
173
}
174
```