0
# Core Suite Declaration
1

2
Primary suite declaration and configuration annotations for defining test suites with display names, failure policies, and basic suite properties on the JUnit Platform.
3

4
## Capabilities
5

6
### @Suite Annotation
7

8
Marks a class as a test suite on the JUnit Platform, serving as the foundational annotation for declarative test suite creation.
9

10
```java { .api }
11
/**
12
 * Marks a class as a test suite on the JUnit Platform.
13
 * Selector and filter annotations control suite contents.
14
 * Configuration annotations provide suite-specific parameters.
15
 * 
16
 * Uses default include pattern when @IncludeClassNamePatterns not present:
17
 * "^(Test.*|.+[.$]Test.*|.*Tests?)$"
18
 * 
19
 * Inherits configuration parameters from discovery request unless disabled
20
 * with @DisableParentConfigurationParameters.
21
 */
22
@Retention(RetentionPolicy.RUNTIME)
23
@Target(ElementType.TYPE)
24
@Inherited
25
@Documented
26
@API(status = STABLE, since = "1.10")
27
@Testable
28
public @interface Suite {
29
    /**
30
     * Fail suite if no tests were discovered.
31
     * @return true to fail when no tests found, false to allow empty suites
32
     * @since 1.9
33
     */
34
    @API(status = STABLE, since = "1.11")
35
    boolean failIfNoTests() default true;
36
}
37
```
38

39
**Usage Examples:**
40

41
```java
42
// Basic suite declaration
43
@Suite
44
@SelectClasses({TestA.class, TestB.class})
45
class BasicSuite {
46
}
47

48
// Suite allowing empty results
49
@Suite(failIfNoTests = false)
50
@SelectPackages("com.example.optional")
51
class OptionalSuite {
52
}
53

54
// Suite with multiple selection strategies
55
@Suite
56
@SelectClasses({CoreTest.class})
57
@SelectPackages("com.example.integration")
58
class CombinedSuite {
59
}
60
```
61

62
### @SuiteDisplayName Annotation
63

64
Declares a custom display name for test suites, providing human-readable names for test reporting and IDE display.
65

66
```java { .api }
67
/**
68
 * Declares a custom display name for test suites.
69
 * Supports spaces, special characters, and emoji for enhanced readability.
70
 * Used by test reporting tools, IDEs, and build systems.
71
 * Overridden by @UseTechnicalNames when present (deprecated).
72
 * 
73
 * @since 1.1
74
 */
75
@Retention(RetentionPolicy.RUNTIME)
76
@Target(ElementType.TYPE)
77
@Inherited
78
@Documented
79
@API(status = MAINTAINED)
80
public @interface SuiteDisplayName {
81
    /**
82
     * Custom display name for the test suite.
83
     * @return display name; never blank or containing only whitespace
84
     */
85
    String value();
86
}
87
```
88

89
**Usage Examples:**
90

91
```java
92
@Suite
93
@SuiteDisplayName("Integration Test Suite")
94
@SelectPackages("com.example.integration")
95
class IntegrationSuite {
96
}
97

98
@Suite
99
@SuiteDisplayName("🚀 Performance Tests")
100
@SelectPackages("com.example.performance")
101
class PerformanceSuite {
102
}
103

104
@Suite  
105
@SuiteDisplayName("User Management - Complete Test Coverage")
106
@SelectClasses({UserServiceTest.class, UserRepositoryTest.class})
107
class UserManagementSuite {
108
}
109
```
110

111
### @UseTechnicalNames Annotation (Deprecated)
112

113
Forces the use of technical names instead of display names for suite execution. This annotation is deprecated and scheduled for removal.
114

115
```java { .api }
116
/**
117
 * Use technical names instead of display names.
118
 * 
119
 * @deprecated Since 1.8, for removal in JUnit Platform 2.0.
120
 *             Superseded by native @Suite support.
121
 * @since 1.0
122
 */
123
@Deprecated
124
@API(status = DEPRECATED, since = "1.8", consumers = {"org.junit.platform.suite.engine"})
125
@Retention(RetentionPolicy.RUNTIME)
126
@Target(ElementType.TYPE)
127
@Inherited
128
@Documented
129
public @interface UseTechnicalNames {
130
}
131
```
132

133
**Migration Note:**
134

135
```java
136
// Deprecated approach (avoid)
137
@Suite
138
@UseTechnicalNames
139
@SuiteDisplayName("My Suite")
140
class MySuite {
141
}
142

143
// Modern approach (recommended)
144
@Suite
145
@SelectClasses({TestA.class, TestB.class})
146
class MySuite {  // Technical name used automatically
147
}
148
```
149

150
## Suite Declaration Patterns
151

152
### Basic Suite Declaration
153

154
Simple suite with explicit test selection:
155

156
```java
157
@Suite
158
@SelectClasses({UserTest.class, ProductTest.class})
159
class BusinessLogicSuite {
160
}
161
```
162

163
### Named Suite with Description
164

165
Suite with custom display name for reporting:
166

167
```java
168
@Suite
169
@SuiteDisplayName("End-to-End Integration Tests")
170
@SelectPackages("com.example.e2e")
171
class E2ESuite {
172
}
173
```
174

175
### Permissive Suite
176

177
Suite that allows empty test results:
178

179
```java
180
@Suite(failIfNoTests = false)
181
@SuiteDisplayName("Optional Component Tests")
182
@SelectPackages("com.example.optional")
183
@IncludeClassNamePatterns(".*ComponentTest")
184
class OptionalComponentSuite {
185
}
186
```
187

188
### Multi-Strategy Suite
189

190
Suite combining multiple selection strategies:
191

192
```java
193
@Suite
194
@SuiteDisplayName("Comprehensive Test Coverage")
195
@SelectClasses({CoreBusinessTest.class})
196
@SelectPackages("com.example.integration")  
197
@SelectMethod(type = UtilityTest.class, name = "specialTest")
198
class ComprehensiveSuite {
199
}
200
```