detox 20.12.2 → 20.13.0

package/src/devices/{common/drivers/android/tools → allocation/drivers/android}/FreeDeviceFinder.js

@@ -1,6 +1,6 @@
-const log = require('../../../../../utils/logger').child({ cat: 'device' });
+const log = require('../../../../utils/logger').child({ cat: 'device' });
 
-const DEVICE_LOOKUP_LOG_EVT = 'DEVICE_LOOKUP';
+const DEVICE_LOOKUP = { event: 'DEVICE_LOOKUP' };
 
 class FreeDeviceFinder {
   constructor(adb, deviceRegistry) {
@@ -10,8 +10,9 @@ class FreeDeviceFinder {
 
   async findFreeDevice(deviceQuery) {
     const { devices } = await this.adb.devices();
+    const takenDevices = this.deviceRegistry.getTakenDevicesSync();
     for (const candidate of devices) {
-      if (await this._isDeviceFreeAndMatching(candidate, deviceQuery)) {
+      if (await this._isDeviceFreeAndMatching(takenDevices, candidate, deviceQuery)) {
         return candidate.adbName;
       }
     }
@@ -19,30 +20,30 @@ class FreeDeviceFinder {
   }
 
   /**
-   * @protected
+   * @private
    */
-  async _isDeviceFreeAndMatching(candidate, deviceQuery) {
+  async _isDeviceFreeAndMatching(takenDevices, candidate, deviceQuery) {
     const { adbName } = candidate;
 
-    const isTaken = this.deviceRegistry.includes(adbName);
+    const isTaken = takenDevices.includes(adbName);
     if (isTaken) {
-      log.debug({ event: DEVICE_LOOKUP_LOG_EVT }, `Device ${adbName} is already taken, skipping...`);
+      log.debug(DEVICE_LOOKUP, `Device ${adbName} is already taken, skipping...`);
       return false;
     }
 
     const isOffline = candidate.status === 'offline';
     if (isOffline) {
-      log.debug({ event: DEVICE_LOOKUP_LOG_EVT }, `Device ${adbName} is offline, skipping...`);
+      log.debug(DEVICE_LOOKUP, `Device ${adbName} is offline, skipping...`);
       return false;
     }
 
     const isMatching = await this._isDeviceMatching(candidate, deviceQuery);
     if (!isMatching) {
-      log.debug({ event: DEVICE_LOOKUP_LOG_EVT }, `Device ${adbName} does not match "${deviceQuery}"`);
+      log.debug(DEVICE_LOOKUP, `Device ${adbName} does not match "${deviceQuery}"`);
       return false;
     }
 
-    log.debug({ event: DEVICE_LOOKUP_LOG_EVT }, `Found a matching & free device ${candidate.adbName}`);
+    log.debug(DEVICE_LOOKUP, `Found a matching & free device ${candidate.adbName}`);
     return true;
   }
 

package/src/devices/allocation/drivers/android/attached/AttachedAndroidAllocDriver.js

@@ -1,20 +1,26 @@
-// @ts-nocheck
-const AttachedAndroidDeviceCookie = require('../../../../cookies/AttachedAndroidDeviceCookie');
-const AllocationDriverBase = require('../../AllocationDriverBase');
+/**
+ * @typedef {import('../../AllocationDriverBase').AllocationDriverBase} AllocationDriverBase
+ * @typedef {import('../../../../common/drivers/android/cookies').AndroidDeviceCookie} AndroidDeviceCookie
+ */
 
-class AttachedAndroidAllocDriver extends AllocationDriverBase {
+/**
+ * @implements {AllocationDriverBase}
+ */
+class AttachedAndroidAllocDriver {
   /**
-   * @param adb { ADB }
-   * @param deviceRegistry { DeviceRegistry }
-   * @param freeDeviceFinder { FreeDeviceFinder }
-   * @param attachedAndroidLauncher { AttachedAndroidLauncher }
+   * @param {object} options
+   * @param {import('../../../../common/drivers/android/exec/ADB')} options.adb
+   * @param {import('../../../DeviceRegistry')} options.deviceRegistry
+   * @param {import('../FreeDeviceFinder')} options.freeDeviceFinder
    */
-  constructor({ adb, deviceRegistry, freeDeviceFinder, attachedAndroidLauncher }) {
-    super();
+  constructor({ adb, deviceRegistry, freeDeviceFinder }) {
     this._adb = adb;
     this._deviceRegistry = deviceRegistry;
     this._freeDeviceFinder = freeDeviceFinder;
-    this._attachedAndroidLauncher = attachedAndroidLauncher;
+  }
+
+  async init() {
+    await this._deviceRegistry.unregisterZombieDevices();
   }
 
   /**
@@ -23,13 +29,13 @@ class AttachedAndroidAllocDriver extends AllocationDriverBase {
    */
   async allocate(deviceConfig) {
     const adbNamePattern = deviceConfig.device.adbName;
-    const adbName = await this._deviceRegistry.allocateDevice(() => this._freeDeviceFinder.findFreeDevice(adbNamePattern));
+    const adbName = await this._deviceRegistry.registerDevice(() => this._freeDeviceFinder.findFreeDevice(adbNamePattern));
 
-    return new AttachedAndroidDeviceCookie(adbName);
+    return { id: adbName, adbName };
   }
 
   /**
-   * @param {AttachedAndroidDeviceCookie} deviceCookie
+   * @param {AndroidDeviceCookie} deviceCookie
    * @returns {Promise<void>}
    */
   async postAllocate(deviceCookie) {
@@ -38,16 +44,15 @@ class AttachedAndroidAllocDriver extends AllocationDriverBase {
     // TODO Also disable native animations?
     await this._adb.apiLevel(adbName);
     await this._adb.unlockScreen(adbName);
-    await this._attachedAndroidLauncher.notifyLaunchCompleted(adbName);
   }
 
   /**
-   * @param cookie { AttachedAndroidDeviceCookie }
+   * @param cookie { AndroidDeviceCookie }
    * @return {Promise<void>}
    */
   async free(cookie) {
     const { adbName } = cookie;
-    await this._deviceRegistry.disposeDevice(adbName);
+    await this._deviceRegistry.unregisterDevice(adbName);
   }
 }
 

package/src/devices/allocation/drivers/android/emulator/EmulatorAllocDriver.js

@@ -1,32 +1,58 @@
-// @ts-nocheck
+/**
+ * @typedef {import('../../AllocationDriverBase').AllocationDriverBase} AllocationDriverBase
+ * @typedef {import('../../../../common/drivers/android/cookies').AndroidDeviceCookie} AndroidDeviceCookie
+ */
+
 const _ = require('lodash');
 
-const AndroidEmulatorCookie = require('../../../../cookies/AndroidEmulatorCookie');
-const AllocationDriverBase = require('../../AllocationDriverBase');
+const Deferred = require('../../../../../utils/Deferred');
+const log = require('../../../../../utils/logger').child({ cat: 'device,device-allocation' });
 
 const { patchAvdSkinConfig } = require('./patchAvdSkinConfig');
 
-class EmulatorAllocDriver extends AllocationDriverBase {
+/**
+ * @implements {AllocationDriverBase}
+ */
+class EmulatorAllocDriver {
   /**
-   * @param adb { ADB }
-   * @param avdValidator { AVDValidator }
-   * @param emulatorVersionResolver { EmulatorVersionResolver }
-   * @param emulatorLauncher { EmulatorLauncher }
-   * @param allocationHelper { EmulatorAllocationHelper }
+   * @param {object} options
+   * @param {import('../../../../common/drivers/android/exec/ADB')} options.adb
+   * @param {import('./AVDValidator')} options.avdValidator
+   * @param {DetoxInternals.RuntimeConfig} options.detoxConfig
+   * @param {import('../../../DeviceRegistry')} options.deviceRegistry
+   * @param {import('./FreeEmulatorFinder')} options.freeDeviceFinder
+   * @param {import('./FreePortFinder')} options.freePortFinder
+   * @param {import('./EmulatorLauncher')} options.emulatorLauncher
+   * @param {import('./EmulatorVersionResolver')} options.emulatorVersionResolver
    */
-  constructor({ adb, avdValidator, emulatorVersionResolver, emulatorLauncher, allocationHelper }) {
-    super();
+  constructor({
+    adb,
+    avdValidator,
+    detoxConfig,
+    deviceRegistry,
+    freeDeviceFinder,
+    freePortFinder,
+    emulatorVersionResolver,
+    emulatorLauncher
+  }) {
     this._adb = adb;
     this._avdValidator = avdValidator;
+    this._deviceRegistry = deviceRegistry;
     this._emulatorVersionResolver = emulatorVersionResolver;
     this._emulatorLauncher = emulatorLauncher;
-    this._allocationHelper = allocationHelper;
-    this._launchInfo = {};
+    this._freeDeviceFinder = freeDeviceFinder;
+    this._freePortFinder = freePortFinder;
+    this._shouldShutdown = detoxConfig.behavior.cleanup.shutdownDevice;
+    this._fixAvdConfigIniSkinNameIfNeeded = _.memoize(this._fixAvdConfigIniSkinNameIfNeeded.bind(this));
+  }
+
+  async init() {
+    await this._deviceRegistry.unregisterZombieDevices();
   }
 
   /**
    * @param deviceConfig
-   * @returns {Promise<AndroidEmulatorCookie>}
+   * @returns {Promise<AndroidDeviceCookie>}
    */
   async allocate(deviceConfig) {
     const avdName = deviceConfig.device.avdName;
@@ -34,50 +60,83 @@ class EmulatorAllocDriver extends AllocationDriverBase {
     await this._avdValidator.validate(avdName, deviceConfig.headless);
     await this._fixAvdConfigIniSkinNameIfNeeded(avdName, deviceConfig.headless);
 
-    const allocResult = await this._allocationHelper.allocateDevice(avdName);
-    const { adbName } = allocResult;
-
-    this._launchInfo[adbName] = {
-      avdName,
-      isRunning: allocResult.isRunning,
-      launchOptions: {
-        bootArgs: deviceConfig.bootArgs,
-        gpuMode: deviceConfig.gpuMode,
-        headless: deviceConfig.headless,
-        readonly: deviceConfig.readonly,
-        port: allocResult.placeholderPort,
-      },
-    };
+    const adbName = await this._deviceRegistry.registerDevice(async () => {
+      let adbName = await this._freeDeviceFinder.findFreeDevice(avdName);
+      if (!adbName) {
+        const port = await this._freePortFinder.findFreePort();
+        adbName = `emulator-${port}`;
+
+        await this._emulatorLauncher.launch({
+          bootArgs: deviceConfig.bootArgs,
+          gpuMode: deviceConfig.gpuMode,
+          headless: deviceConfig.headless,
+          readonly: deviceConfig.readonly,
+          avdName,
+          adbName,
+          port,
+        });
+      }
 
-    return new AndroidEmulatorCookie(adbName);
+      return adbName;
+    });
+
+    return {
+      id: adbName,
+      adbName,
+      name: `${adbName} (${avdName})`,
+    };
   }
 
   /**
-   * @param {AndroidEmulatorCookie} deviceCookie
-   * @returns {Promise<void>}
+   * @param {AndroidDeviceCookie} deviceCookie
    */
   async postAllocate(deviceCookie) {
     const { adbName } = deviceCookie;
-    const { avdName, isRunning, launchOptions } = this._launchInfo[adbName];
 
-    await this._emulatorLauncher.launch(avdName, adbName, isRunning, launchOptions);
+    await this._emulatorLauncher.awaitEmulatorBoot(adbName);
     await this._adb.apiLevel(adbName);
     await this._adb.disableAndroidAnimations(adbName);
     await this._adb.unlockScreen(adbName);
   }
 
   /**
-   * @param cookie { AndroidEmulatorCookie }
-   * @param options { DeallocOptions }
-   * @return { Promise<void> }
+   * @param cookie {AndroidDeviceCookie}
+   * @param options {Partial<import('../../AllocationDriverBase').DeallocOptions>}
+   * @return {Promise<void>}
    */
   async free(cookie, options = {}) {
     const { adbName } = cookie;
 
-    await this._allocationHelper.deallocateDevice(adbName);
-
     if (options.shutdown) {
+      await this._doShutdown(adbName);
+      await this._deviceRegistry.unregisterDevice(adbName);
+    } else {
+      await this._deviceRegistry.releaseDevice(adbName);
+    }
+  }
+
+  async cleanup() {
+    if (this._shouldShutdown) {
+      const { devices } = await this._adb.devices();
+      const actualEmulators = devices.map((device) => device.adbName);
+      const sessionDevices = await this._deviceRegistry.readSessionDevices();
+      const emulatorsToShutdown = _.intersection(sessionDevices.getIds(), actualEmulators);
+      const shutdownPromises = emulatorsToShutdown.map((adbName) => this._doShutdown(adbName));
+      await Promise.all(shutdownPromises);
+    }
+
+    await this._deviceRegistry.unregisterSessionDevices();
+  }
+
+  /**
+   * @param {string} adbName
+   * @return {Promise<void>}
+   */
+  async _doShutdown(adbName) {
+    try {
       await this._emulatorLauncher.shutdown(adbName);
+    } catch (err) {
+      log.warn({ err }, `Failed to shutdown emulator ${adbName}`);
     }
   }
 

package/src/devices/allocation/drivers/android/emulator/EmulatorLauncher.js

@@ -1,49 +1,53 @@
 // @ts-nocheck
 const { DetoxRuntimeError } = require('../../../../../errors');
-const log = require('../../../../../utils/logger').child({ cat: 'device' });
 const retry = require('../../../../../utils/retry');
-const traceMethods = require('../../../../../utils/traceMethods');
-const DeviceLauncher = require('../../../../common/drivers/DeviceLauncher');
 const { LaunchCommand } = require('../../../../common/drivers/android/emulator/exec/EmulatorExec');
 
 const { launchEmulatorProcess } = require('./launchEmulatorProcess');
 
 const isUnknownEmulatorError = (err) => (err.message || '').includes('failed with code null');
 
-class EmulatorLauncher extends DeviceLauncher {
-  constructor({ adb, emulatorExec, eventEmitter }) {
-    super(eventEmitter);
+class EmulatorLauncher {
+  constructor({ adb, emulatorExec }) {
     this._adb = adb;
     this._emulatorExec = emulatorExec;
-    traceMethods(log, this, ['_awaitEmulatorBoot']);
   }
 
   /**
-   * @param avdName { String }
-   * @param adbName { String }
-   * @param isRunning { Boolean }
-   * @param options { Object }
-   * @param options.port { Number | undefined }
-   * @param options.bootArgs { String | undefined }
-   * @param options.gpuMode { String | undefined }
-   * @param options.headless { Boolean }
-   * @param options.readonly { Boolean }
+   * @param {object} options
+   * @param {string} options.avdName
+   * @param {string} options.adbName
+   * @param {number} options.port
+   * @param {string | undefined} options.bootArgs
+   * @param {string | undefined} options.gpuMode
+   * @param {boolean} options.headless
+   * @param {boolean} options.readonly
    */
-  async launch(avdName, adbName, isRunning, options = { port: undefined }) {
-    if (!isRunning) {
-      const launchCommand = new LaunchCommand(avdName, options);
-      await retry({
-        retries: 2,
-        interval: 100,
-        conditionFn: isUnknownEmulatorError,
-      }, () => this._launchEmulator(avdName, launchCommand, adbName));
-    }
-    await this._awaitEmulatorBoot(adbName);
-    await this._notifyBootEvent(adbName, avdName, !isRunning);
+  async launch(options) {
+    const launchCommand = new LaunchCommand(options);
+    await retry({
+      retries: 2,
+      interval: 100,
+      conditionFn: isUnknownEmulatorError,
+    }, () => launchEmulatorProcess(this._emulatorExec, this._adb, launchCommand));
+  }
+
+  /**
+   * @param {string} adbName
+   */
+  async awaitEmulatorBoot(adbName) {
+    await retry({ retries: 240, interval: 2500, shouldUnref: true }, async () => {
+      const isBootComplete = await this._adb.isBootComplete(adbName);
+
+      if (!isBootComplete) {
+        throw new DetoxRuntimeError({
+          message: `Waited for ${adbName} to complete booting for too long!`,
+        });
+      }
+    });
   }
 
   async shutdown(adbName) {
-    await this._notifyPreShutdown(adbName);
     await this._adb.emuKill(adbName);
     await retry({
       retries: 5,
@@ -57,23 +61,6 @@ class EmulatorLauncher extends DeviceLauncher {
         });
       }
     });
-    await this._notifyShutdownCompleted(adbName);
-  }
-
-  _launchEmulator(emulatorName, launchCommand, adbName) {
-    return launchEmulatorProcess(emulatorName, this._emulatorExec, launchCommand, this._adb, adbName);
-  }
-
-  async _awaitEmulatorBoot(adbName) {
-    await retry({ retries: 240, interval: 2500, shouldUnref: true }, async () => {
-      const isBootComplete = await this._adb.isBootComplete(adbName);
-
-      if (!isBootComplete) {
-        throw new DetoxRuntimeError({
-          message: `Waited for ${adbName} to complete booting for too long!`,
-        });
-      }
-    });
   }
 }
 

package/src/devices/allocation/drivers/android/emulator/FreeEmulatorFinder.js

@@ -1,4 +1,4 @@
-const FreeDeviceFinder = require('../../../../common/drivers/android/tools/FreeDeviceFinder');
+const FreeDeviceFinder = require('../FreeDeviceFinder');
 
 class FreeEmulatorFinder extends FreeDeviceFinder {
   /**

package/src/devices/allocation/drivers/android/emulator/FreePortFinder.js

@@ -0,0 +1,37 @@
+const net = require('net');
+
+class FreePortFinder {
+  constructor({ min = 10000, max = 20000 } = {}) {
+    this._min = min;
+    this._max = max;
+  }
+
+  async findFreePort() {
+    let port;
+
+    do {
+      const min = this._min;
+      const max = this._max;
+      port = Math.random() * (max - min) + min;
+      port = port & 0xFFFFFFFE; // Should always be even
+    } while (await this.isPortTaken(port));
+
+    return port;
+  }
+
+  async isPortTaken(port) {
+    return new Promise((resolve, reject) => {
+      const tester = net.createServer()
+        .once('error', /** @param {*} err */ (err) => {
+          /* istanbul ignore next */
+          return err && err.code === 'EADDRINUSE' ? resolve(true) : reject(err);
+        })
+        .once('listening', () => {
+          tester.once('close', () => resolve(false)).close();
+        })
+        .listen(port);
+    });
+  }
+}
+
+module.exports = FreePortFinder;

package/src/devices/allocation/drivers/android/emulator/launchEmulatorProcess.js

@@ -4,10 +4,10 @@ const _ = require('lodash');
 
 const unitLogger = require('../../../../../utils/logger').child({ cat: 'device' });
 
-function launchEmulatorProcess(emulatorName, emulatorExec, emulatorLaunchCommand, adb, adbName) {
+function launchEmulatorProcess(emulatorExec, adb, emulatorLaunchCommand) {
   let childProcessOutput;
   const portName = emulatorLaunchCommand.port ? `-${emulatorLaunchCommand.port}` : '';
-  const tempLog = `./${emulatorName}${portName}.log`;
+  const tempLog = `./${emulatorLaunchCommand.avdName}${portName}.log`;
   const stdout = fs.openSync(tempLog, 'a');
   const stderr = fs.openSync(tempLog, 'a');
 
@@ -31,7 +31,7 @@ function launchEmulatorProcess(emulatorName, emulatorExec, emulatorLaunchCommand
 
   log = log.child({ child_pid: childProcessPromise.childProcess.pid });
 
-  adb.waitForDevice(adbName).then(() => childProcessPromise._cpResolve());
+  adb.waitForDevice(emulatorLaunchCommand.adbName).then(() => childProcessPromise._cpResolve());
 
   return childProcessPromise.then(() => true).catch((err) => {
     detach();

package/src/devices/allocation/drivers/android/genycloud/GenyAllocDriver.js

@@ -1,25 +1,43 @@
+/**
+ * @typedef {import('../../AllocationDriverBase').AllocationDriverBase} AllocationDriverBase
+ * @typedef {import('../../../../common/drivers/android/cookies').GenycloudEmulatorCookie} GenycloudEmulatorCookie
+ */
+
 const { DetoxRuntimeError } = require('../../../../../errors');
 const Timer = require('../../../../../utils/Timer');
-const GenycloudEmulatorCookie = require('../../../../cookies/GenycloudEmulatorCookie');
-const AllocationDriverBase = require('../../AllocationDriverBase');
+const log = require('../../../../../utils/logger').child({ cat: 'device' });
+
+const GenyRegistry = require('./GenyRegistry');
 
-class GenyAllocDriver extends AllocationDriverBase {
+const events = {
+  GENYCLOUD_TEARDOWN: { event: 'GENYCLOUD_TEARDOWN' },
+};
 
+/**
+ * @implements {AllocationDriverBase}
+ */
+class GenyAllocDriver {
   /**
    * @param {object} options
    * @param {import('../../../../common/drivers/android/exec/ADB')} options.adb
-   * @param {import('./GenyRecipeQuerying')} options.recipeQuerying
-   * @param {import('./GenyInstanceAllocationHelper')} options.allocationHelper
+   * @param {DetoxInternals.SessionState} options.detoxSession
+   * @param {import('./GenyRegistry')} options.genyRegistry
    * @param {import('./GenyInstanceLauncher')} options.instanceLauncher
+   * @param {import('./GenyRecipeQuerying')} options.recipeQuerying
    */
-  constructor({ adb, recipeQuerying, allocationHelper, instanceLauncher }) {
-    super();
-
+  constructor({
+    adb,
+    detoxSession,
+    genyRegistry = new GenyRegistry(),
+    instanceLauncher,
+    recipeQuerying,
+  }) {
     this._adb = adb;
-    this._recipeQuerying = recipeQuerying;
+    this._detoxSessionId = detoxSession.id;
+    this._genyRegistry = genyRegistry;
     this._instanceLauncher = instanceLauncher;
-    this._instanceAllocationHelper = allocationHelper;
-    this._launchInfo = {};
+    this._recipeQuerying = recipeQuerying;
+    this._instanceCounter = 0;
   }
 
   /**
@@ -27,47 +45,83 @@ class GenyAllocDriver extends AllocationDriverBase {
    * @return {Promise<GenycloudEmulatorCookie>}
    */
   async allocate(deviceConfig) {
+    await new Promise((resolve) => setTimeout(resolve, 10000));
     const deviceQuery = deviceConfig.device;
     const recipe = await this._recipeQuerying.getRecipeFromQuery(deviceQuery);
     this._assertRecipe(deviceQuery, recipe);
 
-    const { instance, isNew } = await this._instanceAllocationHelper.allocateDevice(recipe);
-    this._launchInfo[instance.uuid] = { isNew };
-    return new GenycloudEmulatorCookie(instance);
+    let instance = this._genyRegistry.findFreeInstance(recipe);
+    if (!instance) {
+      const instanceName = `Detox.${this._detoxSessionId}.${this._instanceCounter++}`;
+      instance = await this._instanceLauncher.launch(recipe, instanceName);
+      this._genyRegistry.addInstance(instance, recipe);
+    }
+
+    return {
+      id: instance.uuid,
+      adbName: instance.adbName,
+      name: instance.name,
+      instance,
+    };
   }
 
   /**
    * @param {GenycloudEmulatorCookie} cookie
-   * @returns {Promise<void>}
    */
   async postAllocate(cookie) {
-    const { instance } = cookie;
-    const { isNew } = this._launchInfo[instance.uuid];
-    const readyInstance = cookie.instance = await this._instanceLauncher.launch(instance, isNew);
-
-    const { adbName } = readyInstance;
-    await Timer.run(20000, 'waiting for device to respond', async () => {
-      await this._adb.disableAndroidAnimations(adbName);
-      await this._adb.setWiFiToggle(adbName, true);
-      await this._adb.apiLevel(adbName);
-    });
+    const instance = await this._instanceLauncher.connect(cookie.instance);
+    this._genyRegistry.updateInstance(instance);
+
+    if (this._genyRegistry.pollNewInstance(instance.uuid)) {
+      const { adbName } = instance;
+
+      await Timer.run(20000, 'waiting for device to respond', async () => {
+        await this._adb.disableAndroidAnimations(adbName);
+        await this._adb.setWiFiToggle(adbName, true);
+        await this._adb.apiLevel(adbName);
+      });
+    }
+
+    return {
+      ...cookie,
+      adbName: instance.adbName,
+    };
   }
 
   /**
-   * @param cookie { GenycloudEmulatorCookie }
-   * @param options { DeallocOptions }
+   * @param cookie {Omit<GenycloudEmulatorCookie, 'instance'>}
+   * @param options {Partial<import('../../AllocationDriverBase').DeallocOptions>}
    * @return {Promise<void>}
    */
   async free(cookie, options = {}) {
-    const { instance } = cookie;
-
-    await this._instanceAllocationHelper.deallocateDevice(instance.uuid);
-
+    // Known issue: cookie won't have a proper 'instance' field due to (de)serialization
     if (options.shutdown) {
-      await this._instanceLauncher.shutdown(instance);
+      this._genyRegistry.removeInstance(cookie.id);
+      await this._instanceLauncher.shutdown(cookie.id);
+    } else {
+      this._genyRegistry.markAsFree(cookie.id);
     }
   }
 
+  async cleanup() {
+    log.info(events.GENYCLOUD_TEARDOWN, 'Initiating Genymotion SaaS instances teardown...');
+
+    const killPromises = this._genyRegistry.getInstances().map((instance) => {
+      this._genyRegistry.markAsBusy(instance.uuid);
+      const onSuccess = () => this._genyRegistry.removeInstance(instance.uuid);
+      const onError = (error) => ({ ...instance, error });
+      return this._instanceLauncher.shutdown(instance.uuid).then(onSuccess, onError);
+    });
+
+    const deletionLeaks = (await Promise.all(killPromises)).filter(Boolean);
+    this._reportGlobalCleanupSummary(deletionLeaks);
+  }
+
+  emergencyCleanup() {
+    const instances = this._genyRegistry.getInstances();
+    this._reportGlobalCleanupSummary(instances);
+  }
+
   _assertRecipe(deviceQuery, recipe) {
     if (!recipe) {
       throw new DetoxRuntimeError({
@@ -76,6 +130,24 @@ class GenyAllocDriver extends AllocationDriverBase {
       });
     }
   }
+
+  _reportGlobalCleanupSummary(deletionLeaks) {
+    if (deletionLeaks.length) {
+      log.warn(events.GENYCLOUD_TEARDOWN, 'WARNING! Detected a Genymotion SaaS instance leakage, for the following instances:');
+
+      deletionLeaks.forEach(({ uuid, name, error }) => {
+        log.warn(events.GENYCLOUD_TEARDOWN, [
+          `Instance ${name} (${uuid})${error ? `: ${error}` : ''}`,
+          `    Kill it by visiting https://cloud.geny.io/instance/${uuid}, or by running:`,
+          `    gmsaas instances stop ${uuid}`,
+        ].join('\n'));
+      });
+
+      log.info(events.GENYCLOUD_TEARDOWN, 'Instances teardown completed with warnings');
+    } else {
+      log.info(events.GENYCLOUD_TEARDOWN, 'Instances teardown completed successfully');
+    }
+  }
 }
 
 module.exports = GenyAllocDriver;