feat: implement automatic container cleanup to prevent port conflicts

- Add cleanupStaleContainers() method to ContainerPool that runs before initialization
- Use Docker API to find and remove stale zemu containers automatically
- Enhanced global test setup with comprehensive process exit handlers
- Added handlers for SIGINT, SIGTERM, beforeExit, uncaughtException, and unhandledRejection
- Prevents port allocation conflicts by cleaning up leftover containers from previous runs
- No more manual container cleanup required - the library manages this automatically

This resolves port conflicts like 'Bind for 0.0.0.0:15000 failed: port is already allocated'
that occurred when containers weren't properly cleaned up from interrupted test runs.

Author: jleni

src/containerPool.ts

@@ -16,6 +16,7 @@
 
 import axios from 'axios'
 import axiosRetry from 'axios-retry'
+import Docker from 'dockerode'
 import rndstr from 'randomstring'
 import { BASE_NAME, DEFAULT_EMU_IMG, DEFAULT_HOST, DEFAULT_START_DELAY } from './constants'
 import EmuContainer from './emulator'
@@ -47,6 +48,7 @@ export class ContainerPool {
   private portRanges: Map<TModel, { transportStart: number; speculosStart: number }> = new Map()
   private readonly host: string = DEFAULT_HOST
   private readonly emuImage: string = DEFAULT_EMU_IMG
+  private readonly docker: Docker = new Docker()
 
   private constructor() {
     this.initializePortRanges()
@@ -69,6 +71,9 @@ export class ContainerPool {
   }
 
   async initialize(config: IPoolConfig): Promise<void> {
+    // Clean up any stale containers before initializing new ones
+    await this.cleanupStaleContainers()
+
     const initPromises: Promise<void>[] = []
 
     for (const [model, count] of Object.entries(config)) {
@@ -307,6 +312,41 @@ export class ContainerPool {
     }
   }
 
+  private async cleanupStaleContainers(): Promise<void> {
+    try {
+      // List all containers that match our naming pattern
+      const containers = await this.docker.listContainers({ 
+        all: true,
+        filters: { 
+          name: [`${BASE_NAME}-pool-`, `${BASE_NAME}-`] 
+        }
+      })
+
+      if (containers.length === 0) {
+        return
+      }
+
+      console.warn(`Found ${containers.length} stale zemu containers, cleaning up...`)
+
+      // Remove all found containers in parallel
+      const cleanupPromises = containers.map(async (containerInfo) => {
+        try {
+          const container = this.docker.getContainer(containerInfo.Id)
+          await container.remove({ force: true })
+        } catch (error) {
+          // Ignore errors when removing containers (they might already be removed)
+          console.warn(`Failed to remove stale container ${containerInfo.Names?.[0]}:`, error)
+        }
+      })
+
+      await Promise.all(cleanupPromises)
+      console.warn(`Cleaned up ${containers.length} stale containers`)
+    } catch (error) {
+      console.warn('Failed to cleanup stale containers:', error)
+      // Don't throw - we want initialization to continue even if cleanup fails
+    }
+  }
+
   async cleanup(): Promise<void> {
     const cleanupPromises: Promise<void>[] = []
 

tests/globalsetup.ts

@@ -1,9 +1,27 @@
 import Zemu from '../src'
 
 const catchExit = () => {
-  process.on('SIGINT', () => {
+  const cleanup = () => {
     console.log('Stopping dangling containers')
     Zemu.stopAllEmuContainers()
+  }
+
+  // Handle various exit signals
+  process.on('SIGINT', cleanup)
+  process.on('SIGTERM', cleanup)
+  process.on('beforeExit', cleanup)
+
+  // Handle uncaught exceptions
+  process.on('uncaughtException', (error) => {
+    console.error('Uncaught exception, cleaning up containers:', error)
+    cleanup()
+    process.exit(1)
+  })
+
+  process.on('unhandledRejection', (reason, promise) => {
+    console.error('Unhandled rejection, cleaning up containers:', reason)
+    cleanup()
+    process.exit(1)
   })
 }