0
# Core Suite Framework
1

2
Central annotations for defining and configuring test suites with display names and failure behavior control.
3

4
## Capabilities
5

6
### @Suite Annotation
7

8
The primary annotation that marks a class as a test suite on the JUnit Platform.
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 additional parameters.
15
 */
16
@Retention(RetentionPolicy.RUNTIME)
17
@Target(ElementType.TYPE)
18
@Inherited
19
@Documented
20
@API(status = STABLE, since = "1.10")
21
@Testable
22
public @interface Suite {
23
    /**
24
     * Fail suite if no tests were discovered.
25
     * @return true to fail when no tests found, false to allow empty suites
26
     * @since 1.9
27
     */
28
    @API(status = STABLE, since = "1.11")
29
    boolean failIfNoTests() default true;
30
}
31
```
32

33
**Usage Examples:**
34

35
```java
36
// Basic suite - fails if no tests found
37
@Suite
38
@SelectPackages("com.example.tests")
39
public class BasicTestSuite {
40
}
41

42
// Suite that allows empty results
43
@Suite(failIfNoTests = false)
44
@SelectTags("optional")
45
public class OptionalTestSuite {
46
}
47

48
// Complex suite with multiple selectors and filters
49
@Suite
50
@SelectClasses({UnitTests.class, IntegrationTests.class})
51
@IncludeTags("smoke")
52
@ExcludeTags("slow")
53
@ConfigurationParameter(key = "parallel.execution", value = "true")
54
public class SmokeTestSuite {
55
}
56
```
57

58
### @SuiteDisplayName Annotation
59

60
Declares a custom display name for test suite execution in IDEs and build tools.
61

62
```java { .api }
63
/**
64
 * Declares a custom display name for test suite execution.
65
 * Display names are used for test reporting and may contain spaces, 
66
 * special characters, and emoji.
67
 */
68
@Retention(RetentionPolicy.RUNTIME)
69
@Target(ElementType.TYPE)
70
@Documented
71
@API(status = MAINTAINED, since = "1.1")
72
public @interface SuiteDisplayName {
73
    /**
74
     * The custom display name for the suite.
75
     * @return custom display name; never blank or consisting solely of whitespace
76
     */
77
    String value();
78
}
79
```
80

81
**Usage Examples:**
82

83
```java
84
@Suite
85
@SuiteDisplayName("🧪 Unit Test Suite")
86
@SelectPackages("com.example.unit")
87
public class UnitTestSuite {
88
}
89

90
@Suite  
91
@SuiteDisplayName("Integration Tests - Database Layer")
92
@SelectClasses({DatabaseIntegrationTest.class, RepositoryTest.class})
93
public class DatabaseIntegrationSuite {
94
}
95

96
@Suite
97
@SuiteDisplayName("Performance & Load Testing")
98
@IncludeTags("performance")
99
public class PerformanceTestSuite {
100
}
101
```
102

103
## Suite Configuration Best Practices
104

105
### Default Behavior
106

107
- When `@IncludeClassNamePatterns` is not present, the default include pattern `^(Test.*|.+[.$]Test.*|.*Tests?)$` is used
108
- By default, suites discover tests using both explicit configuration parameters and parameters from the parent discovery request
109
- Suite classes themselves don't contain test methods - configuration is done through annotations only
110

111
### Configuration Inheritance
112

113
- Suites support configuration inheritance from parent discovery requests
114
- Use `@DisableParentConfigurationParameters` to use only explicitly configured parameters
115
- Multiple selector annotations can be combined for complex test selection
116

117
### @UseTechnicalNames Annotation (Deprecated)
118

119
Specifies that technical names should be used instead of display names for test reporting.
120

121
```java { .api }
122
/**
123
 * Specifies that technical names should be used instead of display names.
124
 * @deprecated since 1.8, in favor of @Suite support provided by 
125
 * junit-platform-suite-engine module; to be removed in JUnit Platform 2.0
126
 */
127
@Retention(RetentionPolicy.RUNTIME)
128
@Target(ElementType.TYPE)
129
@Documented
130
@API(status = DEPRECATED, since = "1.8")
131
@Deprecated
132
public @interface UseTechnicalNames {
133
}
134
```
135

136
**Migration Path:**
137

138
```java
139
// DEPRECATED - Don't use this
140
@RunWith(JUnitPlatform.class)
141
@UseTechnicalNames
142
@SelectPackages("com.example")
143
public class OldStyleSuite {
144
}
145

146
// RECOMMENDED - Use @Suite instead
147
@Suite
148
@SelectPackages("com.example")
149
public class ModernSuite {
150
}
151
```
152

153
**Important Notes:**
154
- This annotation is deprecated since JUnit Platform 1.8
155
- It was used with `@RunWith(JUnitPlatform.class)` in JUnit 4 environments
156
- Will be removed in JUnit Platform 2.0
157
- Modern `@Suite` annotation provides equivalent functionality with better integration
158

159
### Error Handling
160

161
- When `failIfNoTests() = true` (default), suites will fail if no tests are discovered
162
- Invalid configuration parameters or malformed selectors will cause suite failure
163
- Tag expressions with invalid syntax will result in runtime errors