detox 20.41.2 → 20.42.0

package/Detox-android/com/wix/detox/20.42.0/detox-20.42.0-sources.jar.md5

@@ -0,0 +1 @@
+1887d4991e0ed4ee1f60fe19496a9cfa

package/Detox-android/com/wix/detox/20.42.0/detox-20.42.0-sources.jar.sha1

@@ -0,0 +1 @@
+697906ce37fa13e262c3cfdaba6a6e23af05123d

package/Detox-android/com/wix/detox/20.42.0/detox-20.42.0-sources.jar.sha256

@@ -0,0 +1 @@
+81b7cec264869ffb4a51c3f49d0458ea42f02a8921afeeef9fba6d13f81f76c6

package/Detox-android/com/wix/detox/20.42.0/detox-20.42.0-sources.jar.sha512

@@ -0,0 +1 @@
+2345745b36a549ab7230b6cbc55cad2a2a469720a8622a2592669c3a25be55c8a9d0bb7b36123c68e91bc37c6df04f477849018c034e0dd956d1d5e9cb2a1cfb

package/Detox-android/com/wix/detox/20.42.0/detox-20.42.0.aar.md5

@@ -0,0 +1 @@
+69c3525aa2e433c05bee1f04c2724502

package/Detox-android/com/wix/detox/20.42.0/detox-20.42.0.aar.sha1

@@ -0,0 +1 @@
+5dac9bbd10339143f33f66269d560c940dabde5a

package/Detox-android/com/wix/detox/20.42.0/detox-20.42.0.aar.sha256

@@ -0,0 +1 @@
+04cb33cabcf007a0767a85ea4b9322efe008d9ffb2e4a5636f2eb6513fcc81d3

package/Detox-android/com/wix/detox/20.42.0/detox-20.42.0.aar.sha512

@@ -0,0 +1 @@
+aec098beccb4827b287051cfd924ba72a4b8ad6a5d3cf3c5f645dea50ba704f683a2dbe5e724a94801189aded1fe494a69cef0b31f9128dde89ee1ec2fc92e2d

package/Detox-android/com/wix/detox/{20.41.2/detox-20.41.2.pom → 20.42.0/detox-20.42.0.pom}

@@ -3,7 +3,7 @@
   <modelVersion>4.0.0</modelVersion>
   <groupId>com.wix</groupId>
   <artifactId>detox</artifactId>
-  <version>20.41.2</version>
+  <version>20.42.0</version>
   <packaging>aar</packaging>
   <name>Detox</name>
   <description>Gray box end-to-end testing and automation library for mobile apps</description>

package/Detox-android/com/wix/detox/20.42.0/detox-20.42.0.pom.md5

@@ -0,0 +1 @@
+c194caa27e6cabf5bc5bbede5c1e22ad

package/Detox-android/com/wix/detox/20.42.0/detox-20.42.0.pom.sha1

@@ -0,0 +1 @@
+d844bb306d465880c159bb56238879e2395cee9a

package/Detox-android/com/wix/detox/20.42.0/detox-20.42.0.pom.sha256

@@ -0,0 +1 @@
+6989731d5223c5a9f236e3911eaef2e85fbca229eb68bfbec44e31b3529ae70d

package/Detox-android/com/wix/detox/20.42.0/detox-20.42.0.pom.sha512

@@ -0,0 +1 @@
+13500f06af3b22637f0469dbce8b92b7da859ec3b08a28b8874be4ee1116599b97533cc7307a23beebe6c0508e57038ba2f6f195d69a09a994a599071bdce886

package/Detox-android/com/wix/detox/maven-metadata.xml

@@ -3,11 +3,11 @@
   <groupId>com.wix</groupId>
   <artifactId>detox</artifactId>
   <versioning>
-    <latest>20.41.2</latest>
-    <release>20.41.2</release>
+    <latest>20.42.0</latest>
+    <release>20.42.0</release>
     <versions>
-      <version>20.41.2</version>
+      <version>20.42.0</version>
     </versions>
-    <lastUpdated>20250916084648</lastUpdated>
+    <lastUpdated>20250925083025</lastUpdated>
   </versioning>
 </metadata>

package/Detox-android/com/wix/detox/maven-metadata.xml.md5

@@ -1 +1 @@
-78b2664291287ff2e98abc7833e1ff32
+cffd00ec1fa7d24dfa670f1f73cb2157

package/Detox-android/com/wix/detox/maven-metadata.xml.sha1

@@ -1 +1 @@
-3815f5ec320d3eb9cf95c90163e24c91f5120f41
+2f1f1e00242921f53643aeea67e863765c97bdef

package/Detox-android/com/wix/detox/maven-metadata.xml.sha256

@@ -1 +1 @@
-0ba98253bc44988f584d1c5dc53ef6da8485af9b8a1b208494bca124883669cd
+be3543d79c53d124eb70e536793549e36b7f2a5c196b524f55d39cdb322a3216

package/Detox-android/com/wix/detox/maven-metadata.xml.sha512

@@ -1 +1 @@
-6b8f60519bdf9dd63e87f1493dd74c0489d23bec33784921069c0ead127ba66f546d1cc0ed2fa75c818f7f2f28b2a464242e20879ed12f130fdc3de42d442cc5
+003eb81934b9bf5c98fc53dfa0d8871d436a7ef88fd0d430206672a38c898e47c4535ca1a2b621a65163b4c672fbbf65daba9ed9dbc0ee17461a64c674d63cd6

package/android/detox/src/full/java/com/wix/detox/espresso/hierarchy/ViewHierarchyGenerator.kt

@@ -1,10 +1,12 @@
 package com.wix.detox.espresso.hierarchy
 
+import android.util.DisplayMetrics
 import android.util.Xml
 import android.view.View
 import android.view.ViewGroup
 import android.webkit.WebView
 import android.widget.TextView
+import com.wix.detox.espresso.DeviceDisplay
 import com.wix.detox.reactnative.ui.getAccessibilityLabel
 import kotlinx.coroutines.Dispatchers
 import kotlinx.coroutines.runBlocking
@@ -63,6 +65,7 @@ object ViewHierarchyGenerator {
                 startDocument(Xml.Encoding.UTF_8.name, true)
                 setFeature("http://xmlpull.org/v1/doc/features.html#indent-output", true)
                 startTag("", "ViewHierarchy")
+                attribute("", "density", DeviceDisplay.getDensity().toString())
             }
 
             rootViews?.forEach { rootView ->

package/android/detox/src/full/java/com/wix/detox/reactnative/idlingresources/DetoxIdlingResource.kt

@@ -19,7 +19,6 @@ abstract class DetoxIdlingResource : DescriptiveIdlingResource {
         paused.set(false)
     }
 
-
     override fun registerIdleTransitionCallback(callback: IdlingResource.ResourceCallback?) {
         this.callback = callback
     }
@@ -37,7 +36,6 @@ abstract class DetoxIdlingResource : DescriptiveIdlingResource {
 
     protected abstract fun checkIdle(): Boolean
 
-
     fun notifyIdle() {
         callback?.onTransitionToIdle()
     }

package/android/detox/src/full/java/com/wix/detox/reactnative/idlingresources/ReactNativeIdlingResources.kt

@@ -16,7 +16,6 @@ import com.wix.detox.reactnative.idlingresources.network.NetworkIdlingResource
 import kotlinx.coroutines.runBlocking
 import org.joor.Reflect
 
-
 private const val LOG_TAG = "DetoxRNIdleRes"
 
 class ReactNativeIdlingResources(

package/android/detox/src/full/java/com/wix/detox/reactnative/idlingresources/StabilizedIdlingResource.kt

@@ -0,0 +1,74 @@
+package com.wix.detox.reactnative.idlingresources
+
+import androidx.test.espresso.IdlingResource.ResourceCallback
+/**
+ * A wrapper for idling resources that exhibit "flapping" behavior.
+ * This wrapper artificially stabilizes them by mindfully extending their "busy" state periods.
+ *
+ * #### What does flapping mean?
+ *
+ * Some idling resources have extremely short busy periods. While this shouldn't theoretically be an issue,
+ * in real-world scenarios (e.g., a React Native environment), the number of idling resources can accumulate.
+ * Unfortunately, the process of checking if all resources are idle (idle interrogation)
+ * isn't atomic. With many resources involved, this process might miss those brief busy periods
+ * of resources that "flap" (quickly switch between busy and idle) during the interrogation.
+ *
+ * #### How does this wrapper fix flapping?
+ *
+ * This wrapper requires the wrapped resource to report itself as "idle" multiple times consecutively
+ * before the wrapper itself is considered idle. This dramatically reduces the likelihood of it's busy phase being
+ * missed by the idle interrogation process.
+ */
+class StabilizedIdlingResource(
+    private val idlingResource: DetoxIdlingResource,
+    private val size: Int): DetoxIdlingResource(), ResourceCallback {
+
+    private val name = "${idlingResource.name} (stable@$size)"
+    private var idleCounter = 0
+
+    init {
+        if (size <= 1) {
+            throw IllegalArgumentException("Size must be > 1 in order for the usage of this class to make sense")
+        }
+        idlingResource.registerIdleTransitionCallback(this)
+    }
+
+    /**
+     * Implemented according to these 3 guiding principles:
+     * 1. As long as the actual resource is busy - we consider ourselves busy too.
+     * 2. Once actual resource is idle enough times in a row - we consider ourselves "idle", in a *sticky* way
+     *   (until it returns "busy" in an interrogation).
+     * 3. Espresso requires that just before we officially transition ourselves -- idle -> busy, we actively notify it
+     *   via the callback.
+     */
+    @Synchronized
+    override fun checkIdle(): Boolean {
+        if (!idlingResource.isIdleNow) {
+            idleCounter = 0
+            return false
+        }
+
+        if (idleCounter < size) {
+            idleCounter++
+
+            if (idleCounter == size) {
+                notifyIdle()
+            }
+        }
+        return (idleCounter == size)
+    }
+
+    /**
+     * Resets the counter to 0, assuming that Espresso will re-query this (among all other) resources
+     * immediately after this "I'm idle" notification.
+     */
+    @Synchronized
+    override fun onTransitionToIdle() {
+        idleCounter = 0
+        notifyIdle()
+    }
+
+    override fun getName(): String = name
+    override fun getDebugName(): String = idlingResource.getDebugName()
+    override fun getBusyHint(): Map<String, Any>? = idlingResource.getBusyHint()
+}

package/android/detox/src/full/java/com/wix/detox/reactnative/idlingresources/factory/FabricDetoxIdlingResourceFactoryStrategy.kt

@@ -1,9 +1,9 @@
 package com.wix.detox.reactnative.idlingresources.factory
 
 import com.facebook.react.ReactApplication
-import com.wix.detox.reactnative.getCurrentReactContext
 import com.wix.detox.reactnative.getCurrentReactContextSafe
 import com.wix.detox.reactnative.idlingresources.DetoxIdlingResource
+import com.wix.detox.reactnative.idlingresources.StabilizedIdlingResource
 import com.wix.detox.reactnative.idlingresources.animations.AnimatedModuleIdlingResource
 import com.wix.detox.reactnative.idlingresources.network.NetworkIdlingResource
 import com.wix.detox.reactnative.idlingresources.storage.AsyncStorageIdlingResource
@@ -23,7 +23,7 @@ class FabricDetoxIdlingResourceFactoryStrategy(private val reactApplication: Rea
                 IdlingResourcesName.Animations to AnimatedModuleIdlingResource(reactContext),
                 IdlingResourcesName.Timers to FabricTimersIdlingResource(reactContext),
                 IdlingResourcesName.Network to NetworkIdlingResource(reactContext),
-                IdlingResourcesName.AsyncStorage to AsyncStorageIdlingResource(reactContext)
+                IdlingResourcesName.AsyncStorage to StabilizedIdlingResource(AsyncStorageIdlingResource(reactContext), 2)
             )
 
             return@withContext result

package/android/detox/src/full/java/com/wix/detox/reactnative/idlingresources/storage/AsyncStorageIdlingResource.kt

@@ -1,6 +1,5 @@
 package com.wix.detox.reactnative.idlingresources.storage
 
-import android.util.Log
 import androidx.test.espresso.IdlingResource
 import com.facebook.react.bridge.NativeModule
 import com.facebook.react.bridge.ReactContext
@@ -9,36 +8,17 @@ import com.wix.detox.reactnative.idlingresources.DetoxIdlingResource
 import org.joor.Reflect
 import java.util.concurrent.Executor
 
-private const val LOG_TAG = "AsyncStorageIR"
-
 private typealias SExecutorReflectedGenFnType = (executor: Executor) -> SerialExecutorReflected
 
 private val defaultSExecutorReflectedGenFn: SExecutorReflectedGenFnType =
     { executor: Executor -> SerialExecutorReflected(executor) }
 
-private class ModuleReflected(module: NativeModule, sexecutorReflectedGen: SExecutorReflectedGenFnType) {
-    private val executorReflected: SerialExecutorReflected
-
-    init {
-        val reflected = Reflect.on(module)
-        val executor: Executor = reflected.field("executor").get()
-        executorReflected = sexecutorReflectedGen(executor)
-    }
-
-    val sexecutor: SerialExecutorReflected
-        get() = executorReflected
-}
-
-class AsyncStorageIdlingResource
-@JvmOverloads constructor(
+class AsyncStorageIdlingResource @JvmOverloads constructor(
     private val reactContext: ReactContext,
     private val sexecutorReflectedGenFn: SExecutorReflectedGenFnType = defaultSExecutorReflectedGenFn,
-    private val rnHelpers: RNHelpers = RNHelpers()
+    private val rnHelpers: RNHelpers = RNHelpers(),
 ) : DetoxIdlingResource() {
 
-    val logTag: String
-        get() = LOG_TAG
-
     private val moduleReflected: ModuleReflected? = null
     private var idleCheckTask: Runnable? = null
     private val idleCheckTaskImpl = Runnable {
@@ -86,13 +66,14 @@ class AsyncStorageIdlingResource
 
     override fun registerIdleTransitionCallback(callback: IdlingResource.ResourceCallback?) {
         super.registerIdleTransitionCallback(callback)
+
+        // TODO Don't do?
         enqueueIdleCheckTask()
     }
 
     override fun checkIdle(): Boolean =
         checkIdleInternal().also { idle ->
             if (!idle) {
-                Log.d(logTag, "Async-storage is busy!")
                 enqueueIdleCheckTask()
             }
         }
@@ -117,3 +98,16 @@ class AsyncStorageIdlingResource
         idleCheckTask = null
     }
 }
+
+private class ModuleReflected(module: NativeModule, sexecutorReflectedGen: SExecutorReflectedGenFnType) {
+    private val executorReflected: SerialExecutorReflected
+
+    init {
+        val reflected = Reflect.on(module)
+        val executor: Executor = reflected.field("executor").get()
+        executorReflected = sexecutorReflectedGen(executor)
+    }
+
+    val sexecutor: SerialExecutorReflected
+        get() = executorReflected
+}

package/detox.d.ts

@@ -773,6 +773,28 @@ declare global {
              */
             reloadReactNative(): Promise<void>;
 
+            /**
+             * Resets the app state by clearing app data and restoring it to a clean state.
+             *
+             * On Android, this command clears the app's data using the `pm clear` command,
+             * effectively resetting the app to its initial installed state without uninstalling it.
+             *
+             * On iOS, Detox uses a fallback mechanism - it backs up, deletes and installs the app from cache.
+             * This process ensures the app is returned to a clean state.
+             *
+             * @param bundleIds Optional bundle IDs to reset. If none provided, resets the currently selected app.
+             * @example
+             * // Reset current app state
+             * await device.resetAppState();
+             * @example
+             * // Reset specific app state
+             * await device.resetAppState('com.example.app');
+             * @example
+             * // Reset multiple apps
+             * await device.resetAppState('com.app1', 'com.app2');
+             */
+            resetAppState(...bundleIds: string[]): Promise<void>;
+
             /**
              * By default, installApp() with no params will install the app file defined in the current configuration.
              * To install another app, specify its path
@@ -2014,6 +2036,13 @@ declare global {
              * Launch with user activity
              */
             userActivity?: any;
+            /**
+             * Similar to {@link Detox.DeviceLaunchAppConfig.delete | { delete: true }}, but instead of uninstalling and installing the app,
+             * it runs {@link Detox.Device.resetAppState | device.resetAppState()} instead.
+             * @example
+             * await device.launchApp({resetAppState: true});
+             */
+            resetAppState?: boolean;
             /**
              * Launch into a fresh installation
              * A flag that enables relaunching into a fresh installation of the app (it will uninstall and install the binary again), default is false.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "detox",
   "description": "E2E tests and automation for mobile",
-  "version": "20.41.2",
+  "version": "20.42.0",
   "bin": {
     "detox": "local-cli/cli.js"
   },
@@ -68,7 +68,7 @@
     "wtfnode": "^0.9.1"
   },
   "dependencies": {
-    "@wix-pilot/core": "^3.4.1",
+    "@wix-pilot/core": "^3.4.2",
     "@wix-pilot/detox": "^1.0.13",
     "ajv": "^8.6.3",
     "bunyan": "^1.8.12",
@@ -120,5 +120,5 @@
   "browserslist": [
     "node 14"
   ],
-  "gitHead": "69e708aaa8c8dac999c8d442751865df66723cb9"
+  "gitHead": "e86f949767d1fb178f97fa31ec9cb6e2226e86fa"
 }

package/runners/jest/reporter.js

@@ -11,8 +11,8 @@ const {
 class DetoxReporter extends DetoxReporterDispatcher {
   constructor(globalConfig) {
     super(globalConfig, {
-      DetoxSummaryReporter,
       DetoxVerboseReporter,
+      DetoxSummaryReporter,
       DetoxIPCReporter,
     });
   }

package/src/devices/allocation/drivers/ios/SimulatorAllocDriver.js

@@ -8,6 +8,7 @@ const _ = require('lodash');
 
 const { DetoxRuntimeError } = require('../../../../errors');
 const log = require('../../../../utils/logger').child({ cat: 'device,device-allocation' });
+const SimulatorAppCache = require('../../../common/drivers/ios/tools/SimulatorAppCache');
 
 const SimulatorQuery = require('./SimulatorQuery');
 
@@ -24,6 +25,7 @@ class SimulatorAllocDriver {
   constructor({ detoxConfig, deviceRegistry, applesimutils }) {
     this._deviceRegistry = deviceRegistry;
     this._applesimutils = applesimutils;
+    this._appCache = new SimulatorAppCache({ applesimutils });
     this._launchInfo = {};
     this._shouldShutdown = detoxConfig.behavior.cleanup.shutdownDevice;
   }
@@ -58,7 +60,9 @@ class SimulatorAllocDriver {
   async postAllocate(deviceCookie) {
     const { udid } = deviceCookie;
     const { deviceConfig } = this._launchInfo[udid];
+
     await this._applesimutils.boot(udid, deviceConfig.bootArgs, deviceConfig.headless);
+    await this._appCache.cleanupOnce(udid);
 
     return {
       id: udid,
@@ -86,12 +90,15 @@ class SimulatorAllocDriver {
   }
 
   async cleanup() {
+    const sessionDevices = await this._deviceRegistry.readSessionDevices();
+    const deviceIds = sessionDevices.getIds();
+
     if (this._shouldShutdown) {
-      const sessionDevices = await this._deviceRegistry.readSessionDevices();
-      const shutdownPromises = sessionDevices.getIds().map((udid) => this._doShutdown(udid));
+      const shutdownPromises = deviceIds.map((udid) => this._doShutdown(udid));
       await Promise.all(shutdownPromises);
     }
 
+    await Promise.all(deviceIds.map((udid) => this._appCache.cleanup(udid)));
     await this._deviceRegistry.unregisterSessionDevices();
   }
 
@@ -172,7 +179,7 @@ class SimulatorAllocDriver {
       deviceQuery,
       {
         trying: `Searching for device ${deviceQuery} ...`,
-        fields: ['udid', 'os', 'identifier'],
+        fields: ['udid', 'name', 'deviceType', 'os', 'identifier'],
       }
     );
 

package/src/devices/common/drivers/android/exec/ADB.js

@@ -148,6 +148,18 @@ class ADB {
     await this.shell(deviceId, `am force-stop ${appId}`);
   }
 
+  async clearAppData(deviceId, packageId) {
+    try {
+      return await this.shell(deviceId, `pm clear ${packageId}`);
+    } catch (reason) {
+      throw new DetoxRuntimeError({
+        message: `Failed to clear ${packageId} app data on ${deviceId}`,
+        hint: `Please verify that the package is installed on the device:\nadb -s ${deviceId} shell pm list packages ${packageId}`,
+        debugInfo: reason,
+      });
+    }
+  }
+
   async setLocation(deviceId, lat, lon) {
     // NOTE: QEMU for Android for the telnet part relies on C stdlib
     // function `strtod` which is locale-sensitive, meaning that depending

package/src/devices/common/drivers/ios/tools/SimulatorAppCache.js

@@ -0,0 +1,148 @@
+const path = require('path');
+
+const { DetoxInternalError, DetoxRuntimeError } = require('../../../../../errors');
+const { getDetoxAppsCachePath } = require('../../../../../utils/environment');
+const fse = require('../../../../../utils/fsext');
+const log = require('../../../../../utils/logger').child({ cat: 'device,app-cache' });
+
+class SimulatorAppCache {
+  constructor({ applesimutils, rootDir = getDetoxAppsCachePath() }) {
+    this.applesimutils = applesimutils;
+    this.rootDir = rootDir;
+    this.cleanDeviceIds = new Set();
+  }
+
+  /**
+   * Add an app to cache from a binary path
+   * @param {string} deviceId - The device identifier
+   * @param {string} bundleId - The app's bundle identifier
+   * @param {string} binaryPath - Path to the app binary
+   */
+  async add(deviceId, bundleId, binaryPath) {
+    log.trace({ deviceId }, `Caching app (${bundleId}) from binary path: ${binaryPath}`);
+
+    const cacheAppPath = this._getAppCachePath(deviceId, bundleId);
+    await fse.ensureDir(path.dirname(cacheAppPath));
+    await fse.remove(cacheAppPath);
+    await fse.copy(binaryPath, cacheAppPath);
+  }
+
+  /**
+   * Back up an app to cache, if it is not already cached
+   * @param {string} deviceId - The device identifier
+   * @param {string} bundleId - The app's bundle identifier
+   */
+  async backup(deviceId, bundleId) {
+    const appContainerPath = await this.applesimutils.getAppContainer(deviceId, bundleId).catch((reason) => {
+      throw new DetoxRuntimeError({
+        message: `App with bundle ID '${bundleId}' is not installed on this device (${deviceId}). Please install the app first before attempting to reset its state.`,
+        hint: `To check apps installed on the device, use: xcrun simctl listapps ${deviceId}`,
+        debugInfo: reason,
+      });
+    });
+
+    if (!await this.exists(deviceId, bundleId)) {
+      await this.add(deviceId, bundleId, appContainerPath);
+    }
+  }
+
+  /**
+   * Restore an app from cache
+   * @param {string} deviceId - The device identifier
+   * @param {string} bundleId - The app's bundle identifier
+   * @returns {Promise<void>}
+   */
+  async restore(deviceId, bundleId) {
+    log.trace(`Restoring app (${bundleId}) from cache to device (${deviceId})`);
+
+    const cacheAppPath = this._getAppCachePath(deviceId, bundleId);
+
+    if (!await fse.exists(cacheAppPath)) {
+      throw new DetoxInternalError(`No backup found for bundle ID '${bundleId}' on device ${deviceId}. This should not happen unless you're calling SimulatorAppCache#restore() directly.`);
+    }
+
+    await this.applesimutils.install(deviceId, cacheAppPath);
+  }
+
+  /**
+   * Check if an app is cached
+   * @param {string} deviceId - The device identifier
+   * @param {string} bundleId - The app's bundle identifier
+   * @returns {Promise<boolean>} True if the app is cached
+   */
+  async exists(deviceId, bundleId) {
+    const cacheAppPath = this._getAppCachePath(deviceId, bundleId);
+    return await fse.exists(cacheAppPath);
+  }
+
+  /**
+   * Remove cache for a specific app
+   * @param {string} deviceId - The device identifier
+   * @param {string} bundleId - The app's bundle identifier
+   * @returns {Promise<void>}
+   */
+  async remove(deviceId, bundleId) {
+    try {
+      const cacheAppPath = this._getAppCachePath(deviceId, bundleId);
+      if (await fse.remove(cacheAppPath)) {
+        log.trace({ path: cacheAppPath }, `Removed cached app (${bundleId}) for device (${deviceId})`);
+      }
+    } catch (err) {
+      log.warn({ err }, `Failed to remove app cache for ${bundleId} on device ${deviceId}`);
+    }
+  }
+
+  /**
+   * Clean up cache for a device
+   * @param {string} deviceId - The device identifier
+   * @returns {Promise<void>}
+   */
+  async cleanup(deviceId) {
+    try {
+      const deviceCachePath = this._getDeviceCachePath(deviceId);
+      if (await fse.remove(deviceCachePath)) {
+        log.trace({ path: deviceCachePath }, `Cleaned up the app cache for device (${deviceId})`);
+      }
+    } catch (err) {
+      log.warn({ err }, `Failed to cleanup app cache for device ${deviceId}`);
+    }
+
+    this.cleanDeviceIds.add(deviceId);
+  }
+
+  /**
+   * Clean up cache for a device only once per instance.
+   * If the device has already been cleaned, this is a no-op.
+   *
+   * @param {string} deviceId - The device identifier
+   * @returns {Promise<void>}
+   */
+  async cleanupOnce(deviceId) {
+    if (!this.cleanDeviceIds.has(deviceId)) {
+      await this.cleanup(deviceId);
+    }
+  }
+
+  /**
+   * Get the cache path for a specific app on a device
+   * @param {string} deviceId - The device identifier
+   * @param {string} bundleId - The app's bundle identifier
+   * @returns {string} The full path to the cached app
+   * @private
+   */
+  _getAppCachePath(deviceId, bundleId) {
+    return path.join(this._getDeviceCachePath(deviceId), `${bundleId}.app`);
+  }
+
+  /**
+   * Get the device cache directory path
+   * @param {string} deviceId - The device identifier
+   * @returns {string} The device cache directory path
+   * @private
+   */
+  _getDeviceCachePath(deviceId) {
+    return path.join(this.rootDir, deviceId);
+  }
+}
+
+module.exports = SimulatorAppCache;

package/src/devices/runtime/RuntimeDevice.js

@@ -31,6 +31,7 @@ class RuntimeDevice {
       'pressBack',
       'relaunchApp',
       'reloadReactNative',
+      'resetAppState',
       'resetContentAndSettings',
       'resetStatusBar',
       'reverseTcpPort',
@@ -119,7 +120,10 @@ class RuntimeDevice {
       ? params.newInstance
       : this._processes[bundleId] == null;
 
-    if (params.delete) {
+    if (params.resetAppState) {
+      await this.terminateApp(bundleId);
+      await this.resetAppState(bundleId);
+    } else if (params.delete) {
       await this.terminateApp(bundleId);
       await this.uninstallApp();
       await this.installApp();
@@ -261,6 +265,11 @@ class RuntimeDevice {
     await this.deviceDriver.uninstallApp(_bundleId);
   }
 
+  async resetAppState(...bundleIds) {
+    const _bundleIds = bundleIds.length > 0 ? bundleIds : [this._bundleId];
+    await this.deviceDriver.resetAppState(..._bundleIds);
+  }
+
   async installUtilBinaries() {
     const paths = this._deviceConfig.utilBinaryPaths;
     if (paths) {

package/src/devices/runtime/drivers/DeviceDriverBase.js

@@ -91,6 +91,10 @@ class DeviceDriverBase {
     return '';
   }
 
+  async resetAppState(..._bundleIds) {
+    return undefined;
+  }
+
   async uninstallApp() {
     return '';
   }

package/src/devices/runtime/drivers/android/AndroidDriver.js

@@ -84,6 +84,12 @@ class AndroidDriver extends DeviceDriverBase {
     await this.appUninstallHelper.uninstall(this.adbName, bundleId);
   }
 
+  async resetAppState(...bundleIds) {
+    for (const bundleId of bundleIds) {
+      await this.adb.clearAppData(this.adbName, bundleId);
+    }
+  }
+
   async installUtilBinaries(paths) {
     for (const path of paths) {
       const packageId = await this.getBundleIdFromBinary(path);

package/src/devices/runtime/drivers/ios/AppStateResetFallback.js

@@ -0,0 +1,69 @@
+const SimulatorAppCache = require('../../../common/drivers/ios/tools/SimulatorAppCache');
+
+/**
+ * AppStateResetFallback provides app state reset functionality for iOS simulators.
+ *
+ * This class serves as a fallback implementation because iOS does not provide a native
+ * way to reset an app's state (unlike Android's `pm clear` command). To achieve app
+ * state reset on iOS, this class implements a backup-uninstall-reinstall strategy:
+ *
+ * 1. Backs up the app installation to cache
+ * 2. Uninstalls the current app instance
+ * 3. Restores the app installation from cache
+ *
+ * This approach ensures the app is returned to a clean state without requiring
+ * a full app reinstallation from the original bundle, making it more friendly
+ * to local development flows.
+ *
+ * @class AppStateResetFallback
+ */
+class AppStateResetFallback {
+  /**
+   * Creates an instance of AppStateResetFallback.
+   * @param {Object} config
+   * @param {import('../../../common/drivers/ios/tools/AppleSimUtils')} config.applesimutils - AppleSimUtils instance
+   * @param {SimulatorAppCache} [config.appCache] - Optional SimulatorAppCache instance (for testing/mocking)
+   */
+  constructor({ applesimutils, appCache }) {
+    this.applesimutils = applesimutils;
+    this.appCache = appCache ?? new SimulatorAppCache({ applesimutils });
+  }
+
+  /**
+   * Resets the app state for multiple apps by backing them up and restoring them.
+   * This effectively clears the app state while preserving the app installation.
+   *
+   * @param {string} udid - The device identifier
+   * @param {string[]} bundleIds - Array of app bundle identifiers to reset
+   * @returns {Promise<void>}
+   */
+  async resetAppState(udid, bundleIds) {
+    for (const bundleId of bundleIds) {
+      await this.appCache.backup(udid, bundleId);
+      await this.applesimutils.uninstall(udid, bundleId);
+    }
+
+    for (const bundleId of bundleIds) {
+      await this.appCache.restore(udid, bundleId);
+    }
+  }
+
+  /**
+   * Ensures removal of cached app(s) after a potentially
+   * destructive action (such as install or uninstall),
+   * so {@link resetAppState} can't use a stale backup from cache.
+   *
+   * @param {string} udid - The device identifier
+   * @param {string} [bundleId] - Optional bundle identifier for specific app invalidation
+   * @returns {Promise<void>}
+   */
+  async invalidate(udid, bundleId) {
+    if (bundleId) {
+      await this.appCache.remove(udid, bundleId);
+    } else {
+      await this.appCache.cleanup(udid);
+    }
+  }
+}
+
+module.exports = AppStateResetFallback;

package/src/devices/runtime/drivers/ios/SimulatorDriver.js

@@ -15,6 +15,7 @@ const log = require('../../../../utils/logger').child({ cat: 'device' });
 const pressAnyKey = require('../../../../utils/pressAnyKey');
 const traceInvocationCall = require('../../../../utils/traceInvocationCall').bind(null, log);
 
+const AppStateResetFallback = require('./AppStateResetFallback');
 const IosDriver = require('./IosDriver');
 
 /**
@@ -37,12 +38,15 @@ class SimulatorDriver extends IosDriver {
   constructor(deps, { udid, type, bootArgs, headless }) {
     super(deps);
 
+    this.getBundleIdFromBinary = _.memoize(this.getBundleIdFromBinary.bind(this));
+
     this.udid = udid;
     this._type = type;
     this._bootArgs = bootArgs;
     this._headless = headless;
     this._deviceName = `${udid} (${this._type})`;
     this._applesimutils = deps.applesimutils;
+    this._appStateResetFallback = new AppStateResetFallback({ applesimutils: this._applesimutils });
   }
 
   withAction(xcuitestRunner, action, traceDescription, ...params) {
@@ -80,13 +84,24 @@ class SimulatorDriver extends IosDriver {
   }
 
   async installApp(binaryPath) {
-    await this._applesimutils.install(this.udid, getAbsoluteBinaryPath(binaryPath));
+    const absoluteBinaryPath = getAbsoluteBinaryPath(binaryPath);
+    await this._applesimutils.install(this.udid, absoluteBinaryPath);
+
+    const bundleId = await this.getBundleIdFromBinary(binaryPath);
+    await this._appStateResetFallback.invalidate(this.udid, bundleId);
   }
 
   async uninstallApp(bundleId) {
     const { udid } = this;
     await this.emitter.emit('beforeUninstallApp', { deviceId: udid, bundleId });
     await this._applesimutils.uninstall(udid, bundleId);
+    await this._appStateResetFallback.invalidate(udid, bundleId);
+  }
+
+  async resetAppState(...bundleIds) {
+    const { udid } = this;
+    const _bundleIds = bundleIds.length > 0 ? bundleIds : [this._bundleId];
+    await this._appStateResetFallback.resetAppState(udid, _bundleIds);
   }
 
   async launchApp(bundleId, launchArgs, languageAndLocale) {
@@ -186,6 +201,7 @@ class SimulatorDriver extends IosDriver {
     await this._applesimutils.shutdown(this.udid);
     await this.emitter.emit('shutdownDevice', { deviceId: this.udid });
     await this._applesimutils.resetContentAndSettings(this.udid);
+    await this._appStateResetFallback.invalidate(this.udid);
     await this._applesimutils.boot(this.udid, this._bootArgs, this._headless);
     await this.emitter.emit('bootDevice', { deviceId: this.udid });
   }

package/src/utils/constructSafeFilename.js

@@ -41,7 +41,8 @@ function constructSafeFilename(prefix = '', trimmable = '', suffix = '') {
 
   const trimmed = trimmable.slice(-MAX_FILE_LENGTH + nonTrimmableLength);
   const unsafe = prefix + trimmed + suffix;
-  const sanitized = sanitize(unsafe, sanitizeOptions);
+  const sanitized = sanitize(unsafe, sanitizeOptions)
+    .replace(/\$/g, sanitizeOptions.replacement);
 
   return sanitized;
 }

package/src/utils/environment.js

@@ -20,6 +20,7 @@ function which(executable, path) {
 const DETOX_LIBRARY_ROOT_PATH = path.join(appdatapath.appDataPath(), 'Detox');
 const MISSING_SDK_ERROR = `$ANDROID_SDK_ROOT is not defined, set the path to the SDK installation directory into $ANDROID_SDK_ROOT,
 Go to https://developer.android.com/studio/command-line/variables.html for more details`;
+const DETOX_APPS_CACHE_PATH = path.join(DETOX_LIBRARY_ROOT_PATH, 'apps-cache');
 const DETOX_LOCK_FILE_PATH = path.join(DETOX_LIBRARY_ROOT_PATH, 'global-context.json');
 const DEVICE_REGISTRY_PATH = path.join(DETOX_LIBRARY_ROOT_PATH, 'device.registry.json');
 const LAST_FAILED_TESTS_PATH = path.join(DETOX_LIBRARY_ROOT_PATH, 'last-failed.txt');
@@ -217,6 +218,16 @@ function getDetoxLibraryRootPath() {
   return DETOX_LIBRARY_ROOT_PATH;
 }
 
+function getDetoxAppsCachePath(udid, bundleId) {
+  if (udid && bundleId) {
+    return path.join(DETOX_APPS_CACHE_PATH, udid, bundleId);
+  } else if (udid) {
+    return path.join(DETOX_APPS_CACHE_PATH, udid);
+  } else {
+    return DETOX_APPS_CACHE_PATH;
+  }
+}
+
 function getDetoxLockFilePath() {
   return DETOX_LOCK_FILE_PATH;
 }
@@ -249,6 +260,7 @@ module.exports = {
   getXCUITestRunnerPath,
   getAndroidSDKPath,
   getAndroidEmulatorPath,
+  getDetoxAppsCachePath,
   getDetoxLibraryRootPath,
   getDetoxLockFilePath,
   getDeviceRegistryPath,

package/src/utils/fsext.js

@@ -19,8 +19,21 @@ async function getDirectories (rootPath) {
   return dirs.sort();
 }
 
+async function remove(filePath) {
+  if (await fs.exists(filePath)) {
+    await fs.remove(filePath);
+    return true;
+  }
+
+  return false;
+}
+
 module.exports = {
+  copy: fs.copy,
+  ensureDir: fs.ensureDir,
+  exists: fs.exists,
   getDirectories,
   isDirEmptySync,
   readdirSync: fs.readdirSync,
+  remove,
 };

package/Detox-android/com/wix/detox/20.41.2/detox-20.41.2-sources.jar.md5

@@ -1 +0,0 @@
-78e6a14fb3535afbf9e26a44532bad26

package/Detox-android/com/wix/detox/20.41.2/detox-20.41.2-sources.jar.sha1

@@ -1 +0,0 @@
-6608ad7ef3136c6a6a96d8c0196c015266fad90b

package/Detox-android/com/wix/detox/20.41.2/detox-20.41.2-sources.jar.sha256

@@ -1 +0,0 @@
-8cad5bb8dcadcb1489d21e9eb02b4e404ba142611cac6c9e0b5b870eabd02644

package/Detox-android/com/wix/detox/20.41.2/detox-20.41.2-sources.jar.sha512

@@ -1 +0,0 @@
-420217e7885b9b62f1345d4a75fa684508898a054f188e60816f6cdbfc95bc8ca4af71d09f60d81246fb723f551b52b211765c59f9edc10394b508387f1293d1

package/Detox-android/com/wix/detox/20.41.2/detox-20.41.2.aar.md5

@@ -1 +0,0 @@
-92af4eb56025da6478dcf052cc974ed9

package/Detox-android/com/wix/detox/20.41.2/detox-20.41.2.aar.sha1

@@ -1 +0,0 @@
-caa2f11c005b65f021c582cf67539513db45db0c

package/Detox-android/com/wix/detox/20.41.2/detox-20.41.2.aar.sha256

@@ -1 +0,0 @@
-69db0de12353910d42ff6cfb919ff43ddfb3225f762463bc326f31741f20c118

package/Detox-android/com/wix/detox/20.41.2/detox-20.41.2.aar.sha512

@@ -1 +0,0 @@
-aa19d01f92ff6aa9724f8eba5d9b705e0d549105a08f11b643e5fcd530d292ee9be73a354a447d2d1377ed80ebe07cf7da405da06c6a382ea1127b69e105b543

package/Detox-android/com/wix/detox/20.41.2/detox-20.41.2.pom.md5

@@ -1 +0,0 @@
-03211aed18c8bbd28357bdbbc15b17ed

package/Detox-android/com/wix/detox/20.41.2/detox-20.41.2.pom.sha1

@@ -1 +0,0 @@
-3d506946f8dd584cd3f5f849f81ce8badba26ff1

package/Detox-android/com/wix/detox/20.41.2/detox-20.41.2.pom.sha256

@@ -1 +0,0 @@
-2b73ef91d19c21879c9f7562235484c19750e46011ba430b2255a50a6c23bc90

package/Detox-android/com/wix/detox/20.41.2/detox-20.41.2.pom.sha512

@@ -1 +0,0 @@
-3cf68662b57730aa809c02a55762284adaae491b7ff7b96781630e7e2829c530d956f099d12bd5a27d45a72d995befd5b127c4d966ddfbd322dcf43715316d3d