0
# Apache Log4j Core Test Library
1

2
Apache Log4j Core Test Library is a comprehensive testing infrastructure for Apache Log4j core implementation. It provides essential test utilities, mock servers, JUnit integration, custom appenders, and testing helpers that enable thorough testing of Log4j-based applications and extensions.
3

4
## Package Information
5

6
- **Package Name**: log4j-core-test
7
- **Package Type**: maven
8
- **Language**: Java
9
- **Installation**: Add dependency to Maven pom.xml:
10

11
```xml
12
<dependency>
13
    <groupId>org.apache.logging.log4j</groupId>
14
    <artifactId>log4j-core-test</artifactId>
15
    <version>2.25.1</version>
16
    <scope>test</scope>
17
</dependency>
18
```
19

20
## Core Imports
21

22
```java
23
// Test appenders
24
import org.apache.logging.log4j.core.test.appender.ListAppender;
25
import org.apache.logging.log4j.core.test.appender.BlockingAppender;
26

27
// JUnit 4 integration
28
import org.apache.logging.log4j.core.test.junit.LoggerContextRule;
29

30
// JUnit 5 integration
31
import org.apache.logging.log4j.core.test.junit.LoggerContextSource;
32
import org.apache.logging.log4j.core.test.junit.Named;
33

34
// Utility classes
35
import org.apache.logging.log4j.core.test.AvailablePortFinder;
36
import org.apache.logging.log4j.core.test.CoreLoggerContexts;
37

38
// Common Log4j classes used with test library
39
import org.apache.logging.log4j.Logger;
40
import org.apache.logging.log4j.LogEvent;
41
```
42

43
## Basic Usage
44

45
```java
46
import org.apache.logging.log4j.Logger;
47
import org.apache.logging.log4j.LogEvent;
48
import org.apache.logging.log4j.core.test.appender.ListAppender;
49
import org.apache.logging.log4j.core.test.junit.LoggerContextRule;
50
import org.junit.Rule;
51
import org.junit.Test;
52
import java.util.List;
53

54
import static org.junit.Assert.assertEquals;
55

56
public class MyLoggerTest {
57
    
58
    @Rule
59
    public LoggerContextRule context = new LoggerContextRule("log4j2-test.xml");
60
    
61
    @Test
62
    public void testLogging() {
63
        // Get the ListAppender configured in log4j2-test.xml
64
        ListAppender listAppender = context.getListAppender("TestAppender");
65
        
66
        // Perform logging operations
67
        Logger logger = context.getLogger();
68
        logger.info("Test message");
69
        
70
        // Verify logged events
71
        List<LogEvent> events = listAppender.getEvents();
72
        assertEquals(1, events.size());
73
        assertEquals("Test message", events.get(0).getMessage().getFormattedMessage());
74
    }
75
}
76
```
77

78
## Architecture
79

80
The Log4j Core Test Library is organized around several key components:
81

82
- **Test Appenders**: Specialized appenders for capturing and verifying log events during testing
83
- **JUnit Integration**: TestRules and Extensions for both JUnit 4 and JUnit 5 integration
84
- **Mock Servers**: Dummy network servers (SMTP, Syslog) for testing network appenders
85
- **Hamcrest Matchers**: Custom matchers for file-based assertions
86
- **Utility Classes**: Port management, compilation helpers, profiler integration
87
- **Test Categories**: Organized categorization for different types of tests
88

89
## Capabilities
90

91
### Test Appenders
92

93
Core test appenders for capturing and analyzing log events, including the primary ListAppender for event collection and specialized appenders for testing failure scenarios and threading behavior.
94

95
```java { .api }
96
public class ListAppender extends AbstractAppender {
97
    public List<LogEvent> getEvents();
98
    public List<String> getMessages();
99
    public List<byte[]> getData();
100
    public ListAppender clear();
101
    public static ListAppender getListAppender(String name);
102
}
103

104
public class BlockingAppender extends AbstractAppender {
105
    public static BlockingAppender createAppender(String name);
106
    public volatile boolean running;
107
}
108
```
109

110
[Test Appenders](./test-appenders.md)
111

112
### JUnit Integration
113

114
Comprehensive JUnit 4 and JUnit 5 integration providing TestRules and Extensions for LoggerContext management, configuration loading, and test lifecycle integration.
115

116
```java { .api }
117
public class LoggerContextRule implements TestRule, LoggerContextAccessor {
118
    public <T extends Appender> T getAppender(String name);
119
    public <T extends Appender> T getRequiredAppender(String name, Class<T> cls);
120
    public ListAppender getListAppender(String name);
121
    public Logger getLogger();
122
    public Configuration getConfiguration();
123
    public LoggerContext getLoggerContext();
124
    public void reconfigure();
125
}
126

127
@Target({ElementType.TYPE, ElementType.METHOD})
128
@Retention(RetentionPolicy.RUNTIME)
129
public @interface LoggerContextSource {
130
    String value();
131
    ReconfigurationPolicy reconfigure() default ReconfigurationPolicy.NEVER;
132
    long timeout() default 0;
133
    TimeUnit unit() default TimeUnit.SECONDS;
134
}
135
```
136

137
[JUnit Integration](./junit-integration.md)
138

139
### Mock Network Servers
140

141
Mock SMTP and Syslog servers for testing network appenders, supporting TCP, UDP, and TLS protocols with message capture and verification capabilities.
142

143
```java { .api }
144
public class SimpleSmtpServer implements Runnable {
145
    public static SimpleSmtpServer start();
146
    public static SimpleSmtpServer start(int port);
147
    public synchronized boolean isStopped();
148
    public synchronized void stop();
149
    public synchronized Iterator<SmtpMessage> getReceivedEmail();
150
    public synchronized int getReceivedEmailSize();
151
}
152

153
public abstract class MockSyslogServer extends Thread {
154
    public abstract int getLocalPort();
155
    public void shutdown();
156
    public int getNumberOfReceivedMessages();
157
    public List<String> getMessageList();
158
}
159
```
160

161
[Mock Servers](./mock-servers.md)
162

163
### Testing Utilities
164

165
Essential utilities for test infrastructure including port management, system property handling, logger context lifecycle management, and compilation helpers.
166

167
```java { .api }
168
public final class AvailablePortFinder {
169
    public static int getNextAvailable();
170
    public static int getNextAvailable(int fromPort);
171
    public static boolean available(int port);
172
    public static final int MIN_PORT_NUMBER = 1100;
173
    public static final int MAX_PORT_NUMBER = 65535;
174
}
175

176
public class SystemPropertyTestRule implements TestRule {
177
    public static SystemPropertyTestRule create(String name, String value);
178
    public Statement apply(Statement base, Description description);
179
    public String getName();
180
    public String getValue();
181
}
182

183
public class CoreLoggerContexts {
184
    public static void stopLoggerContext();
185
    public static void stopLoggerContext(boolean currentContext);
186
    public static void stopLoggerContext(boolean currentContext, File checkFilePresence);
187
}
188
```
189

190
[Testing Utilities](./testing-utilities.md)
191

192
### Hamcrest Matchers
193

194
Custom Hamcrest matchers for file-based assertions and Map testing, providing fluent assertion APIs for common testing scenarios.
195

196
```java { .api }
197
public final class FileMatchers {
198
    public static Matcher<File> exists();
199
    public static Matcher<File> hasLength(Matcher<Long> lengthMatcher);
200
    public static Matcher<File> isEmpty();
201
    public static Matcher<File> lastModified(Matcher<Long> lastModifiedMatcher);
202
    public static Matcher<File> hasFiles();
203
    public static Matcher<File> hasName(Matcher<String> nameMatcher);
204
}
205
```
206

207
[Hamcrest Matchers](./hamcrest-matchers.md)
208

209
### Test Categories
210

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

213
```java { .api }
214
public interface AsyncLoggers {}
215
public interface PerformanceTests {}
216
public interface Appenders {}
217
public interface Configurations {}
218
public interface Layouts {}
219
public interface Scripts {}
220
```
221

222
[Test Categories](./test-categories.md)
223

224
## Types
225

226
```java { .api }
227
public enum ReconfigurationPolicy {
228
    NEVER, BEFORE_EACH, AFTER_EACH
229
}
230

231
@Target(ElementType.PARAMETER)
232
@Retention(RetentionPolicy.RUNTIME)
233
public @interface Named {
234
    String value();
235
}
236

237
public class TestMarkers {
238
    public static final Marker LIFE_CYCLE;
239
    public static final Marker TEST;
240
    public static final Marker TEST_RULE;
241
    public static final Marker TEST_RULE_LIFE_CYCLE;
242
}
243
```