0
# Suite Lifecycle Management
1

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

4
## Capabilities
5

6
### @BeforeSuite Annotation
7

8
Signals that the annotated method should be executed before all tests in the current test suite.
9

10
```java { .api }
11
/**
12
 * Signals that the annotated method should be executed before all tests
13
 * in the current test suite.
14
 * 
15
 * Methods must be static, void, and not private.
16
 * Supports inheritance with deterministic but non-obvious execution order.
17
 */
18
@Retention(RetentionPolicy.RUNTIME)
19
@Target(ElementType.METHOD)
20
@Documented
21
@API(status = EXPERIMENTAL, since = "1.11")
22
public @interface BeforeSuite {
23
}
24
```
25

26
**Method Requirements:**
27
- Must be `static`
28
- Must return `void`
29
- Must not be `private`
30
- May have any visibility (public, protected, package-private)
31

32
**Usage Examples:**
33

34
```java
35
@Suite
36
@SelectPackages("com.example.integration")
37
public class IntegrationTestSuite {
38
    
39
    @BeforeSuite
40
    static void setupDatabase() {
41
        System.setProperty("test.database.url", "jdbc:h2:mem:testdb");
42
        DatabaseTestUtil.initializeSchema();
43
    }
44
    
45
    @BeforeSuite
46
    static void setupHttpClient() {
47
        HttpClientTestUtil.configureTestClient();
48
    }
49
}
50

51
// Inheritance example
52
public abstract class BaseTestSuite {
53
    @BeforeSuite
54
    protected static void baseSetup() {
55
        System.out.println("Base suite setup");
56
    }
57
}
58

59
@Suite
60
@SelectClasses(MyTest.class)
61
public class ConcreteTestSuite extends BaseTestSuite {
62
    @BeforeSuite
63
    static void concreteSetup() {
64
        System.out.println("Concrete suite setup");
65
    }
66
    // Both baseSetup() and concreteSetup() will execute
67
}
68
```
69

70
### @AfterSuite Annotation
71

72
Signals that the annotated method should be executed after all tests in the current test suite.
73

74
```java { .api }
75
/**
76
 * Signals that the annotated method should be executed after all tests
77
 * in the current test suite.
78
 * 
79
 * Methods must be static, void, and not private.
80
 * Supports inheritance - superclass methods execute after subclass methods.
81
 */
82
@Retention(RetentionPolicy.RUNTIME)
83
@Target(ElementType.METHOD)
84
@Documented
85
@API(status = EXPERIMENTAL, since = "1.11")
86
public @interface AfterSuite {
87
}
88
```
89

90
**Method Requirements:**
91
- Must be `static`
92
- Must return `void`  
93
- Must not be `private`
94
- May have any visibility (public, protected, package-private)
95

96
**Usage Examples:**
97

98
```java
99
@Suite
100
@SelectPackages("com.example.integration")
101
public class IntegrationTestSuite {
102
    
103
    @BeforeSuite
104
    static void setupResources() {
105
        DatabaseTestUtil.initializeSchema();
106
        MessageQueueTestUtil.startEmbeddedBroker();
107
    }
108
    
109
    @AfterSuite
110
    static void cleanupResources() {
111
        MessageQueueTestUtil.stopEmbeddedBroker();
112
        DatabaseTestUtil.cleanupSchema();
113
    }
114
}
115

116
// Multiple cleanup methods
117
@Suite
118
@SelectTags("performance")
119
public class PerformanceTestSuite {
120
    
121
    @AfterSuite
122
    static void generateReport() {
123
        PerformanceReportGenerator.generateReport();
124
    }
125
    
126
    @AfterSuite
127
    static void cleanupTempFiles() {
128
        TestFileUtil.cleanupTempDirectory();
129
    }
130
}
131
```
132

133
## Lifecycle Execution Order
134

135
### Multiple Methods in Same Class
136

137
When multiple `@BeforeSuite` or `@AfterSuite` methods exist in the same class:
138
- Execution order is deterministic but not obvious
139
- Do not rely on specific ordering between methods in the same class
140
- Use method dependencies or combine logic into a single method if order matters
141

142
### Inheritance Hierarchy
143

144
For inherited lifecycle methods:
145
- **@BeforeSuite**: Superclass methods execute before subclass methods
146
- **@AfterSuite**: Subclass methods execute before superclass methods (reverse order)
147

148
```java
149
public abstract class BaseTestSuite {
150
    @BeforeSuite
151
    static void baseSetup() {
152
        System.out.println("1. Base setup");
153
    }
154
    
155
    @AfterSuite
156
    static void baseCleanup() {
157
        System.out.println("4. Base cleanup");
158
    }
159
}
160

161
@Suite
162
@SelectClasses(MyTest.class)
163
public class ConcreteTestSuite extends BaseTestSuite {
164
    @BeforeSuite
165
    static void concreteSetup() {
166
        System.out.println("2. Concrete setup");
167
    }
168
    
169
    @AfterSuite
170
    static void concreteCleanup() {
171
        System.out.println("3. Concrete cleanup");
172
    }
173
}
174
// Execution order: 1 -> 2 -> [tests] -> 3 -> 4
175
```
176

177
## Best Practices
178

179
### Resource Management
180

181
```java
182
@Suite
183
@SelectPackages("com.example.database")
184
public class DatabaseTestSuite {
185
    
186
    private static TestDatabase testDatabase;
187
    
188
    @BeforeSuite
189
    static void startDatabase() {
190
        testDatabase = new TestDatabase();
191
        testDatabase.start();
192
        testDatabase.loadTestData();
193
    }
194
    
195
    @AfterSuite
196
    static void stopDatabase() {
197
        if (testDatabase != null) {
198
            testDatabase.stop();
199
        }
200
    }
201
}
202
```
203

204
### Exception Handling
205

206
```java
207
@Suite
208
@SelectTags("integration")  
209
public class IntegrationTestSuite {
210
    
211
    @BeforeSuite
212
    static void setupExternalServices() {
213
        try {
214
            ExternalServiceTestUtil.startMockServices();
215
        } catch (Exception e) {
216
            throw new RuntimeException("Failed to start external services", e);
217
        }
218
    }
219
    
220
    @AfterSuite
221
    static void cleanupExternalServices() {
222
        try {
223
            ExternalServiceTestUtil.stopMockServices();
224
        } catch (Exception e) {
225
            // Log but don't throw - allow other cleanup to proceed
226
            System.err.println("Warning: Failed to stop external services: " + e.getMessage());
227
        }
228
    }
229
}
230
```
231

232
### Configuration and State
233

234
```java
235
@Suite
236
@SelectClasses({SecurityTest.class, AuthenticationTest.class})
237
public class SecurityTestSuite {
238
    
239
    @BeforeSuite
240
    static void configureSecurityContext() {
241
        System.setProperty("security.test.mode", "true");
242
        SecurityTestUtil.installTestSecurityManager();
243
    }
244
    
245
    @AfterSuite
246
    static void restoreSecurityContext() {
247
        SecurityTestUtil.uninstallTestSecurityManager();
248
        System.clearProperty("security.test.mode");
249
    }
250
}