0
# Pulsar TestMocks
1

2
Mock implementations and test utilities for Apache Pulsar components, providing lightweight alternatives to ZooKeeper and BookKeeper for isolated unit testing. This library enables developers to test Pulsar-dependent code without requiring external distributed services.
3

4
## Package Information
5

6
- **Package Name**: testmocks
7
- **Group ID**: org.apache.pulsar
8
- **Language**: Java
9
- **Version**: 4.0.6
10
- **Installation**: Include as Maven dependency in your project
11

12
```xml
13
<dependency>
14
    <groupId>org.apache.pulsar</groupId>
15
    <artifactId>testmocks</artifactId>
16
    <version>4.0.6</version>
17
    <scope>test</scope>
18
</dependency>
19
```
20

21
## Core Imports
22

23
```java
24
import org.apache.zookeeper.MockZooKeeper;
25
import org.apache.zookeeper.MockZooKeeperSession;
26
import org.apache.bookkeeper.client.PulsarMockBookKeeper;
27
import org.apache.bookkeeper.client.BookKeeperTestClient;
28
```
29

30
## Basic Usage
31

32
### ZooKeeper Mocking
33

34
```java
35
import org.apache.zookeeper.MockZooKeeper;
36
import org.apache.zookeeper.CreateMode;
37
import org.apache.zookeeper.ZooDefs;
38

39
// Create a mock ZooKeeper instance
40
MockZooKeeper mockZk = MockZooKeeper.newInstance();
41

42
// Use it like a real ZooKeeper client
43
mockZk.create("/test", "data".getBytes(), ZooDefs.Ids.OPEN_ACL_UNSAFE, CreateMode.PERSISTENT);
44
byte[] data = mockZk.getData("/test", null, null);
45
```
46

47
### BookKeeper Mocking
48

49
```java
50
import org.apache.bookkeeper.client.PulsarMockBookKeeper;
51
import org.apache.bookkeeper.client.LedgerHandle;
52
import org.apache.bookkeeper.client.api.DigestType;
53

54
// Create mock BookKeeper with ordered executor
55
PulsarMockBookKeeper mockBk = new PulsarMockBookKeeper(executor);
56

57
// Create and use ledgers
58
LedgerHandle ledger = mockBk.createLedger(DigestType.CRC32, "password".getBytes());
59
ledger.addEntry("entry data".getBytes());
60
ledger.close();
61
```
62

63
## Architecture
64

65
The testmocks library is organized into three main packages that mirror the Apache ecosystem structure:
66

67
- **org.apache.zookeeper**: Mock ZooKeeper implementations for coordination service testing
68
  - MockZooKeeper: Complete in-memory ZooKeeper implementation with failure injection
69
  - MockZooKeeperSession: Session-based wrapper for multi-client testing scenarios
70
  
71
- **org.apache.bookkeeper.client**: Mock BookKeeper client implementations for distributed ledger testing
72
  - PulsarMockBookKeeper: In-memory BookKeeper client with full API support
73
  - PulsarMockLedgerHandle: Mock ledger handle with ReadHandle interface support
74
  - PulsarMockReadHandle: Separate read-only handle implementation
75
  - BookKeeperTestClient: Enhanced client with internal component access
76
  - TestStatsProvider: In-memory statistics collection and analysis
77
  
78
- **org.apache.bookkeeper.test**: Testing utilities and server components for comprehensive BookKeeper testing
79
  - ServerTester: Server testing infrastructure with auto-recovery management
80
  - MockUncleanShutdownDetection: Shutdown lifecycle testing utilities
81

82
### Key Design Patterns
83

84
**Drop-in Replacement**: All mock implementations extend or implement the same interfaces as their real counterparts, enabling seamless substitution in existing code.
85

86
**Failure Injection**: Comprehensive failure injection capabilities allow testing of error handling and recovery scenarios without complex test infrastructure.
87

88
**Statistics Collection**: Built-in metrics collection enables performance testing and behavior analysis without external monitoring systems.
89

90
**Interceptor Pattern**: Read operation interception enables advanced testing scenarios like data transformation and latency simulation.
91

92
**Session Management**: Session-based testing supports multi-client scenarios and isolation between test cases.
93

94
This structure enables comprehensive testing of Pulsar components without requiring external distributed services, while maintaining full API compatibility and providing enhanced testing capabilities.
95

96
## Capabilities
97

98
### ZooKeeper Mocking
99

100
Complete ZooKeeper API implementation with in-memory storage, session management, and configurable failure injection for testing coordination service interactions.
101

102
```java { .api }
103
class MockZooKeeper extends ZooKeeper {
104
    static MockZooKeeper newInstance();
105
    static MockZooKeeper newInstance(int readOpDelayMs);
106
    String create(String path, byte[] data, List<ACL> acl, CreateMode createMode);
107
    byte[] getData(String path, Watcher watcher, Stat stat);
108
    List<String> getChildren(String path, Watcher watcher);
109
    void setData(String path, byte[] data, int version);
110
    void delete(String path, int version);
111
    void failConditional(KeeperException.Code rc, BiPredicate<Op, String> predicate);
112
    void setAlwaysFail(KeeperException.Code rc);
113
}
114

115
class MockZooKeeperSession extends ZooKeeper {
116
    static MockZooKeeperSession newInstance(MockZooKeeper mockZooKeeper);
117
    static MockZooKeeperSession newInstance(MockZooKeeper mockZooKeeper, boolean closeMockZooKeeperOnClose);
118
}
119
```
120

121
[ZooKeeper Mocking](./zookeeper-mocking.md)
122

123
### BookKeeper Client Mocking
124

125
In-memory BookKeeper client implementation with full ledger lifecycle management, read/write operations, and configurable testing behaviors.
126

127
```java { .api }
128
class PulsarMockBookKeeper extends BookKeeper {
129
    PulsarMockBookKeeper(OrderedExecutor orderedExecutor);
130
    LedgerHandle createLedger(DigestType digestType, byte[] passwd);
131
    LedgerHandle createLedger(int ensSize, int writeQuorumSize, int ackQuorumSize, DigestType digestType, byte[] passwd);
132
    void asyncOpenLedger(long lId, DigestType digestType, byte[] passwd, OpenCallback cb, Object ctx);
133
    void asyncDeleteLedger(long lId, DeleteCallback cb, Object ctx);
134
    OpenBuilder newOpenLedgerOp();
135
    DeleteBuilder newDeleteLedgerOp();
136
    void setReadHandleInterceptor(PulsarMockReadHandleInterceptor readHandleInterceptor);
137
    void failAfter(int steps, int rc);
138
    void addEntryDelay(long delay, TimeUnit unit);
139
}
140

141
interface PulsarMockReadHandleInterceptor {
142
    CompletableFuture<LedgerEntries> interceptReadAsync(long ledgerId, long firstEntry, long lastEntry, LedgerEntries entries);
143
}
144
```
145

146
[BookKeeper Client Mocking](./bookkeeper-client-mocking.md)
147

148
### BookKeeper Testing Utilities
149

150
Enhanced testing components including specialized test clients, in-memory stats providers, and server testing infrastructure for comprehensive BookKeeper testing scenarios.
151

152
```java { .api }
153
class BookKeeperTestClient extends BookKeeper {
154
    BookKeeperTestClient(ClientConfiguration conf);
155
    BookKeeperTestClient(ClientConfiguration conf, TestStatsProvider statsProvider);
156
    ZooKeeper getZkHandle();
157
    BookieClient getBookieClient();
158
    void waitForReadOnlyBookie(BookieId id);
159
}
160

161
class TestStatsProvider implements StatsProvider {
162
    TestStatsLogger getStatsLogger(String scope);
163
    TestOpStatsLogger getOpStatsLogger(String path);
164
    TestCounter getCounter(String path);
165
    void forEachOpStatLogger(BiConsumer<String, TestOpStatsLogger> f);
166
    void clear();
167
}
168
```
169

170
[BookKeeper Testing Utilities](./bookkeeper-testing-utilities.md)
171

172
### BookKeeper Server Testing
173

174
Server-side testing infrastructure including server setup, auto-recovery management, and comprehensive testing utilities for integration testing scenarios.
175

176
```java { .api }
177
class ServerTester {
178
    ServerTester(ServerConfiguration conf);
179
    ServerTester(ServerConfiguration conf, Bookie b);
180
    void startAutoRecovery();
181
    void stopAutoRecovery();
182
    Auditor getAuditor();
183
    ReplicationWorker getReplicationWorker();
184
    BookieServer getServer();
185
    TestStatsProvider getStatsProvider();
186
    BookieSocketAddress getAddress();
187
    void shutdown();
188
}
189

190
static class MockUncleanShutdownDetection implements UncleanShutdownDetection {
191
    void registerStartUp();
192
    void registerCleanShutdown();
193
    boolean lastShutdownWasUnclean();
194
    boolean getStartRegistered();
195
    boolean getShutdownRegistered();
196
}
197
```
198

199
[BookKeeper Server Testing](./bookkeeper-server-testing.md)
200

201
## Error Handling
202

203
All mock implementations can be configured to simulate various failure scenarios:
204

205
- **Network failures**: Configurable delays and timeouts
206
- **Service failures**: Specific error codes and exception injection
207
- **State transitions**: Simulated connection state changes
208
- **Resource exhaustion**: Controlled failure after specified operations
209

210
This enables comprehensive testing of error handling and recovery logic in client applications.