@omnitron-dev/testing 0.4.0 → 0.4.2

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 (89) 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/package.json +28 -2
  62. package/src/async/README.md +336 -0
  63. package/src/async/deferred.ts +98 -0
  64. package/src/async/events.ts +386 -0
  65. package/src/async/index.ts +48 -0
  66. package/src/async/mock-timer.ts +220 -0
  67. package/src/async/retry.ts +118 -0
  68. package/src/async/wait.ts +151 -0
  69. package/src/docker/database-manager.ts +242 -0
  70. package/src/docker/docker-test-manager.ts +1186 -0
  71. package/src/docker/index.ts +48 -0
  72. package/src/docker/redis-manager.ts +738 -0
  73. package/src/docker/types.ts +216 -0
  74. package/src/errors.ts +31 -0
  75. package/src/helpers/assertions.ts +171 -0
  76. package/src/helpers/console.ts +74 -0
  77. package/src/helpers/index.ts +15 -0
  78. package/src/helpers/temp-dir.ts +50 -0
  79. package/src/index.ts +2 -0
  80. package/src/performance/index.ts +11 -0
  81. package/src/performance/memory-detector.ts +166 -0
  82. package/src/performance/perf-timer.ts +146 -0
  83. package/src/titan/container-utils.ts +128 -0
  84. package/src/titan/index.ts +59 -0
  85. package/src/titan/redis-test-utils.ts +566 -0
  86. package/src/titan/test-application.ts +154 -0
  87. package/src/titan/test-fixtures.ts +304 -0
  88. package/src/titan/test-mocks.ts +336 -0
  89. package/src/titan/test-module.ts +231 -0
@@ -0,0 +1,1186 @@
1
+ /**
2
+ * Generic Docker Test Manager
3
+ *
4
+ * Provides a unified interface for managing Docker containers in tests
5
+ * with robust lifecycle management, graceful shutdown, and reliable cleanup.
6
+ *
7
+ * Features:
8
+ * - Singleton pattern for centralized container management
9
+ * - Automatic port allocation with worker-aware ranges
10
+ * - Cross-platform Docker executable detection
11
+ * - Graceful shutdown with cleanup on exit
12
+ * - Health check support
13
+ * - Network management
14
+ */
15
+
16
+ import { execSync, execFileSync } from 'child_process';
17
+ import { randomBytes } from 'crypto';
18
+ import * as net from 'net';
19
+ import { EventEmitter } from 'events';
20
+ import type {
21
+ DockerContainer,
22
+ DockerContainerStatus,
23
+ DockerTestManagerOptions,
24
+ ContainerOptions,
25
+ } from './types.js';
26
+
27
+ /**
28
+ * Docker Test Manager
29
+ *
30
+ * Manages Docker containers for testing with automatic cleanup and port allocation.
31
+ * Uses singleton pattern to ensure proper cleanup across test suites.
32
+ *
33
+ * @example
34
+ * ```typescript
35
+ * const manager = DockerTestManager.getInstance();
36
+ * const container = await manager.createContainer({
37
+ * image: 'redis:7-alpine',
38
+ * ports: { 6379: 'auto' },
39
+ * healthcheck: {
40
+ * test: ['CMD', 'redis-cli', 'ping'],
41
+ * interval: '1s',
42
+ * },
43
+ * waitFor: { healthcheck: true },
44
+ * });
45
+ *
46
+ * // Use container...
47
+ * await container.cleanup();
48
+ * ```
49
+ */
50
+ export class DockerTestManager extends EventEmitter {
51
+ private static instance: DockerTestManager;
52
+ private containers: Map<string, DockerContainer> = new Map();
53
+ private usedPorts: Set<number> = new Set();
54
+ private networks: Set<string> = new Set();
55
+ private cleanupInProgress = false;
56
+
57
+ private dockerPath: string;
58
+ private basePort: number;
59
+ private maxRetries: number;
60
+ private startupTimeout: number;
61
+ private gracefulShutdownTimeout: number;
62
+ private maxCleanupRetries: number;
63
+ private cleanup: boolean;
64
+ private verbose: boolean;
65
+ private defaultNetwork?: string;
66
+
67
+ private constructor(options: DockerTestManagerOptions = {}) {
68
+ super();
69
+ this.dockerPath = options.dockerPath || this.findDockerPath();
70
+
71
+ // Worker-aware port allocation to prevent conflicts in parallel test execution
72
+ // Each jest worker gets its own 10k port range
73
+ const workerId = parseInt(process.env['JEST_WORKER_ID'] || '1', 10);
74
+ const basePortOffset = (workerId - 1) * 10000;
75
+ this.basePort = options.basePort || (10000 + basePortOffset);
76
+
77
+ this.maxRetries = options.maxRetries || 20;
78
+ this.startupTimeout = options.startupTimeout || 30000;
79
+ this.gracefulShutdownTimeout = options.gracefulShutdownTimeout || 10000;
80
+ this.maxCleanupRetries = options.maxCleanupRetries || 3;
81
+ this.cleanup = options.cleanup !== false;
82
+ this.verbose = options.verbose || false;
83
+ this.defaultNetwork = options.network;
84
+
85
+ if (this.verbose) {
86
+ this.log(`Initialized for Jest worker ${workerId} with port range ${this.basePort}-${this.basePort + 10000}`);
87
+ }
88
+
89
+ // Verify Docker is available
90
+ this.verifyDocker();
91
+
92
+ // Register cleanup handlers with graceful shutdown
93
+ if (this.cleanup) {
94
+ // Increase max listeners to avoid warnings when multiple test managers are instantiated
95
+ // This is safe because signal handlers should be idempotent and cleanup is managed by the singleton pattern
96
+ process.setMaxListeners(Math.max(20, process.getMaxListeners()));
97
+
98
+ process.on('exit', () => this.cleanupSync());
99
+ process.on('SIGINT', () => {
100
+ this.log('SIGINT received - initiating graceful shutdown');
101
+ this.cleanupAllAsync()
102
+ .then(() => {
103
+ this.log('Cleanup completed, exiting');
104
+ process.exit(0);
105
+ })
106
+ .catch((error) => {
107
+ this.logError('Cleanup failed during SIGINT', error);
108
+ process.exit(1);
109
+ });
110
+ });
111
+ process.on('SIGTERM', () => {
112
+ this.log('SIGTERM received - initiating graceful shutdown');
113
+ this.cleanupAllAsync()
114
+ .then(() => {
115
+ this.log('Cleanup completed, exiting');
116
+ process.exit(0);
117
+ })
118
+ .catch((error) => {
119
+ this.logError('Cleanup failed during SIGTERM', error);
120
+ process.exit(1);
121
+ });
122
+ });
123
+ }
124
+ }
125
+
126
+ /**
127
+ * Get the singleton instance of DockerTestManager
128
+ *
129
+ * @param options - Configuration options (only used on first call)
130
+ * @returns The singleton DockerTestManager instance
131
+ */
132
+ static getInstance(options?: DockerTestManagerOptions): DockerTestManager {
133
+ if (!DockerTestManager.instance) {
134
+ DockerTestManager.instance = new DockerTestManager(options);
135
+ }
136
+ return DockerTestManager.instance;
137
+ }
138
+
139
+ /**
140
+ * Find Docker executable path across different platforms
141
+ *
142
+ * Detection strategy:
143
+ * 1. Try 'which docker' (Unix) or 'where docker' (Windows) to find in PATH
144
+ * 2. Check platform-specific common locations
145
+ * 3. Validate the found path works with 'docker version'
146
+ *
147
+ * Supported platforms:
148
+ * - macOS: /usr/local/bin/docker, /opt/homebrew/bin/docker, docker in PATH
149
+ * - Linux: /usr/bin/docker, /usr/local/bin/docker, /snap/bin/docker, docker in PATH
150
+ * - Windows: docker.exe in PATH, C:\Program Files\Docker\Docker\resources\bin\docker.exe
151
+ *
152
+ * @throws Error if Docker cannot be found
153
+ * @private
154
+ */
155
+ private findDockerPath(): string {
156
+ const isWindows = process.platform === 'win32';
157
+ const whichCommand = isWindows ? 'where' : 'which';
158
+ const dockerBinary = isWindows ? 'docker.exe' : 'docker';
159
+
160
+ // Strategy 1: Try to find Docker in PATH using which/where
161
+ try {
162
+ const result = execSync(`${whichCommand} ${dockerBinary}`, {
163
+ encoding: 'utf8',
164
+ stdio: ['pipe', 'pipe', 'ignore'],
165
+ }).trim();
166
+
167
+ // On Windows, 'where' can return multiple paths (one per line)
168
+ // Take the first one
169
+ const dockerPath = result.split('\n')[0]?.trim();
170
+
171
+ if (dockerPath && this.testDockerPath(dockerPath)) {
172
+ if (this.verbose) {
173
+ console.log(`Found Docker in PATH: ${dockerPath}`);
174
+ }
175
+ return dockerPath;
176
+ }
177
+ } catch {
178
+ // Command failed, continue to fallback paths
179
+ }
180
+
181
+ // Strategy 2: Check platform-specific common locations
182
+ const fallbackPaths = this.getDockerFallbackPaths();
183
+
184
+ for (const path of fallbackPaths) {
185
+ if (this.testDockerPath(path)) {
186
+ if (this.verbose) {
187
+ console.log(`Found Docker at fallback path: ${path}`);
188
+ }
189
+ return path;
190
+ }
191
+ }
192
+
193
+ // Strategy 3: If all else fails, try just 'docker' or 'docker.exe' and hope it's in PATH
194
+ if (this.testDockerPath(dockerBinary)) {
195
+ if (this.verbose) {
196
+ console.log(`Using Docker from PATH: ${dockerBinary}`);
197
+ }
198
+ return dockerBinary;
199
+ }
200
+
201
+ // No Docker found
202
+ throw new Error(
203
+ `Docker executable not found. Please install Docker and ensure it's in your PATH.\n` +
204
+ `Searched paths:\n` +
205
+ ` - PATH using '${whichCommand} ${dockerBinary}'\n` +
206
+ ` - ${fallbackPaths.join('\n - ')}\n` +
207
+ `\n` +
208
+ `Platform: ${process.platform}\n` +
209
+ `For more information, visit: https://docs.docker.com/get-docker/`
210
+ );
211
+ }
212
+
213
+ /**
214
+ * Get platform-specific fallback paths for Docker
215
+ * @private
216
+ */
217
+ private getDockerFallbackPaths(): string[] {
218
+ switch (process.platform) {
219
+ case 'darwin': // macOS
220
+ return [
221
+ '/usr/local/bin/docker', // Intel Mac / Docker Desktop
222
+ '/opt/homebrew/bin/docker', // Apple Silicon Mac / Homebrew
223
+ '/Applications/Docker.app/Contents/Resources/bin/docker', // Docker Desktop
224
+ ];
225
+
226
+ case 'linux':
227
+ return [
228
+ '/usr/bin/docker', // Most common Linux location
229
+ '/usr/local/bin/docker', // Alternative Linux location
230
+ '/snap/bin/docker', // Snap package
231
+ '/var/lib/snapd/snap/bin/docker', // Snap on some distros
232
+ '/opt/docker/bin/docker', // Custom installations
233
+ ];
234
+
235
+ case 'win32': // Windows
236
+ return [
237
+ 'docker.exe', // Should be in PATH
238
+ 'C:\\Program Files\\Docker\\Docker\\resources\\bin\\docker.exe',
239
+ 'C:\\ProgramData\\DockerDesktop\\version-bin\\docker.exe',
240
+ ];
241
+
242
+ default:
243
+ // Unknown platform, try generic paths
244
+ return ['/usr/local/bin/docker', '/usr/bin/docker', 'docker'];
245
+ }
246
+ }
247
+
248
+ /**
249
+ * Test if a Docker path is valid by running 'docker version'
250
+ * @private
251
+ */
252
+ private testDockerPath(dockerPath: string): boolean {
253
+ try {
254
+ // Use execFileSync to avoid shell quoting issues
255
+ execFileSync(dockerPath, ['version'], {
256
+ stdio: 'ignore',
257
+ timeout: 5000, // 5 second timeout
258
+ });
259
+ return true;
260
+ } catch {
261
+ return false;
262
+ }
263
+ }
264
+
265
+ /**
266
+ * Verify Docker is available and working
267
+ * @throws Error if Docker is not available
268
+ * @private
269
+ */
270
+ private verifyDocker(): void {
271
+ try {
272
+ // Use execFileSync to avoid shell quoting issues
273
+ execFileSync(this.dockerPath, ['version'], { stdio: 'ignore' });
274
+ } catch {
275
+ throw new Error(
276
+ `Docker is not available at path: ${this.dockerPath}\n` +
277
+ `Please install Docker or verify it's properly configured.\n` +
278
+ `Visit: https://docs.docker.com/get-docker/`
279
+ );
280
+ }
281
+ }
282
+
283
+ /**
284
+ * Find an available port for container mapping
285
+ * @private
286
+ */
287
+ private async findAvailablePort(): Promise<number> {
288
+ for (let i = 0; i < this.maxRetries; i++) {
289
+ const port = this.basePort + Math.floor(Math.random() * 10000);
290
+ if (!this.usedPorts.has(port) && (await this.isPortAvailable(port))) {
291
+ this.usedPorts.add(port);
292
+ return port;
293
+ }
294
+ }
295
+ throw new Error('Could not find available port for container');
296
+ }
297
+
298
+ /**
299
+ * Check if a port is available on localhost
300
+ * @private
301
+ */
302
+ private async isPortAvailable(port: number): Promise<boolean> {
303
+ return new Promise((resolve) => {
304
+ const server = net.createServer();
305
+ server.once('error', () => resolve(false));
306
+ server.once('listening', () => {
307
+ server.close();
308
+ resolve(true);
309
+ });
310
+ server.listen(port, '127.0.0.1');
311
+ });
312
+ }
313
+
314
+ /**
315
+ * Log a message if verbose mode is enabled
316
+ * @private
317
+ */
318
+ private log(message: string, data?: any): void {
319
+ if (this.verbose) {
320
+ const timestamp = new Date().toISOString();
321
+ const msg = data ? `[${timestamp}] ${message}: ${JSON.stringify(data)}` : `[${timestamp}] ${message}`;
322
+ console.log(msg);
323
+ }
324
+ }
325
+
326
+ /**
327
+ * Log an error message
328
+ * @private
329
+ */
330
+ private logError(message: string, error: any): void {
331
+ const timestamp = new Date().toISOString();
332
+ const err = error instanceof Error ? error.message : String(error);
333
+ const msg = `[${timestamp}] ERROR: ${message}: ${err}`;
334
+ if (this.verbose) {
335
+ console.error(msg);
336
+ }
337
+ }
338
+
339
+ /**
340
+ * Get the status of a container
341
+ * @private
342
+ */
343
+ private async getContainerStatus(name: string): Promise<DockerContainerStatus> {
344
+ try {
345
+ const inspectOutput = execFileSync(
346
+ this.dockerPath,
347
+ [
348
+ 'inspect',
349
+ '--format',
350
+ '{{.State.Running}}\t{{.State.Status}}\t{{.State.Health.Status}}\t{{.State.ExitCode}}',
351
+ name,
352
+ ],
353
+ {
354
+ encoding: 'utf8',
355
+ stdio: ['pipe', 'pipe', 'ignore'],
356
+ }
357
+ ).trim();
358
+
359
+ const [running, state, health, exitCode] = inspectOutput.split('\t');
360
+
361
+ return {
362
+ isRunning: running === 'true',
363
+ state: state || undefined,
364
+ health: health && health !== '<no value>' ? health : undefined,
365
+ exitCode: exitCode ? parseInt(exitCode) : undefined,
366
+ };
367
+ } catch (error) {
368
+ this.logError(`Failed to get container status for ${name}`, error);
369
+ return { isRunning: false };
370
+ }
371
+ }
372
+
373
+ /**
374
+ * Check if a container is healthy
375
+ * @private
376
+ */
377
+ private async isContainerHealthy(name: string): Promise<boolean> {
378
+ try {
379
+ const status = await this.getContainerStatus(name);
380
+ if (!status.isRunning) {
381
+ return false;
382
+ }
383
+ // If container has health check, wait for healthy state
384
+ if (status.health) {
385
+ return status.health === 'healthy';
386
+ }
387
+ // If no health check defined, just check if running
388
+ return true;
389
+ } catch {
390
+ return false;
391
+ }
392
+ }
393
+
394
+ /**
395
+ * Create and start a Docker container
396
+ *
397
+ * @param options - Container configuration
398
+ * @returns Promise resolving to DockerContainer instance
399
+ *
400
+ * @example
401
+ * ```typescript
402
+ * const container = await manager.createContainer({
403
+ * image: 'postgres:16-alpine',
404
+ * ports: { 5432: 'auto' },
405
+ * environment: { POSTGRES_PASSWORD: 'test' },
406
+ * healthcheck: {
407
+ * test: ['CMD', 'pg_isready'],
408
+ * interval: '1s',
409
+ * },
410
+ * waitFor: { healthcheck: true },
411
+ * });
412
+ * ```
413
+ */
414
+ async createContainer(options: ContainerOptions): Promise<DockerContainer> {
415
+ const id = `test-${randomBytes(8).toString('hex')}`; // 8 bytes for better uniqueness in parallel execution
416
+ const name = options.name || `container-${id}`;
417
+ const host = '127.0.0.1';
418
+
419
+ // Remove any existing container with the same name to avoid conflicts
420
+ try {
421
+ execFileSync(this.dockerPath, ['rm', '-f', name], { stdio: 'ignore' });
422
+ this.log(`Removed existing container: ${name}`);
423
+ } catch {
424
+ // Container doesn't exist, which is fine
425
+ }
426
+
427
+ // Process port mappings
428
+ const portMappings = new Map<number, number>();
429
+ if (options.ports) {
430
+ for (const [containerPort, hostPort] of Object.entries(options.ports)) {
431
+ const cPort = parseInt(containerPort);
432
+ const hPort = hostPort === 'auto' ? await this.findAvailablePort() : hostPort;
433
+ portMappings.set(cPort, hPort);
434
+ }
435
+ }
436
+
437
+ // Build docker run command
438
+ const dockerArgs: string[] = ['run', '-d', '--name', name];
439
+
440
+ // Add ports
441
+ portMappings.forEach((hostPort, containerPort) => {
442
+ dockerArgs.push('-p', `${hostPort}:${containerPort}`);
443
+ });
444
+
445
+ // Add environment variables
446
+ const environment = options.environment || {};
447
+ for (const [key, value] of Object.entries(environment)) {
448
+ dockerArgs.push('-e', `${key}=${value}`);
449
+ }
450
+
451
+ // Add labels
452
+ const labels = {
453
+ 'test.id': id,
454
+ 'test.cleanup': 'true',
455
+ ...options.labels,
456
+ };
457
+ for (const [key, value] of Object.entries(labels)) {
458
+ dockerArgs.push('--label', `${key}=${value}`);
459
+ }
460
+
461
+ // Add volumes
462
+ if (options.volumes) {
463
+ for (const volume of options.volumes) {
464
+ dockerArgs.push('-v', volume);
465
+ }
466
+ }
467
+
468
+ // Add networks
469
+ const networks = options.networks || (this.defaultNetwork ? [this.defaultNetwork] : []);
470
+ for (const network of networks) {
471
+ // Create network if it doesn't exist
472
+ await this.ensureNetwork(network);
473
+ dockerArgs.push('--network', network);
474
+ }
475
+
476
+ // Add healthcheck if provided
477
+ if (options.healthcheck) {
478
+ // Docker CLI --health-cmd expects a string that is executed by the shell
479
+ // The healthcheck.test array format from Docker Compose needs to be converted:
480
+ // - ['CMD', 'arg1', 'arg2'] -> execute command directly (no shell)
481
+ // - ['CMD-SHELL', 'command'] -> execute via shell
482
+ let healthCmd: string;
483
+ if (Array.isArray(options.healthcheck.test)) {
484
+ if (options.healthcheck.test[0] === 'CMD-SHELL') {
485
+ // CMD-SHELL format: join everything after the first element
486
+ healthCmd = options.healthcheck.test.slice(1).join(' ');
487
+ } else if (options.healthcheck.test[0] === 'CMD') {
488
+ // CMD format: join command parts without shell
489
+ // Docker CLI expects this as a single string that will be word-split
490
+ // For example: ['CMD', 'redis-cli', 'ping'] -> 'redis-cli ping'
491
+ healthCmd = options.healthcheck.test.slice(1).join(' ');
492
+ } else {
493
+ // No format specifier, join all parts
494
+ healthCmd = options.healthcheck.test.join(' ');
495
+ }
496
+ } else {
497
+ // String format
498
+ healthCmd = options.healthcheck.test;
499
+ }
500
+ dockerArgs.push('--health-cmd', healthCmd);
501
+ if (options.healthcheck.interval) {
502
+ dockerArgs.push('--health-interval', options.healthcheck.interval);
503
+ }
504
+ if (options.healthcheck.timeout) {
505
+ dockerArgs.push('--health-timeout', options.healthcheck.timeout);
506
+ }
507
+ if (options.healthcheck.retries) {
508
+ dockerArgs.push('--health-retries', options.healthcheck.retries.toString());
509
+ }
510
+ if (options.healthcheck.startPeriod) {
511
+ dockerArgs.push('--health-start-period', options.healthcheck.startPeriod);
512
+ }
513
+ }
514
+
515
+ // Add image and command
516
+ dockerArgs.push(options.image);
517
+ if (options.command) {
518
+ dockerArgs.push('sh', '-c', options.command);
519
+ }
520
+
521
+ if (this.verbose) {
522
+ console.log(`Starting container ${name}: docker ${dockerArgs.join(' ')}`);
523
+ }
524
+
525
+ // Start container using execFileSync to properly handle arguments with spaces
526
+ try {
527
+ this.log(`Starting container: ${name}`, { image: options.image });
528
+ const result = execFileSync(this.dockerPath, dockerArgs, {
529
+ encoding: 'utf8',
530
+ stdio: ['pipe', 'pipe', 'pipe'], // Always capture output for better error messages
531
+ });
532
+ if (this.verbose && result) {
533
+ console.log(result);
534
+ }
535
+ } catch (error) {
536
+ // Clean up allocated ports before throwing
537
+ portMappings.forEach((port) => {
538
+ this.usedPorts.delete(port);
539
+ });
540
+ const execError = error as { stderr?: Buffer | string; stdout?: Buffer | string; message?: string; status?: number };
541
+ const stderr = execError.stderr ? String(execError.stderr).trim() : '';
542
+ const stdout = execError.stdout ? String(execError.stdout).trim() : '';
543
+ const message = execError.message || String(error);
544
+
545
+ // Check if container already exists
546
+ if (stderr.includes('already in use') || stderr.includes('name is already') || stderr.includes('Conflict')) {
547
+ throw new Error(
548
+ `Container name conflict: ${name} already exists.\n` +
549
+ `Please ensure previous test containers are cleaned up.\n` +
550
+ `Stderr: ${stderr}`
551
+ );
552
+ }
553
+
554
+ throw new Error(
555
+ `Failed to start container ${name}:\n` +
556
+ `Command: docker ${dockerArgs.join(' ')}\n` +
557
+ `Exit code: ${execError.status || 'unknown'}\n` +
558
+ (stderr ? `Stderr: ${stderr}\n` : '') +
559
+ (stdout ? `Stdout: ${stdout}\n` : '') +
560
+ (message && !stderr && !stdout ? `Error: ${message}` : '')
561
+ );
562
+ }
563
+
564
+ // Wait for container to be ready
565
+ if (options.waitFor) {
566
+ try {
567
+ await this.waitForContainer(name, options.waitFor);
568
+ this.log(`Container ready: ${name}`);
569
+ } catch (error) {
570
+ // Container failed to start, attempt cleanup
571
+ this.logError(`Container ${name} failed to become ready, cleaning up`, error);
572
+ try {
573
+ execFileSync(this.dockerPath, ['stop', '-t', '5', name], { stdio: 'ignore' });
574
+ execFileSync(this.dockerPath, ['rm', '-f', name], { stdio: 'ignore' });
575
+ } catch {
576
+ // Ignore cleanup errors during rollback
577
+ }
578
+ // Clean up allocated ports
579
+ portMappings.forEach((port) => {
580
+ this.usedPorts.delete(port);
581
+ });
582
+ throw error;
583
+ }
584
+ }
585
+
586
+ // Get internal IP if container is on a network
587
+ let internalIp: string | undefined;
588
+ if (networks.length > 0) {
589
+ try {
590
+ const ipOutput = execFileSync(
591
+ this.dockerPath,
592
+ ['inspect', name, '--format', '{{range .NetworkSettings.Networks}}{{.IPAddress}}{{end}}'],
593
+ {
594
+ encoding: 'utf8',
595
+ stdio: ['pipe', 'pipe', 'ignore'],
596
+ }
597
+ ).trim();
598
+ if (ipOutput) {
599
+ internalIp = ipOutput;
600
+ this.log(`Container ${name} internal IP: ${internalIp}`);
601
+ }
602
+ } catch (error) {
603
+ this.logError(`Failed to get internal IP for ${name}`, error);
604
+ // Continue without internal IP
605
+ }
606
+ }
607
+
608
+ const container: DockerContainer = {
609
+ id,
610
+ name,
611
+ image: options.image,
612
+ host,
613
+ port: portMappings.values().next().value, // First port for convenience
614
+ ports: portMappings,
615
+ environment,
616
+ labels,
617
+ networks,
618
+ createdAt: new Date(),
619
+ internalIp,
620
+ getStatus: async () => this.getContainerStatus(name),
621
+ isHealthy: async () => this.isContainerHealthy(name),
622
+ cleanup: async () => {
623
+ await this.cleanupContainerWithRetry(name, id, portMappings);
624
+ },
625
+ };
626
+
627
+ this.containers.set(id, container);
628
+ return container;
629
+ }
630
+
631
+ /**
632
+ * Clean up a container with retry logic
633
+ * @private
634
+ */
635
+ private async cleanupContainerWithRetry(name: string, id: string, portMappings: Map<number, number>): Promise<void> {
636
+ this.log(`Starting cleanup for container: ${name}`);
637
+
638
+ let lastError: Error | null = null;
639
+
640
+ for (let attempt = 1; attempt <= this.maxCleanupRetries; attempt++) {
641
+ try {
642
+ // Check if container exists
643
+ try {
644
+ const status = await this.getContainerStatus(name);
645
+ if (!status.isRunning) {
646
+ this.log(`Container ${name} is not running, force removing`, { attempt });
647
+ }
648
+ } catch {
649
+ // Container doesn't exist, nothing to clean up
650
+ this.log(`Container ${name} doesn't exist, skipping stop`, { attempt });
651
+ break;
652
+ }
653
+
654
+ // Gracefully stop the container first
655
+ try {
656
+ const stopTimeoutSecs = Math.ceil(this.gracefulShutdownTimeout / 1000).toString();
657
+ this.log(`Stopping container ${name}`, { attempt, timeout: this.gracefulShutdownTimeout });
658
+ execFileSync(this.dockerPath, ['stop', '-t', stopTimeoutSecs, name], {
659
+ stdio: 'ignore',
660
+ timeout: this.gracefulShutdownTimeout + 5000, // Add buffer to docker timeout
661
+ });
662
+ this.log(`Container stopped: ${name}`, { attempt });
663
+ } catch (error) {
664
+ this.logError(`Failed to gracefully stop container ${name}`, error);
665
+ // Continue to force remove
666
+ }
667
+
668
+ // Remove container
669
+ try {
670
+ this.log(`Removing container ${name}`, { attempt });
671
+ execFileSync(this.dockerPath, ['rm', '-f', name], { stdio: 'ignore' });
672
+ this.log(`Container removed: ${name}`, { attempt });
673
+ lastError = null; // Clear error on success
674
+ break;
675
+ } catch (error) {
676
+ lastError = error instanceof Error ? error : new Error(String(error));
677
+ if (attempt === this.maxCleanupRetries) {
678
+ throw lastError;
679
+ }
680
+ // Wait before retrying
681
+ await new Promise((resolve) => setTimeout(resolve, 1000 * attempt));
682
+ }
683
+ } catch (error) {
684
+ lastError = error instanceof Error ? error : new Error(String(error));
685
+ if (attempt === this.maxCleanupRetries) {
686
+ this.logError(`Final cleanup attempt failed for container ${name}`, lastError);
687
+ // Don't throw, continue with port cleanup
688
+ } else {
689
+ this.logError(`Cleanup attempt ${attempt} failed for container ${name}, retrying`, lastError);
690
+ await new Promise((resolve) => setTimeout(resolve, 1000 * attempt));
691
+ }
692
+ }
693
+ }
694
+
695
+ // Always release ports, even if cleanup failed
696
+ try {
697
+ portMappings.forEach((port) => {
698
+ this.usedPorts.delete(port);
699
+ this.log(`Released port: ${port}`);
700
+ });
701
+ } catch (error) {
702
+ this.logError('Failed to release ports', error);
703
+ }
704
+
705
+ // Remove from tracking
706
+ this.containers.delete(id);
707
+ this.log(`Container cleanup completed: ${name}`, { attempts: this.maxCleanupRetries });
708
+ }
709
+
710
+ /**
711
+ * Ensure a Docker network exists
712
+ * @private
713
+ */
714
+ private async ensureNetwork(network: string): Promise<void> {
715
+ if (!this.networks.has(network)) {
716
+ try {
717
+ execFileSync(this.dockerPath, ['network', 'create', network, '--label', 'test.cleanup=true'], {
718
+ stdio: 'pipe',
719
+ encoding: 'utf8',
720
+ });
721
+ this.networks.add(network);
722
+ this.log(`Created network: ${network}`);
723
+ } catch (error) {
724
+ const execError = error as { stderr?: string; stdout?: string; message?: string };
725
+ const stderr = execError.stderr || execError.message || String(error);
726
+ // Network might already exist - check if that's the case
727
+ if (stderr.includes('already exists') || stderr.includes('network with name')) {
728
+ this.log(`Network already exists: ${network}`);
729
+ this.networks.add(network);
730
+ } else if (stderr.includes('all predefined address pools have been fully subnetted')) {
731
+ // Docker network pool exhausted - try to clean up unused networks
732
+ this.log('Docker network pool exhausted, attempting cleanup...');
733
+ try {
734
+ // Prune unused networks
735
+ execFileSync(this.dockerPath, ['network', 'prune', '-f'], {
736
+ stdio: 'ignore',
737
+ });
738
+ this.log('Cleaned up unused networks, retrying network creation...');
739
+ // Retry network creation after cleanup
740
+ execFileSync(this.dockerPath, ['network', 'create', network, '--label', 'test.cleanup=true'], {
741
+ stdio: 'pipe',
742
+ encoding: 'utf8',
743
+ });
744
+ this.networks.add(network);
745
+ this.log(`Created network after cleanup: ${network}`);
746
+ } catch (retryError) {
747
+ throw new Error(`Failed to create network ${network} even after cleanup: ${stderr}`);
748
+ }
749
+ } else {
750
+ // Real error - throw it
751
+ throw new Error(`Failed to create network ${network}: ${stderr}`);
752
+ }
753
+ }
754
+ }
755
+ }
756
+
757
+ /**
758
+ * Remove a Docker network
759
+ * @private
760
+ */
761
+ private async removeNetwork(network: string): Promise<void> {
762
+ if (!this.networks.has(network)) {
763
+ return; // Network not tracked by this manager
764
+ }
765
+
766
+ try {
767
+ execFileSync(this.dockerPath, ['network', 'rm', network], {
768
+ stdio: 'ignore',
769
+ });
770
+ this.networks.delete(network);
771
+ this.log(`Removed network: ${network}`);
772
+ } catch (error) {
773
+ // Network might still be in use or already removed
774
+ this.networks.delete(network); // Remove from tracking anyway
775
+ this.logError(`Failed to remove network ${network}`, error);
776
+ }
777
+ }
778
+
779
+ /**
780
+ * Wait for a container to be ready
781
+ * @private
782
+ */
783
+ private async waitForContainer(name: string, options: ContainerOptions['waitFor']): Promise<void> {
784
+ const startTime = Date.now();
785
+ const timeout = options?.timeout || this.startupTimeout;
786
+
787
+ let lastError: Error | undefined;
788
+
789
+ while (Date.now() - startTime < timeout) {
790
+ try {
791
+ // First check if container is still running
792
+ const status = await this.getContainerStatus(name);
793
+ if (!status.isRunning) {
794
+ throw new Error(
795
+ `Container exited with status '${status.state}' and exit code ${status.exitCode}. ` +
796
+ `Check container logs with 'docker logs ${name}'`
797
+ );
798
+ }
799
+
800
+ // Check if container is healthy (if healthcheck is configured)
801
+ if (options?.healthcheck) {
802
+ if (status.health === 'healthy') {
803
+ this.log(`Container ${name} is healthy`);
804
+ return;
805
+ }
806
+
807
+ if (status.health === 'unhealthy') {
808
+ throw new Error(
809
+ `Container ${name} health check failed. ` + `Check container logs with 'docker logs ${name}'`
810
+ );
811
+ }
812
+
813
+ // Health check is still starting
814
+ if (status.health === 'starting') {
815
+ this.log(`Waiting for health check on ${name}...`, { elapsed: Date.now() - startTime });
816
+ }
817
+ }
818
+
819
+ // Check if port is accessible
820
+ if (options?.port) {
821
+ const container = this.containers.get(name);
822
+ if (container) {
823
+ const hostPort = container.ports.get(options.port);
824
+ if (hostPort && (await this.isPortListening('127.0.0.1', hostPort))) {
825
+ this.log(`Port ${hostPort} is listening on ${name}`);
826
+ return;
827
+ }
828
+ }
829
+ }
830
+
831
+ // If no specific wait condition, just check container is running
832
+ if (!options?.healthcheck && !options?.port) {
833
+ this.log(`Container ${name} is running`);
834
+ return;
835
+ }
836
+
837
+ lastError = undefined;
838
+ } catch (error) {
839
+ lastError = error instanceof Error ? error : new Error(String(error));
840
+ this.logError(`Error waiting for container ${name}`, lastError);
841
+
842
+ // Check if this is a fatal error
843
+ if (
844
+ lastError.message.includes('exited') ||
845
+ lastError.message.includes('unhealthy') ||
846
+ lastError.message.includes('health check failed')
847
+ ) {
848
+ throw lastError;
849
+ }
850
+ }
851
+
852
+ await new Promise((resolve) => setTimeout(resolve, 200));
853
+ }
854
+
855
+ const elapsed = Date.now() - startTime;
856
+ const errorMsg = lastError ? `: ${lastError.message}` : '';
857
+ throw new Error(`Container ${name} failed to start within ${timeout}ms (${elapsed}ms elapsed)${errorMsg}`);
858
+ }
859
+
860
+ /**
861
+ * Check if a port is listening
862
+ * @private
863
+ */
864
+ private async isPortListening(host: string, port: number): Promise<boolean> {
865
+ return new Promise((resolve) => {
866
+ const socket = new net.Socket();
867
+
868
+ socket.setTimeout(100);
869
+ socket.on('connect', () => {
870
+ socket.destroy();
871
+ resolve(true);
872
+ });
873
+ socket.on('timeout', () => {
874
+ socket.destroy();
875
+ resolve(false);
876
+ });
877
+ socket.on('error', () => {
878
+ resolve(false);
879
+ });
880
+
881
+ socket.connect(port, host);
882
+ });
883
+ }
884
+
885
+ /**
886
+ * Get a container by ID
887
+ *
888
+ * @param id - Container ID
889
+ * @returns DockerContainer or undefined if not found
890
+ */
891
+ async getContainer(id: string): Promise<DockerContainer | undefined> {
892
+ return this.containers.get(id);
893
+ }
894
+
895
+ /**
896
+ * Clean up a specific container
897
+ *
898
+ * @param id - Container ID to clean up
899
+ */
900
+ async cleanupContainer(id: string): Promise<void> {
901
+ const container = this.containers.get(id);
902
+ if (container) {
903
+ await container.cleanup();
904
+ }
905
+ }
906
+
907
+ /**
908
+ * Clean up all containers managed by this instance
909
+ */
910
+ async cleanupAll(): Promise<void> {
911
+ if (this.cleanupInProgress) {
912
+ this.log('Cleanup already in progress, skipping');
913
+ return;
914
+ }
915
+
916
+ this.cleanupInProgress = true;
917
+
918
+ try {
919
+ this.log(`Starting cleanup of ${this.containers.size} containers`);
920
+
921
+ // Cleanup containers in parallel with Promise.allSettled to handle failures
922
+ const cleanupPromises = Array.from(this.containers.values()).map((container) =>
923
+ container
924
+ .cleanup()
925
+ .then(() => {
926
+ this.log(`Cleanup succeeded: ${container.name}`);
927
+ })
928
+ .catch((error) => {
929
+ this.logError(`Cleanup failed for ${container.name}`, error);
930
+ // Still continue cleaning up other containers
931
+ })
932
+ );
933
+
934
+ const results = await Promise.allSettled(cleanupPromises);
935
+
936
+ const failed = results.filter((r) => r.status === 'rejected').length;
937
+ if (failed > 0) {
938
+ this.log(`Cleanup completed with ${failed} failures`);
939
+ } else {
940
+ this.log('All containers cleaned up successfully');
941
+ }
942
+
943
+ // Cleanup networks
944
+ this.log(`Cleaning up ${this.networks.size} networks`);
945
+ const networkArray = Array.from(this.networks);
946
+ for (const network of networkArray) {
947
+ try {
948
+ this.log(`Removing network: ${network}`);
949
+ execFileSync(this.dockerPath, ['network', 'rm', network], { stdio: 'ignore' });
950
+ this.log(`Network removed: ${network}`);
951
+ } catch (error) {
952
+ this.logError(`Failed to remove network ${network}`, error);
953
+ // Continue with other networks
954
+ }
955
+ }
956
+
957
+ this.containers.clear();
958
+ this.usedPorts.clear();
959
+ this.networks.clear();
960
+
961
+ this.log('Final cleanup completed');
962
+ } finally {
963
+ this.cleanupInProgress = false;
964
+ }
965
+ }
966
+
967
+ /**
968
+ * Async cleanup - for signal handlers
969
+ * @private
970
+ */
971
+ private async cleanupAllAsync(): Promise<void> {
972
+ this.log('Initiating graceful cleanup of all test containers');
973
+ await this.cleanupAll();
974
+ }
975
+
976
+ /**
977
+ * Synchronous cleanup - for process exit
978
+ * @private
979
+ */
980
+ private cleanupSync(): void {
981
+ try {
982
+ this.log('Performing synchronous cleanup of remaining test containers');
983
+
984
+ const isWindows = process.platform === 'win32';
985
+
986
+ if (isWindows) {
987
+ // Windows-specific cleanup
988
+ this.cleanupSyncWindows();
989
+ } else {
990
+ // Unix-like systems
991
+ this.cleanupSyncUnix();
992
+ }
993
+
994
+ this.log('Synchronous cleanup completed');
995
+ } catch (error) {
996
+ this.logError('Error during synchronous cleanup', error);
997
+ // Don't throw during process exit cleanup
998
+ }
999
+ }
1000
+
1001
+ /**
1002
+ * Windows-specific synchronous cleanup
1003
+ * @private
1004
+ */
1005
+ private cleanupSyncWindows(): void {
1006
+ try {
1007
+ // Get container IDs with test.cleanup label
1008
+ const containerIds = execFileSync(this.dockerPath, ['ps', '-a', '--filter', 'label=test.cleanup=true', '-q'], {
1009
+ encoding: 'utf8',
1010
+ stdio: ['pipe', 'pipe', 'ignore'],
1011
+ }).trim();
1012
+
1013
+ if (containerIds) {
1014
+ const ids = containerIds.split('\n').filter((id) => id.trim());
1015
+ this.log(`Found ${ids.length} test containers to clean up`);
1016
+
1017
+ for (const id of ids) {
1018
+ try {
1019
+ const trimmedId = id.trim();
1020
+ this.log(`Stopping container: ${trimmedId}`);
1021
+ try {
1022
+ execFileSync(this.dockerPath, ['stop', '-t', '5', trimmedId], { stdio: 'ignore' });
1023
+ } catch {
1024
+ // Already stopped
1025
+ }
1026
+
1027
+ this.log(`Removing container: ${trimmedId}`);
1028
+ execFileSync(this.dockerPath, ['rm', '-f', trimmedId], { stdio: 'ignore' });
1029
+ this.log(`Container removed: ${trimmedId}`);
1030
+ } catch (error) {
1031
+ this.logError(`Failed to cleanup container ${id}`, error);
1032
+ // Continue with other containers
1033
+ }
1034
+ }
1035
+ }
1036
+
1037
+ // Remove test networks
1038
+ try {
1039
+ const networkIds = execFileSync(
1040
+ this.dockerPath,
1041
+ ['network', 'ls', '--filter', 'label=test.cleanup=true', '-q'],
1042
+ {
1043
+ encoding: 'utf8',
1044
+ stdio: ['pipe', 'pipe', 'ignore'],
1045
+ }
1046
+ ).trim();
1047
+
1048
+ if (networkIds) {
1049
+ const ids = networkIds.split('\n').filter((id) => id.trim());
1050
+ this.log(`Found ${ids.length} test networks to clean up`);
1051
+
1052
+ for (const id of ids) {
1053
+ try {
1054
+ this.log(`Removing network: ${id.trim()}`);
1055
+ execFileSync(this.dockerPath, ['network', 'rm', id.trim()], { stdio: 'ignore' });
1056
+ this.log(`Network removed: ${id.trim()}`);
1057
+ } catch (error) {
1058
+ this.logError(`Failed to cleanup network ${id}`, error);
1059
+ }
1060
+ }
1061
+ }
1062
+ } catch (error) {
1063
+ this.logError('Failed to cleanup networks', error);
1064
+ }
1065
+ } catch (error) {
1066
+ this.logError('Windows cleanup failed', error);
1067
+ }
1068
+ }
1069
+
1070
+ /**
1071
+ * Unix-specific synchronous cleanup
1072
+ * @private
1073
+ */
1074
+ private cleanupSyncUnix(): void {
1075
+ try {
1076
+ // Remove containers
1077
+ const containerCmd = `"${this.dockerPath}" ps -a --filter "label=test.cleanup=true" -q`;
1078
+ try {
1079
+ const ids = execSync(containerCmd, { encoding: 'utf8', stdio: ['pipe', 'pipe', 'ignore'] }).trim();
1080
+ if (ids) {
1081
+ const containerIds = ids.split('\n').filter((id) => id.trim());
1082
+ this.log(`Found ${containerIds.length} test containers to clean up`);
1083
+
1084
+ for (const id of containerIds) {
1085
+ try {
1086
+ const trimmedId = id.trim();
1087
+ this.log(`Stopping container: ${trimmedId}`);
1088
+ try {
1089
+ execFileSync(this.dockerPath, ['stop', '-t', '5', trimmedId], { stdio: 'ignore' });
1090
+ } catch {
1091
+ // Already stopped
1092
+ }
1093
+
1094
+ this.log(`Removing container: ${trimmedId}`);
1095
+ execFileSync(this.dockerPath, ['rm', '-f', trimmedId], { stdio: 'ignore' });
1096
+ this.log(`Container removed: ${trimmedId}`);
1097
+ } catch (error) {
1098
+ this.logError(`Failed to cleanup container ${id}`, error);
1099
+ }
1100
+ }
1101
+ }
1102
+ } catch (error) {
1103
+ this.logError('Failed to cleanup containers', error);
1104
+ }
1105
+
1106
+ // Remove test networks
1107
+ try {
1108
+ const networkCmd = `"${this.dockerPath}" network ls --filter "label=test.cleanup=true" -q`;
1109
+ const ids = execSync(networkCmd, { encoding: 'utf8', stdio: ['pipe', 'pipe', 'ignore'] }).trim();
1110
+ if (ids) {
1111
+ const networkIds = ids.split('\n').filter((id) => id.trim());
1112
+ this.log(`Found ${networkIds.length} test networks to clean up`);
1113
+
1114
+ for (const id of networkIds) {
1115
+ try {
1116
+ this.log(`Removing network: ${id.trim()}`);
1117
+ execFileSync(this.dockerPath, ['network', 'rm', id.trim()], { stdio: 'ignore' });
1118
+ this.log(`Network removed: ${id.trim()}`);
1119
+ } catch (error) {
1120
+ this.logError(`Failed to cleanup network ${id}`, error);
1121
+ }
1122
+ }
1123
+ }
1124
+ } catch (error) {
1125
+ this.logError('Failed to cleanup networks', error);
1126
+ }
1127
+
1128
+ // Remove test volumes
1129
+ try {
1130
+ const volumeCmd = `"${this.dockerPath}" volume ls --filter "label=test.cleanup=true" -q`;
1131
+ const ids = execSync(volumeCmd, { encoding: 'utf8', stdio: ['pipe', 'pipe', 'ignore'] }).trim();
1132
+ if (ids) {
1133
+ const volumeIds = ids.split('\n').filter((id) => id.trim());
1134
+ this.log(`Found ${volumeIds.length} test volumes to clean up`);
1135
+
1136
+ for (const id of volumeIds) {
1137
+ try {
1138
+ this.log(`Removing volume: ${id.trim()}`);
1139
+ execFileSync(this.dockerPath, ['volume', 'rm', '-f', id.trim()], { stdio: 'ignore' });
1140
+ this.log(`Volume removed: ${id.trim()}`);
1141
+ } catch (error) {
1142
+ this.logError(`Failed to cleanup volume ${id}`, error);
1143
+ }
1144
+ }
1145
+ }
1146
+ } catch (error) {
1147
+ this.logError('Failed to cleanup volumes', error);
1148
+ }
1149
+ } catch (error) {
1150
+ this.logError('Unix cleanup failed', error);
1151
+ }
1152
+ }
1153
+
1154
+ /**
1155
+ * Helper to run tests with a container
1156
+ *
1157
+ * @param options - Container configuration
1158
+ * @param testFn - Test function that receives the container
1159
+ * @returns Promise resolving to test function result
1160
+ *
1161
+ * @example
1162
+ * ```typescript
1163
+ * await DockerTestManager.withContainer(
1164
+ * { image: 'redis:7-alpine', ports: { 6379: 'auto' } },
1165
+ * async (container) => {
1166
+ * // Use container in tests
1167
+ * const port = container.port!;
1168
+ * // ...
1169
+ * }
1170
+ * );
1171
+ * ```
1172
+ */
1173
+ static async withContainer<T>(
1174
+ options: ContainerOptions,
1175
+ testFn: (container: DockerContainer) => Promise<T>
1176
+ ): Promise<T> {
1177
+ const manager = DockerTestManager.getInstance();
1178
+ const container = await manager.createContainer(options);
1179
+
1180
+ try {
1181
+ return await testFn(container);
1182
+ } finally {
1183
+ await container.cleanup();
1184
+ }
1185
+ }
1186
+ }