0
# Test Categories
1

2
JUnit test category interfaces for organizing and running specific types of tests, including performance tests, async logger tests, and component-specific test groups.
3

4
## Capabilities
5

6
### Core Test Categories
7

8
Category interfaces for organizing different types of Log4j tests using JUnit's `@Category` annotation.
9

10
```java { .api }
11
/**
12
 * Category for AsyncLogger tests that require LMAX Disruptor
13
 * Used to separate tests that need specific dependencies
14
 */
15
public interface AsyncLoggers {
16
    // Marker interface for JUnit categories
17
}
18

19
/**
20
 * Category for performance-sensitive tests
21
 * Used to separate resource-intensive tests from regular unit tests
22
 */
23
public interface PerformanceTests {
24
    // Marker interface for JUnit categories
25
}
26

27
/**
28
 * Category for appender-specific tests
29
 * Groups tests that focus on appender functionality
30
 */
31
public interface Appenders {
32
    // Marker interface for JUnit categories
33
}
34

35
/**
36
 * Category for configuration-related tests
37
 * Groups tests that focus on Log4j configuration loading and processing
38
 */
39
public interface Configurations {
40
    // Marker interface for JUnit categories
41
}
42

43
/**
44
 * Category for layout-specific tests
45
 * Groups tests that focus on message formatting and layout functionality
46
 */
47
public interface Layouts { 
48
    // Marker interface for JUnit categories
49
}
50

51
/**
52
 * Category for script-based tests
53
 * Groups tests that involve scripting functionality (Groovy, JavaScript, etc.)
54
 */
55
public interface Scripts {
56
    // Marker interface for JUnit categories
57
}
58
```
59

60
### JUnit 5 Tags
61

62
JUnit 5 tags for test organization and filtering.
63

64
```java { .api }
65
/**
66
 * Container for JUnit 5 tags used in Log4j testing
67
 */
68
public final class Tags {
69
    
70
    /**
71
     * Tag for async logger tests requiring LMAX Disruptor
72
     * Used with @Tag annotation in JUnit 5
73
     */
74
    public static final String ASYNC_LOGGERS = "async-loggers";
75
    
76
    /**
77
     * Tag for performance tests
78
     */
79
    public static final String PERFORMANCE = "performance";
80
    
81
    /**
82
     * Tag for integration tests
83
     */
84
    public static final String INTEGRATION = "integration";
85
    
86
    /**
87
     * Tag for functional tests
88
     */
89
    public static final String FUNCTIONAL = "functional";
90
}
91
```
92

93
## Usage Examples
94

95
### JUnit 4 Category Usage
96

97
```java
98
import org.apache.logging.log4j.core.test.categories.AsyncLoggers;
99
import org.apache.logging.log4j.core.test.categories.PerformanceTests;
100
import org.apache.logging.log4j.core.test.categories.Appenders;
101
import org.junit.Test;
102
import org.junit.experimental.categories.Category;
103

104
// Single category
105
@Category(AsyncLoggers.class)
106
public class AsyncLoggerTest {
107
    
108
    @Test
109
    public void testAsyncLogging() {
110
        // Test requires LMAX Disruptor dependency
111
        // Uses AsyncLogger functionality
112
    }
113
}
114

115
// Multiple categories
116
@Category({Appenders.class, PerformanceTests.class})
117
public class HighPerformanceAppenderTest {
118
    
119
    @Test
120
    public void testAppenderThroughput() {
121
        // Performance test for appender throughput
122
    }
123
}
124

125
// Method-level categorization
126
public class MixedAppenderTest {
127
    
128
    @Test
129
    @Category(Appenders.class)
130
    public void testBasicAppenderFunctionality() {
131
        // Basic appender test
132
    }
133
    
134
    @Test
135
    @Category({Appenders.class, PerformanceTests.class})
136
    public void testAppenderPerformance() {
137
        // Performance-sensitive appender test
138
    }
139
}
140
```
141

142
### JUnit 5 Tag Usage
143

144
```java
145
import org.apache.logging.log4j.core.test.junit.Tags;
146
import org.junit.jupiter.api.Tag;
147
import org.junit.jupiter.api.Test;
148

149
// Class-level tagging
150
@Tag(Tags.ASYNC_LOGGERS)
151
class AsyncLoggerTest {
152
    
153
    @Test
154
    void testAsyncLogging() {
155
        // Async logger test
156
    }
157
}
158

159
// Method-level tagging
160
class MixedLoggerTest {
161
    
162
    @Test
163
    @Tag(Tags.PERFORMANCE)
164
    void testLoggingPerformance() {
165
        // Performance test
166
    }
167
    
168
    @Test
169
    @Tag(Tags.INTEGRATION)
170
    void testDatabaseIntegration() {
171
        // Integration test
172
    }
173
}
174

175
// Multiple tags
176
@Tag(Tags.ASYNC_LOGGERS)
177
@Tag(Tags.PERFORMANCE)
178
class AsyncPerformanceTest {
179
    
180
    @Test
181
    void testAsyncLoggerThroughput() {
182
        // Combined async + performance test
183
    }
184
}
185
```
186

187
### Maven Surefire Configuration
188

189
Configure Maven Surefire plugin to run specific test categories:
190

191
```xml
192
<!-- Run only basic tests (exclude performance and async) -->
193
<plugin>
194
    <groupId>org.apache.maven.plugins</groupId>
195
    <artifactId>maven-surefire-plugin</artifactId>
196
    <configuration>
197
        <excludedGroups>
198
            org.apache.logging.log4j.core.test.categories.PerformanceTests,
199
            org.apache.logging.log4j.core.test.categories.AsyncLoggers
200
        </excludedGroups>
201
    </configuration>
202
</plugin>
203

204
<!-- Run only AsyncLogger tests -->
205
<plugin>
206
    <groupId>org.apache.maven.plugins</groupId>
207
    <artifactId>maven-surefire-plugin</artifactId>
208
    <configuration>
209
        <groups>org.apache.logging.log4j.core.test.categories.AsyncLoggers</groups>
210
    </configuration>
211
</plugin>
212

213
<!-- JUnit 5 tag configuration -->
214
<plugin>
215
    <groupId>org.apache.maven.plugins</groupId>
216
    <artifactId>maven-surefire-plugin</artifactId>
217
    <configuration>
218
        <groups>async-loggers</groups>
219
        <excludedGroups>performance</excludedGroups>
220
    </configuration>
221
</plugin>
222
```
223

224
### Gradle Test Configuration
225

226
Configure Gradle to run specific test categories:
227

228
```gradle
229
// JUnit 4 categories
230
test {
231
    useJUnit {
232
        includeCategories 'org.apache.logging.log4j.core.test.categories.Appenders'
233
        excludeCategories 'org.apache.logging.log4j.core.test.categories.PerformanceTests'
234
    }
235
}
236

237
// Separate task for performance tests
238
task performanceTest(type: Test) {
239
    useJUnit {
240
        includeCategories 'org.apache.logging.log4j.core.test.categories.PerformanceTests'
241
    }
242
}
243

244
// JUnit 5 tags
245
test {
246
    useJUnitPlatform {
247
        includeTags 'async-loggers'
248
        excludeTags 'performance'
249
    }
250
}
251
```
252

253
## Category Usage Patterns
254

255
### Component-Specific Testing
256

257
```java
258
// Appender tests
259
@Category(Appenders.class)
260
public class FileAppenderTest {
261
    // File appender specific tests
262
}
263

264
@Category(Appenders.class)
265
public class DatabaseAppenderTest {
266
    // Database appender specific tests
267
}
268

269
// Layout tests
270
@Category(Layouts.class)
271
public class PatternLayoutTest {
272
    // Pattern layout specific tests
273
}
274
```
275

276
### Environment-Specific Testing
277

278
```java
279
// Performance tests for CI/local development separation
280
@Category(PerformanceTests.class)
281
public class ThroughputBenchmarkTest {
282
    
283
    @Test
284
    public void measureLoggingThroughput() {
285
        // Long-running performance test
286
        // Excluded from regular CI builds
287
    }
288
}
289

290
// Async tests requiring specific dependencies
291
@Category(AsyncLoggers.class)
292
public class DisruptorIntegrationTest {
293
    
294
    @Test
295
    public void testWithDisruptor() {
296
        // Requires LMAX Disruptor on classpath
297
        // May be excluded if dependency not available
298
    }
299
}
300
```
301

302
### Build Pipeline Integration
303

304
```java
305
// Quick smoke tests
306
@Category({Appenders.class, Layouts.class})
307
public class SmokeTest {
308
    // Fast tests for initial pipeline stages
309
}
310

311
// Comprehensive integration tests  
312
@Category({AsyncLoggers.class, PerformanceTests.class, Scripts.class})
313
public class FullIntegrationTest {
314
    // Comprehensive tests for later pipeline stages
315
}
316
```
317

318
### Mixed Category Strategies
319

320
```java
321
public class ComplexAppenderTest {
322
    
323
    @Test
324
    @Category(Appenders.class)
325
    public void testBasicFunctionality() {
326
        // Basic appender test - runs in all builds
327
    }
328
    
329
    @Test
330
    @Category({Appenders.class, PerformanceTests.class})
331
    public void testHighThroughput() {
332
        // Performance test - only in performance builds
333
    }
334
    
335
    @Test
336
    @Category({Appenders.class, AsyncLoggers.class})
337
    public void testAsyncAppender() {
338
        // Async test - only when Disruptor available
339
    }
340
    
341
    @Test
342
    @Category({Appenders.class, Scripts.class})
343
    public void testScriptConfiguration() {
344
        // Script test - only when scripting engines available
345
    }
346
}
347
```
348

349
## Best Practices
350

351
### Category Organization
352

353
1. **Single Responsibility**: Each category should represent a clear testing concern
354
2. **Dependency-based**: Use categories to separate tests with different dependency requirements
355
3. **Performance Separation**: Isolate performance tests from regular unit tests
356
4. **Environment Matching**: Align categories with build pipeline stages
357

358
### Build Configuration
359

360
1. **Default Exclusions**: Exclude performance and integration tests from default builds
361
2. **Specialized Profiles**: Create Maven profiles or Gradle tasks for specific categories
362
3. **CI Integration**: Use categories to create fast feedback loops in continuous integration
363
4. **Documentation**: Document which categories are expected to run in which environments