@omnitron-dev/testing 0.4.1 → 0.4.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (154) hide show
  1. package/dist/async/deferred.d.ts +15 -0
  2. package/dist/async/deferred.js +35 -0
  3. package/dist/async/deferred.js.map +1 -0
  4. package/dist/async/events.d.ts +32 -0
  5. package/dist/async/events.js +176 -0
  6. package/dist/async/events.js.map +1 -0
  7. package/dist/async/index.d.ts +5 -0
  8. package/dist/async/index.js +6 -0
  9. package/dist/async/index.js.map +1 -0
  10. package/dist/async/mock-timer.d.ts +19 -0
  11. package/dist/async/mock-timer.js +87 -0
  12. package/dist/async/mock-timer.js.map +1 -0
  13. package/dist/async/retry.d.ts +8 -0
  14. package/dist/async/retry.js +36 -0
  15. package/dist/async/retry.js.map +1 -0
  16. package/dist/async/wait.d.ts +10 -0
  17. package/dist/async/wait.js +35 -0
  18. package/dist/async/wait.js.map +1 -0
  19. package/dist/docker/database-manager.d.ts +22 -0
  20. package/dist/docker/database-manager.js +97 -0
  21. package/dist/docker/database-manager.js.map +1 -0
  22. package/dist/docker/docker-test-manager.d.ts +44 -0
  23. package/dist/docker/docker-test-manager.js +805 -0
  24. package/dist/docker/docker-test-manager.js.map +1 -0
  25. package/dist/docker/index.d.ts +4 -0
  26. package/dist/docker/index.js +4 -0
  27. package/dist/docker/index.js.map +1 -0
  28. package/dist/docker/redis-manager.d.ts +12 -0
  29. package/dist/docker/redis-manager.js +453 -0
  30. package/dist/docker/redis-manager.js.map +1 -0
  31. package/dist/docker/types.d.ts +103 -0
  32. package/dist/docker/types.js +2 -0
  33. package/dist/docker/types.js.map +1 -0
  34. package/dist/errors.d.ts +15 -0
  35. package/dist/errors.js +28 -0
  36. package/dist/errors.js.map +1 -0
  37. package/dist/helpers/assertions.d.ts +6 -0
  38. package/dist/helpers/assertions.js +37 -0
  39. package/dist/helpers/assertions.js.map +1 -0
  40. package/dist/helpers/console.d.ts +1 -0
  41. package/dist/helpers/console.js +23 -0
  42. package/dist/helpers/console.js.map +1 -0
  43. package/dist/helpers/index.d.ts +3 -0
  44. package/dist/helpers/index.js +4 -0
  45. package/dist/helpers/index.js.map +1 -0
  46. package/dist/helpers/temp-dir.d.ts +2 -0
  47. package/dist/helpers/temp-dir.js +13 -0
  48. package/dist/helpers/temp-dir.js.map +1 -0
  49. package/dist/index.d.ts +2 -0
  50. package/dist/index.js +2 -0
  51. package/dist/index.js.map +1 -1
  52. package/dist/performance/index.d.ts +2 -0
  53. package/dist/performance/index.js +3 -0
  54. package/dist/performance/index.js.map +1 -0
  55. package/dist/performance/memory-detector.d.ts +9 -0
  56. package/dist/performance/memory-detector.js +61 -0
  57. package/dist/performance/memory-detector.js.map +1 -0
  58. package/dist/performance/perf-timer.d.ts +9 -0
  59. package/dist/performance/perf-timer.js +49 -0
  60. package/dist/performance/perf-timer.js.map +1 -0
  61. package/dist/titan/container-utils.d.ts +20 -0
  62. package/dist/titan/container-utils.js +78 -0
  63. package/dist/titan/container-utils.js.map +1 -0
  64. package/dist/titan/database/database-testing.module.d.ts +81 -0
  65. package/dist/titan/database/database-testing.module.js +419 -0
  66. package/dist/titan/database/database-testing.module.js.map +1 -0
  67. package/dist/titan/database/index.d.ts +3 -0
  68. package/dist/titan/database/index.js +4 -0
  69. package/dist/titan/database/index.js.map +1 -0
  70. package/dist/titan/database/test-utilities.d.ts +31 -0
  71. package/dist/titan/database/test-utilities.js +145 -0
  72. package/dist/titan/database/test-utilities.js.map +1 -0
  73. package/dist/titan/index.d.ts +14 -0
  74. package/dist/titan/index.js +10 -0
  75. package/dist/titan/index.js.map +1 -0
  76. package/dist/titan/nexus/index.d.ts +3 -0
  77. package/dist/titan/nexus/index.js +4 -0
  78. package/dist/titan/nexus/index.js.map +1 -0
  79. package/dist/titan/nexus/mock-provider.d.ts +41 -0
  80. package/dist/titan/nexus/mock-provider.js +127 -0
  81. package/dist/titan/nexus/mock-provider.js.map +1 -0
  82. package/dist/titan/nexus/test-container.d.ts +120 -0
  83. package/dist/titan/nexus/test-container.js +559 -0
  84. package/dist/titan/nexus/test-container.js.map +1 -0
  85. package/dist/titan/nexus/test-utilities.d.ts +135 -0
  86. package/dist/titan/nexus/test-utilities.js +484 -0
  87. package/dist/titan/nexus/test-utilities.js.map +1 -0
  88. package/dist/titan/pm/index.d.ts +4 -0
  89. package/dist/titan/pm/index.js +4 -0
  90. package/dist/titan/pm/index.js.map +1 -0
  91. package/dist/titan/pm/mock-process-spawner.d.ts +60 -0
  92. package/dist/titan/pm/mock-process-spawner.js +321 -0
  93. package/dist/titan/pm/mock-process-spawner.js.map +1 -0
  94. package/dist/titan/pm/mock-spawner.d.ts +27 -0
  95. package/dist/titan/pm/mock-spawner.js +99 -0
  96. package/dist/titan/pm/mock-spawner.js.map +1 -0
  97. package/dist/titan/pm/test-process-manager.d.ts +49 -0
  98. package/dist/titan/pm/test-process-manager.js +188 -0
  99. package/dist/titan/pm/test-process-manager.js.map +1 -0
  100. package/dist/titan/redis-test-utils.d.ts +33 -0
  101. package/dist/titan/redis-test-utils.js +414 -0
  102. package/dist/titan/redis-test-utils.js.map +1 -0
  103. package/dist/titan/test-application.d.ts +21 -0
  104. package/dist/titan/test-application.js +90 -0
  105. package/dist/titan/test-application.js.map +1 -0
  106. package/dist/titan/test-fixtures.d.ts +97 -0
  107. package/dist/titan/test-fixtures.js +223 -0
  108. package/dist/titan/test-fixtures.js.map +1 -0
  109. package/dist/titan/test-mocks.d.ts +29 -0
  110. package/dist/titan/test-mocks.js +262 -0
  111. package/dist/titan/test-mocks.js.map +1 -0
  112. package/dist/titan/test-module.d.ts +46 -0
  113. package/dist/titan/test-module.js +120 -0
  114. package/dist/titan/test-module.js.map +1 -0
  115. package/package.json +41 -4
  116. package/src/async/README.md +336 -0
  117. package/src/async/deferred.ts +98 -0
  118. package/src/async/events.ts +386 -0
  119. package/src/async/index.ts +48 -0
  120. package/src/async/mock-timer.ts +220 -0
  121. package/src/async/retry.ts +118 -0
  122. package/src/async/wait.ts +151 -0
  123. package/src/docker/database-manager.ts +242 -0
  124. package/src/docker/docker-test-manager.ts +1186 -0
  125. package/src/docker/index.ts +48 -0
  126. package/src/docker/redis-manager.ts +738 -0
  127. package/src/docker/types.ts +216 -0
  128. package/src/errors.ts +31 -0
  129. package/src/helpers/assertions.ts +171 -0
  130. package/src/helpers/console.ts +74 -0
  131. package/src/helpers/index.ts +15 -0
  132. package/src/helpers/temp-dir.ts +50 -0
  133. package/src/index.ts +2 -0
  134. package/src/performance/index.ts +11 -0
  135. package/src/performance/memory-detector.ts +166 -0
  136. package/src/performance/perf-timer.ts +146 -0
  137. package/src/titan/container-utils.ts +128 -0
  138. package/src/titan/database/database-testing.module.ts +831 -0
  139. package/src/titan/database/index.ts +30 -0
  140. package/src/titan/database/test-utilities.ts +337 -0
  141. package/src/titan/index.ts +147 -0
  142. package/src/titan/nexus/index.ts +3 -0
  143. package/src/titan/nexus/mock-provider.ts +189 -0
  144. package/src/titan/nexus/test-container.ts +887 -0
  145. package/src/titan/nexus/test-utilities.ts +796 -0
  146. package/src/titan/pm/index.ts +22 -0
  147. package/src/titan/pm/mock-process-spawner.ts +481 -0
  148. package/src/titan/pm/mock-spawner.ts +156 -0
  149. package/src/titan/pm/test-process-manager.ts +345 -0
  150. package/src/titan/redis-test-utils.ts +566 -0
  151. package/src/titan/test-application.ts +154 -0
  152. package/src/titan/test-fixtures.ts +304 -0
  153. package/src/titan/test-mocks.ts +336 -0
  154. package/src/titan/test-module.ts +232 -0
@@ -0,0 +1,738 @@
1
+ /**
2
+ * Redis Test Manager
3
+ *
4
+ * Provides specialized helpers for creating and managing Redis containers
5
+ * in tests. Supports standalone Redis, Redis Cluster, and Redis Sentinel.
6
+ */
7
+
8
+ import { execFileSync } from 'child_process';
9
+ import { randomBytes } from 'crypto';
10
+ import { DockerTestManager } from './docker-test-manager.js';
11
+ import type {
12
+ DockerContainer,
13
+ RedisContainerOptions,
14
+ RedisClusterOptions,
15
+ RedisClusterContainers,
16
+ RedisSentinelOptions,
17
+ RedisSentinelContainers,
18
+ } from './types.js';
19
+
20
+ /**
21
+ * Redis Test Manager
22
+ *
23
+ * Provides convenient methods for creating Redis containers with various
24
+ * configurations: standalone, cluster, and sentinel.
25
+ *
26
+ * @example
27
+ * ```typescript
28
+ * // Standalone Redis
29
+ * const redis = await RedisTestManager.createRedisContainer();
30
+ *
31
+ * // Redis Cluster
32
+ * const cluster = await RedisTestManager.createRedisCluster({
33
+ * masterCount: 3,
34
+ * replicasPerMaster: 1,
35
+ * });
36
+ *
37
+ * // Redis Sentinel
38
+ * const sentinel = await RedisTestManager.createRedisSentinel({
39
+ * replicaCount: 2,
40
+ * sentinelCount: 3,
41
+ * });
42
+ * ```
43
+ */
44
+ export class RedisTestManager {
45
+ private static _dockerManager: DockerTestManager | null = null;
46
+
47
+ /**
48
+ * Get the Docker manager instance
49
+ * @private
50
+ */
51
+ private static getDockerManager(): DockerTestManager {
52
+ if (!RedisTestManager._dockerManager) {
53
+ RedisTestManager._dockerManager = DockerTestManager.getInstance();
54
+ }
55
+ return RedisTestManager._dockerManager;
56
+ }
57
+
58
+ /**
59
+ * Create a standalone Redis container
60
+ *
61
+ * @param options - Redis configuration options
62
+ * @returns Promise resolving to DockerContainer
63
+ *
64
+ * @example
65
+ * ```typescript
66
+ * const container = await RedisTestManager.createRedisContainer({
67
+ * password: 'mypass',
68
+ * maxMemory: '512mb',
69
+ * });
70
+ *
71
+ * const port = container.ports.get(6379)!;
72
+ * const connStr = `redis://:mypass@localhost:${port}/0`;
73
+ * ```
74
+ */
75
+ static async createRedisContainer(options?: RedisContainerOptions): Promise<DockerContainer> {
76
+ const port = options?.port || 'auto';
77
+ const password = options?.password;
78
+ const database = options?.database ?? 0;
79
+ const maxMemory = options?.maxMemory || '256mb';
80
+ const requirePass = options?.requirePass ?? Boolean(password);
81
+
82
+ const environment: Record<string, string> = {};
83
+ const command: string[] = ['redis-server'];
84
+
85
+ // Configure Redis settings
86
+ command.push('--maxmemory', maxMemory);
87
+ command.push('--maxmemory-policy', 'allkeys-lru');
88
+ command.push('--save', ''); // Disable RDB snapshots for tests
89
+ command.push('--appendonly', 'no'); // Disable AOF for tests
90
+
91
+ if (requirePass && password) {
92
+ command.push('--requirepass', password);
93
+ }
94
+
95
+ return RedisTestManager.getDockerManager().createContainer({
96
+ name: options?.name,
97
+ image: 'redis:7-alpine',
98
+ ports: { 6379: port },
99
+ environment,
100
+ command: command.join(' '),
101
+ healthcheck: {
102
+ test: password ? ['CMD', 'redis-cli', '-a', password, 'ping'] : ['CMD', 'redis-cli', 'ping'],
103
+ interval: '1s',
104
+ timeout: '3s',
105
+ retries: 5,
106
+ startPeriod: '2s',
107
+ },
108
+ waitFor: {
109
+ healthcheck: true,
110
+ timeout: 30000,
111
+ },
112
+ });
113
+ }
114
+
115
+ /**
116
+ * Create a Redis Cluster (3 masters + 3 replicas by default)
117
+ *
118
+ * @param options - Redis Cluster configuration options
119
+ * @returns Promise resolving to RedisClusterContainers
120
+ *
121
+ * @example
122
+ * ```typescript
123
+ * const cluster = await RedisTestManager.createRedisCluster({
124
+ * masterCount: 3,
125
+ * replicasPerMaster: 1,
126
+ * password: 'mypass',
127
+ * });
128
+ *
129
+ * // Use cluster nodes
130
+ * const nodes = cluster.nodes; // [{ host: '127.0.0.1', port: 12345 }, ...]
131
+ *
132
+ * // Cleanup when done
133
+ * await cluster.cleanup();
134
+ * ```
135
+ */
136
+ static async createRedisCluster(options?: RedisClusterOptions): Promise<RedisClusterContainers> {
137
+ const masterCount = options?.masterCount ?? 3;
138
+ const replicasPerMaster = options?.replicasPerMaster ?? 1;
139
+ const password = options?.password;
140
+ const networkName = options?.network || `redis-cluster-${randomBytes(8).toString('hex')}`;
141
+
142
+ // Create network
143
+ await RedisTestManager.getDockerManager()['ensureNetwork'](networkName);
144
+
145
+ const masters: DockerContainer[] = [];
146
+ const replicas: DockerContainer[] = [];
147
+ const nodes: Array<{ host: string; port: number }> = [];
148
+ const allocatedPorts: number[] = [];
149
+
150
+ // Extract unique ID from network name to ensure container names are unique
151
+ const networkId = networkName.split('-').pop() || randomBytes(4).toString('hex');
152
+
153
+ try {
154
+ // Create master nodes with dynamically allocated ports
155
+ for (let i = 0; i < masterCount; i++) {
156
+ // Use dynamic port allocation instead of fixed basePort to avoid conflicts
157
+ const port = await RedisTestManager.getDockerManager()['findAvailablePort']();
158
+ allocatedPorts.push(port);
159
+ const name = `redis-cluster-${networkId}-master-${i}`;
160
+
161
+ const command = [
162
+ 'redis-server',
163
+ '--cluster-enabled',
164
+ 'yes',
165
+ '--cluster-config-file',
166
+ 'nodes.conf',
167
+ '--cluster-node-timeout',
168
+ '5000',
169
+ '--appendonly',
170
+ 'no',
171
+ '--save',
172
+ '',
173
+ '--port',
174
+ '6379',
175
+ ];
176
+
177
+ if (password) {
178
+ command.push('--requirepass', password);
179
+ command.push('--masterauth', password);
180
+ }
181
+
182
+ const container = await RedisTestManager.getDockerManager().createContainer({
183
+ name,
184
+ image: 'redis:7-alpine',
185
+ ports: { 6379: port },
186
+ networks: [networkName],
187
+ command: command.join(' '),
188
+ healthcheck: {
189
+ test: password ? ['CMD', 'redis-cli', '-a', password, 'ping'] : ['CMD', 'redis-cli', 'ping'],
190
+ interval: '1s',
191
+ timeout: '3s',
192
+ retries: 5,
193
+ startPeriod: '2s',
194
+ },
195
+ waitFor: {
196
+ healthcheck: true,
197
+ timeout: 30000,
198
+ },
199
+ });
200
+
201
+ masters.push(container);
202
+ nodes.push({ host: container.host, port });
203
+ }
204
+
205
+ // Create replica nodes with dynamically allocated ports
206
+ for (let i = 0; i < masterCount * replicasPerMaster; i++) {
207
+ // Use dynamic port allocation
208
+ const port = await RedisTestManager.getDockerManager()['findAvailablePort']();
209
+ allocatedPorts.push(port);
210
+ const name = `redis-cluster-${networkId}-replica-${i}`;
211
+
212
+ const command = [
213
+ 'redis-server',
214
+ '--cluster-enabled',
215
+ 'yes',
216
+ '--cluster-config-file',
217
+ 'nodes.conf',
218
+ '--cluster-node-timeout',
219
+ '5000',
220
+ '--appendonly',
221
+ 'no',
222
+ '--save',
223
+ '',
224
+ '--port',
225
+ '6379',
226
+ ];
227
+
228
+ if (password) {
229
+ command.push('--requirepass', password);
230
+ command.push('--masterauth', password);
231
+ }
232
+
233
+ const container = await RedisTestManager.getDockerManager().createContainer({
234
+ name,
235
+ image: 'redis:7-alpine',
236
+ ports: { 6379: port },
237
+ networks: [networkName],
238
+ command: command.join(' '),
239
+ healthcheck: {
240
+ test: password ? ['CMD', 'redis-cli', '-a', password, 'ping'] : ['CMD', 'redis-cli', 'ping'],
241
+ interval: '1s',
242
+ timeout: '3s',
243
+ retries: 5,
244
+ startPeriod: '2s',
245
+ },
246
+ waitFor: {
247
+ healthcheck: true,
248
+ timeout: 30000,
249
+ },
250
+ });
251
+
252
+ replicas.push(container);
253
+ nodes.push({ host: container.host, port });
254
+ }
255
+
256
+ // Wait for all containers to be fully ready and connected to network
257
+ const preInitDelay = options?.preInitDelay ?? 5000;
258
+ await new Promise((resolve) => setTimeout(resolve, preInitDelay));
259
+
260
+ // Verify all nodes respond to PING before initializing cluster
261
+ const dockerPath = RedisTestManager.getDockerManager()['dockerPath'];
262
+ const allContainers = [...masters, ...replicas];
263
+ for (const container of allContainers) {
264
+ const maxPingRetries = 30;
265
+ for (let i = 0; i < maxPingRetries; i++) {
266
+ try {
267
+ const pingArgs = password
268
+ ? ['exec', container.name, 'redis-cli', '-a', password, 'ping']
269
+ : ['exec', container.name, 'redis-cli', 'ping'];
270
+ execFileSync(dockerPath, pingArgs, { stdio: 'pipe', timeout: 5000 });
271
+ break;
272
+ } catch {
273
+ if (i === maxPingRetries - 1) {
274
+ throw new Error(`Container ${container.name} not responding to redis-cli ping after ${maxPingRetries} attempts`);
275
+ }
276
+ await new Promise((r) => setTimeout(r, 1000));
277
+ }
278
+ }
279
+ }
280
+
281
+ // Initialize cluster
282
+ await RedisTestManager.initializeCluster(masters, replicas, password);
283
+
284
+ // Build NAT map for ioredis cluster connectivity
285
+ // Maps internal Docker IPs to external localhost:port addresses
286
+ const natMap: Record<string, { host: string; port: number }> = {};
287
+ for (const container of allContainers) {
288
+ if (container.internalIp) {
289
+ const hostPort = container.ports.get(6379);
290
+ if (hostPort) {
291
+ // Map internal IP:6379 to localhost:hostPort
292
+ natMap[`${container.internalIp}:6379`] = { host: 'localhost', port: hostPort };
293
+ }
294
+ }
295
+ }
296
+
297
+ return {
298
+ masters,
299
+ replicas,
300
+ network: networkName,
301
+ nodes,
302
+ natMap,
303
+ cleanup: async () => {
304
+ // Clean up containers first
305
+ await Promise.allSettled([...masters.map((c) => c.cleanup()), ...replicas.map((c) => c.cleanup())]);
306
+ // Then remove the network
307
+ try {
308
+ await RedisTestManager.getDockerManager()['removeNetwork'](networkName);
309
+ } catch (error) {
310
+ // Log but don't throw - network cleanup is best effort
311
+ console.warn(`Failed to remove network ${networkName}:`, error);
312
+ }
313
+ },
314
+ };
315
+ } catch (error) {
316
+ // Cleanup on failure - release allocated ports and clean up containers
317
+ allocatedPorts.forEach((port) => {
318
+ RedisTestManager.getDockerManager()['usedPorts'].delete(port);
319
+ });
320
+ await Promise.allSettled([
321
+ ...masters.map((c) =>
322
+ c.cleanup().catch((cleanupError) => {
323
+ // Log cleanup errors but don't fail the error flow - we're already handling a failure
324
+ console.error(`Failed to cleanup master container ${c.name}:`, cleanupError);
325
+ })
326
+ ),
327
+ ...replicas.map((c) =>
328
+ c.cleanup().catch((cleanupError) => {
329
+ // Log cleanup errors but don't fail the error flow - we're already handling a failure
330
+ console.error(`Failed to cleanup replica container ${c.name}:`, cleanupError);
331
+ })
332
+ ),
333
+ ]);
334
+ // Try to remove network on failure too
335
+ try {
336
+ await RedisTestManager.getDockerManager()['removeNetwork'](networkName);
337
+ } catch (networkError) {
338
+ // Log network cleanup errors but don't fail - network might be in use or already removed
339
+ console.error(`Failed to remove network ${networkName} during failure cleanup:`, networkError);
340
+ }
341
+ throw error;
342
+ }
343
+ }
344
+
345
+ /**
346
+ * Create Redis Sentinel setup (1 master + N replicas + M sentinels)
347
+ *
348
+ * @param options - Redis Sentinel configuration options
349
+ * @returns Promise resolving to RedisSentinelContainers
350
+ *
351
+ * @example
352
+ * ```typescript
353
+ * const sentinel = await RedisTestManager.createRedisSentinel({
354
+ * masterName: 'mymaster',
355
+ * replicaCount: 2,
356
+ * sentinelCount: 3,
357
+ * password: 'mypass',
358
+ * });
359
+ *
360
+ * // Use sentinel configuration
361
+ * const sentinelPorts = sentinel.sentinelPorts;
362
+ * const masterName = sentinel.masterName;
363
+ *
364
+ * // Cleanup when done
365
+ * await sentinel.cleanup();
366
+ * ```
367
+ */
368
+ static async createRedisSentinel(options?: RedisSentinelOptions): Promise<RedisSentinelContainers> {
369
+ const masterName = options?.masterName || 'mymaster';
370
+ const replicaCount = options?.replicaCount ?? 2;
371
+ const sentinelCount = options?.sentinelCount ?? 3;
372
+ const password = options?.password;
373
+ const networkName = options?.network || `redis-sentinel-${randomBytes(8).toString('hex')}`;
374
+
375
+ // Create network
376
+ await RedisTestManager.getDockerManager()['ensureNetwork'](networkName);
377
+
378
+ let master: DockerContainer | undefined;
379
+ const replicas: DockerContainer[] = [];
380
+ const sentinels: DockerContainer[] = [];
381
+ const sentinelPorts: number[] = [];
382
+ const allocatedPorts: number[] = [];
383
+
384
+ try {
385
+ // Create master with dynamic port allocation
386
+ const masterPort = await RedisTestManager.getDockerManager()['findAvailablePort']();
387
+ allocatedPorts.push(masterPort);
388
+ const command = ['redis-server', '--appendonly', 'no', '--save', ''];
389
+
390
+ if (password) {
391
+ command.push('--requirepass', password);
392
+ command.push('--masterauth', password);
393
+ }
394
+
395
+ master = await RedisTestManager.getDockerManager().createContainer({
396
+ name: `redis-sentinel-master`,
397
+ image: 'redis:7-alpine',
398
+ ports: { 6379: masterPort },
399
+ networks: [networkName],
400
+ command: command.join(' '),
401
+ healthcheck: {
402
+ test: password ? ['CMD', 'redis-cli', '-a', password, 'ping'] : ['CMD', 'redis-cli', 'ping'],
403
+ interval: '1s',
404
+ timeout: '3s',
405
+ retries: 5,
406
+ },
407
+ waitFor: {
408
+ healthcheck: true,
409
+ timeout: 30000,
410
+ },
411
+ });
412
+
413
+ // Create replicas
414
+ for (let i = 0; i < replicaCount; i++) {
415
+ const replicaPort = 6380 + i;
416
+ const replicaCommand = ['redis-server', '--appendonly', 'no', '--save', '', '--slaveof', master.name, '6379'];
417
+
418
+ if (password) {
419
+ replicaCommand.push('--requirepass', password);
420
+ replicaCommand.push('--masterauth', password);
421
+ }
422
+
423
+ const replica = await RedisTestManager.getDockerManager().createContainer({
424
+ name: `redis-sentinel-replica-${i}`,
425
+ image: 'redis:7-alpine',
426
+ ports: { 6379: replicaPort },
427
+ networks: [networkName],
428
+ command: replicaCommand.join(' '),
429
+ healthcheck: {
430
+ test: password ? ['CMD', 'redis-cli', '-a', password, 'ping'] : ['CMD', 'redis-cli', 'ping'],
431
+ interval: '1s',
432
+ timeout: '3s',
433
+ retries: 5,
434
+ },
435
+ waitFor: {
436
+ healthcheck: true,
437
+ timeout: 30000,
438
+ },
439
+ });
440
+
441
+ replicas.push(replica);
442
+ }
443
+
444
+ // Create sentinels with dynamic port allocation
445
+ for (let i = 0; i < sentinelCount; i++) {
446
+ const sentinelPort = await RedisTestManager.getDockerManager()['findAvailablePort']();
447
+ allocatedPorts.push(sentinelPort);
448
+ sentinelPorts.push(sentinelPort);
449
+
450
+ // Create sentinel config
451
+ const sentinelConfig = [
452
+ `sentinel monitor ${masterName} ${master.name} 6379 2`,
453
+ `sentinel down-after-milliseconds ${masterName} 5000`,
454
+ `sentinel parallel-syncs ${masterName} 1`,
455
+ `sentinel failover-timeout ${masterName} 10000`,
456
+ ];
457
+
458
+ if (password) {
459
+ sentinelConfig.push(`sentinel auth-pass ${masterName} ${password}`);
460
+ }
461
+
462
+ const sentinelCommand = [
463
+ 'sh',
464
+ '-c',
465
+ `echo "${sentinelConfig.join('\\n')}" > /tmp/sentinel.conf && redis-sentinel /tmp/sentinel.conf`,
466
+ ];
467
+
468
+ const sentinel = await RedisTestManager.getDockerManager().createContainer({
469
+ name: `redis-sentinel-${i}`,
470
+ image: 'redis:7-alpine',
471
+ ports: { 26379: sentinelPort },
472
+ networks: [networkName],
473
+ command: sentinelCommand.join(' '),
474
+ healthcheck: {
475
+ test: ['CMD', 'redis-cli', '-p', '26379', 'ping'],
476
+ interval: '1s',
477
+ timeout: '3s',
478
+ retries: 5,
479
+ },
480
+ waitFor: {
481
+ healthcheck: true,
482
+ timeout: 30000,
483
+ },
484
+ });
485
+
486
+ sentinels.push(sentinel);
487
+ }
488
+
489
+ return {
490
+ master,
491
+ replicas,
492
+ sentinels,
493
+ network: networkName,
494
+ masterName,
495
+ sentinelPorts,
496
+ cleanup: async () => {
497
+ await Promise.all(
498
+ [master?.cleanup(), ...replicas.map((c) => c.cleanup()), ...sentinels.map((c) => c.cleanup())].filter(
499
+ Boolean
500
+ ) as Promise<void>[]
501
+ );
502
+ },
503
+ };
504
+ } catch (error) {
505
+ // Cleanup on failure - release allocated ports
506
+ allocatedPorts.forEach((port) => {
507
+ RedisTestManager.getDockerManager()['usedPorts'].delete(port);
508
+ });
509
+ await Promise.all(
510
+ [
511
+ master?.cleanup().catch((cleanupError) => {
512
+ // Log cleanup errors but don't fail the error flow - we're already handling a failure
513
+ console.error(`Failed to cleanup master container ${master?.name}:`, cleanupError);
514
+ }),
515
+ ...replicas.map((c) =>
516
+ c.cleanup().catch((cleanupError) => {
517
+ // Log cleanup errors but don't fail the error flow - we're already handling a failure
518
+ console.error(`Failed to cleanup replica container ${c.name}:`, cleanupError);
519
+ })
520
+ ),
521
+ ...sentinels.map((c) =>
522
+ c.cleanup().catch((cleanupError) => {
523
+ // Log cleanup errors but don't fail the error flow - we're already handling a failure
524
+ console.error(`Failed to cleanup sentinel container ${c.name}:`, cleanupError);
525
+ })
526
+ ),
527
+ ].filter(Boolean)
528
+ );
529
+ throw error;
530
+ }
531
+ }
532
+
533
+ /**
534
+ * Helper to initialize Redis cluster
535
+ * @private
536
+ */
537
+ private static async initializeCluster(
538
+ masters: DockerContainer[],
539
+ replicas: DockerContainer[],
540
+ password?: string
541
+ ): Promise<void> {
542
+ if (masters.length === 0) {
543
+ return;
544
+ }
545
+
546
+ // Build cluster create command
547
+ // Note: Use container names as hostnames (not 127.0.0.1) because cluster init runs inside a container
548
+ // Docker network DNS resolves container names to their IPs, and Redis listens on port 6379 internally
549
+ const allNodes = [...masters, ...replicas];
550
+ const nodeAddresses = allNodes.map((c) => {
551
+ return `${c.name}:6379`;
552
+ });
553
+
554
+ const clusterArgs = [
555
+ 'redis-cli',
556
+ '--cluster',
557
+ 'create',
558
+ ...nodeAddresses,
559
+ '--cluster-replicas',
560
+ String(Math.floor(replicas.length / masters.length)),
561
+ '--cluster-yes',
562
+ ];
563
+
564
+ if (password) {
565
+ clusterArgs.splice(1, 0, '-a', password);
566
+ }
567
+
568
+ // Execute cluster create inside the first master container
569
+ const firstMaster = masters[0];
570
+ if (!firstMaster) {
571
+ throw new Error('No master nodes available to initialize cluster');
572
+ }
573
+
574
+ try {
575
+ const dockerPath = DockerTestManager.getInstance()['dockerPath'];
576
+ const verbose = DockerTestManager.getInstance()['verbose'];
577
+
578
+ if (verbose) {
579
+ console.log('[RedisCluster] Initializing cluster with nodes:', nodeAddresses);
580
+ console.log('[RedisCluster] Running command:', ['exec', firstMaster.name, ...clusterArgs].join(' '));
581
+ }
582
+
583
+ const output = execFileSync(dockerPath, ['exec', firstMaster.name, ...clusterArgs], {
584
+ stdio: verbose ? 'inherit' : 'pipe',
585
+ timeout: 30000,
586
+ encoding: 'utf8',
587
+ });
588
+
589
+ if (verbose && output) {
590
+ console.log('[RedisCluster] Initialization output:', output);
591
+ }
592
+
593
+ // Wait for cluster to be ready - robust check
594
+ const maxWait = 30000; // 30 seconds
595
+ const startTime = Date.now();
596
+ let clusterReady = false;
597
+
598
+ while (!clusterReady && Date.now() - startTime < maxWait) {
599
+ try {
600
+ const clusterInfo = execFileSync(
601
+ dockerPath,
602
+ ['exec', firstMaster.name, 'redis-cli', ...(password ? ['-a', password] : []), 'cluster', 'info'],
603
+ { encoding: 'utf8', stdio: 'pipe' }
604
+ );
605
+
606
+ if (clusterInfo.includes('cluster_state:ok')) {
607
+ // Verify all slots are assigned
608
+ if (clusterInfo.includes('cluster_slots_assigned:16384') && clusterInfo.includes('cluster_slots_ok:16384')) {
609
+ clusterReady = true;
610
+ if (verbose) {
611
+ console.log('[RedisCluster] Cluster is ready');
612
+ }
613
+ break;
614
+ }
615
+ }
616
+ } catch {
617
+ // Not ready yet, continue waiting
618
+ }
619
+
620
+ await new Promise((resolve) => setTimeout(resolve, 500));
621
+ }
622
+
623
+ if (!clusterReady) {
624
+ throw new Error('Redis cluster failed to reach ready state within timeout');
625
+ }
626
+
627
+ if (verbose) {
628
+ console.log('[RedisCluster] Cluster initialization complete');
629
+ }
630
+ } catch (error) {
631
+ const errorMsg = error instanceof Error ? error.message : String(error);
632
+ throw new Error(`Failed to initialize Redis cluster: ${errorMsg}`);
633
+ }
634
+ }
635
+
636
+ /**
637
+ * Helper: Run test with a standalone Redis container
638
+ *
639
+ * @param testFn - Test function that receives container and connection string
640
+ * @param options - Redis configuration options
641
+ * @returns Promise resolving to test function result
642
+ *
643
+ * @example
644
+ * ```typescript
645
+ * await RedisTestManager.withRedis(async (container, connectionString) => {
646
+ * const client = new Redis(connectionString);
647
+ * await client.set('key', 'value');
648
+ * // Run tests...
649
+ * await client.quit();
650
+ * });
651
+ * ```
652
+ */
653
+ static async withRedis<T>(
654
+ testFn: (container: DockerContainer, connectionString: string) => Promise<T>,
655
+ options?: RedisContainerOptions
656
+ ): Promise<T> {
657
+ const container = await RedisTestManager.createRedisContainer(options);
658
+
659
+ const port = container.ports.get(6379)!;
660
+ const password = options?.password;
661
+ const database = options?.database ?? 0;
662
+
663
+ let connectionString = `redis://`;
664
+ if (password) {
665
+ connectionString += `:${password}@`;
666
+ }
667
+ connectionString += `localhost:${port}/${database}`;
668
+
669
+ try {
670
+ return await testFn(container, connectionString);
671
+ } finally {
672
+ await container.cleanup();
673
+ }
674
+ }
675
+
676
+ /**
677
+ * Helper: Run test with Redis cluster
678
+ *
679
+ * @param testFn - Test function that receives cluster containers
680
+ * @param options - Redis Cluster configuration options
681
+ * @returns Promise resolving to test function result
682
+ *
683
+ * @example
684
+ * ```typescript
685
+ * await RedisTestManager.withRedisCluster(async (cluster) => {
686
+ * const client = new Redis.Cluster(cluster.nodes.map(n => ({ host: n.host, port: n.port })));
687
+ * await client.set('key', 'value');
688
+ * // Run tests...
689
+ * await client.quit();
690
+ * }, { masterCount: 3, replicasPerMaster: 1 });
691
+ * ```
692
+ */
693
+ static async withRedisCluster<T>(
694
+ testFn: (cluster: RedisClusterContainers) => Promise<T>,
695
+ options?: RedisClusterOptions
696
+ ): Promise<T> {
697
+ const cluster = await RedisTestManager.createRedisCluster(options);
698
+
699
+ try {
700
+ return await testFn(cluster);
701
+ } finally {
702
+ await cluster.cleanup();
703
+ }
704
+ }
705
+
706
+ /**
707
+ * Helper: Run test with Redis Sentinel
708
+ *
709
+ * @param testFn - Test function that receives sentinel containers
710
+ * @param options - Redis Sentinel configuration options
711
+ * @returns Promise resolving to test function result
712
+ *
713
+ * @example
714
+ * ```typescript
715
+ * await RedisTestManager.withRedisSentinel(async (sentinel) => {
716
+ * const client = new Redis({
717
+ * sentinels: sentinel.sentinelPorts.map(port => ({ host: '127.0.0.1', port })),
718
+ * name: sentinel.masterName,
719
+ * });
720
+ * await client.set('key', 'value');
721
+ * // Run tests...
722
+ * await client.quit();
723
+ * });
724
+ * ```
725
+ */
726
+ static async withRedisSentinel<T>(
727
+ testFn: (sentinel: RedisSentinelContainers) => Promise<T>,
728
+ options?: RedisSentinelOptions
729
+ ): Promise<T> {
730
+ const sentinel = await RedisTestManager.createRedisSentinel(options);
731
+
732
+ try {
733
+ return await testFn(sentinel);
734
+ } finally {
735
+ await sentinel.cleanup();
736
+ }
737
+ }
738
+ }