create-cmp-cli 0.11.0 → 0.12.0

package/template/composeApp/src/androidInstrumentedTest/kotlin/com/example/app/testing/NotificationAsserts.kt

@@ -0,0 +1,163 @@
+package __PACKAGE__.testing
+
+import android.app.NotificationManager
+import android.content.Context
+import android.os.Build
+import android.service.notification.StatusBarNotification
+import androidx.test.platform.app.InstrumentationRegistry
+import org.junit.Assert.assertTrue
+import org.junit.Assert.fail
+import org.junit.Assume.assumeTrue
+
+/**
+ * Notification assertions against the REAL NotificationManager — the shade as the OS sees
+ * it, not as the app hopes it is.
+ *
+ * Why this exists: "the notification posted" is an asynchronous OS-side fact. Posting is
+ * fire-and-forget, delivery is ranked/filtered/deferred, and none of it is observable from
+ * a JVM test. The recurring production failures this file targets are all of the shape
+ * "the code ran, the phone stayed dark": a channel created with the wrong importance, a
+ * full-screen intent silently dropped, a re-post under a changed channel id that Android
+ * discards without error.
+ *
+ * Constraints the code can't show:
+ *  - `activeNotifications` only returns notifications the OS ACCEPTED. On API 33+ a fresh
+ *    install has no POST_NOTIFICATIONS grant and everything is dropped before it reaches
+ *    the shade — take the grant in your test's @Before via
+ *    `uiAutomation.grantRuntimePermission(pkg, "android.permission.POST_NOTIFICATIONS")`
+ *    (see PlatformBehaviorSeamTest). A suite that forgets the grant reports the exact bug
+ *    it exists to catch, so [awaitNotification]'s failure message reminds you.
+ *  - Posting is asynchronous; every positive assertion here is a bounded poll, never a
+ *    single read. The negative check ([assertNoNotification]) polls the FULL window —
+ *    absence is only meaningful after the post would have landed.
+ *  - Channel behavior (sound, vibration, DND bypass) is partly OS/OEM-owned: importance is
+ *    app-controlled at creation, but `lockscreenVisibility`/`bypassDnd`/sound routing are
+ *    "modifiable by the system and the ranker" and read back as defaults regardless of
+ *    what you set. Assert what the app controls; leave the OEM half to the manual tier
+ *    (see docs/TESTING.md).
+ */
+object NotificationAsserts {
+
+    private val context: Context
+        get() = InstrumentationRegistry.getInstrumentation().targetContext
+
+    private val manager: NotificationManager
+        get() = context.getSystemService(Context.NOTIFICATION_SERVICE) as NotificationManager
+
+    private const val DEFAULT_TIMEOUT_MS = 10_000L
+    private const val POLL_MS = 100L
+
+    /**
+     * Waits (bounded poll, [timeoutMs]) for a posted notification matching [predicate] and
+     * returns it. Fails with the current shade contents — the diff you actually need.
+     */
+    fun awaitNotification(
+        timeoutMs: Long = DEFAULT_TIMEOUT_MS,
+        predicate: (StatusBarNotification) -> Boolean,
+    ): StatusBarNotification {
+        val deadline = System.currentTimeMillis() + timeoutMs
+        while (System.currentTimeMillis() < deadline) {
+            manager.activeNotifications.firstOrNull(predicate)?.let { return it }
+            Thread.sleep(POLL_MS)
+        }
+        fail(
+            "no matching notification posted within ${timeoutMs}ms. " +
+                "Shade holds: ${describeShade()}. " +
+                "If the shade is empty on API 33+, check the POST_NOTIFICATIONS grant first.",
+        )
+        error("unreachable")
+    }
+
+    /** [awaitNotification] by the (id, tag) pair the app posted under. */
+    fun awaitNotification(
+        id: Int,
+        tag: String? = null,
+        timeoutMs: Long = DEFAULT_TIMEOUT_MS,
+    ): StatusBarNotification =
+        awaitNotification(timeoutMs) { it.id == id && it.tag == tag }
+
+    /**
+     * Asserts NOTHING matching [predicate] is in the shade for the full [windowMs].
+     * Deliberately slow: a notification that appears 2s late is still a failure, so the
+     * whole window is watched — use this sparingly, for "the cancel actually cancelled".
+     */
+    fun assertNoNotification(
+        windowMs: Long = 3_000L,
+        predicate: (StatusBarNotification) -> Boolean,
+    ) {
+        val deadline = System.currentTimeMillis() + windowMs
+        while (System.currentTimeMillis() < deadline) {
+            val hit = manager.activeNotifications.firstOrNull(predicate)
+            if (hit != null) fail("unexpected notification in the shade: ${describe(hit)}")
+            Thread.sleep(POLL_MS)
+        }
+    }
+
+    /**
+     * Asserts the channel exists with AT LEAST [importanceFloor]. A floor, not equality:
+     * the user can raise a channel's importance and the app must keep working — what the
+     * app must guarantee is the minimum it created the channel with.
+     *
+     * The classic escaped bug: a heads-up channel created as IMPORTANCE_DEFAULT renders as
+     * a silent shade line — code identical, behavior invisible to every JVM tier.
+     *
+     * Channels exist from API 26; on older devices the test is skipped (assumption), never
+     * vacuously green.
+     */
+    fun assertChannelExists(
+        channelId: String,
+        importanceFloor: Int = NotificationManager.IMPORTANCE_DEFAULT,
+    ) {
+        assumeTrue(
+            "notification channels need API 26+ (device is ${Build.VERSION.SDK_INT})",
+            Build.VERSION.SDK_INT >= Build.VERSION_CODES.O,
+        )
+        val channel = manager.getNotificationChannel(channelId)
+            ?: fail(
+                "notification channel '$channelId' does not exist. Channels present: " +
+                    manager.notificationChannels.joinToString { it.id },
+            ).let { error("unreachable") }
+        assertTrue(
+            "channel '$channelId' importance is ${channel.importance}, below the required " +
+                "floor $importanceFloor — it will not behave (heads-up/sound) the way the " +
+                "feature assumes",
+            channel.importance >= importanceFloor,
+        )
+    }
+
+    /**
+     * Asserts the app is currently CAPABLE of a full-screen (lock-screen takeover)
+     * notification on [channelId]:
+     *  - the channel exists at IMPORTANCE_HIGH or above (below HIGH the OS won't launch
+     *    the full-screen intent, it just posts quietly), and
+     *  - on API 34+, `canUseFullScreenIntent()` — Android 14 turned USE_FULL_SCREEN_INTENT
+     *    into a revocable special access, so a manifest permission alone stopped being
+     *    proof. On 24..33 the manifest grant is install-time and not queryable, so only
+     *    the channel half is asserted there.
+     *
+     * This is capability, not delivery: whether a takeover actually renders over the lock
+     * screen on a locked, Doze-ing, OEM-skinned device belongs to the manual tier.
+     */
+    fun assertFullScreenIntentCapable(channelId: String) {
+        assertChannelExists(channelId, NotificationManager.IMPORTANCE_HIGH)
+        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.UPSIDE_DOWN_CAKE) {
+            assertTrue(
+                "canUseFullScreenIntent() is false — Android 14+ treats full-screen intents " +
+                    "as revocable special access; declare USE_FULL_SCREEN_INTENT in the " +
+                    "manifest and (for alarm/call apps outside the auto-grant) send the user " +
+                    "to ACTION_MANAGE_APP_USE_FULL_SCREEN_INTENT",
+                manager.canUseFullScreenIntent(),
+            )
+        }
+    }
+
+    private fun describeShade(): String {
+        val active = manager.activeNotifications
+        return if (active.isEmpty()) "(empty)" else active.joinToString { describe(it) }
+    }
+
+    private fun describe(sbn: StatusBarNotification): String =
+        "[id=${sbn.id} tag=${sbn.tag} channel=${
+            if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) sbn.notification.channelId else "n/a"
+        }]"
+}

package/template/composeApp/src/androidInstrumentedTest/kotlin/com/example/app/testing/PermissionControl.kt

@@ -0,0 +1,132 @@
+package __PACKAGE__.testing
+
+import android.content.pm.PackageManager
+import android.content.pm.PermissionInfo
+import androidx.test.platform.app.InstrumentationRegistry
+import org.junit.Assert.fail
+import org.junit.Assume.assumeTrue
+
+/**
+ * Runtime-permission control for the on-device tier — make "what happens when the user
+ * denies it?" a test input instead of a support ticket.
+ *
+ * Why this exists: the recurring production shape is an app that assumes its grant. A
+ * fresh install on API 33+ holds NO notification grant, every `notify()` is dropped
+ * before it reaches the shade, and all of it is silent — the code runs, the phone stays
+ * dark, and every JVM tier stays green. The denied state is the DEFAULT state for a new
+ * user, and it was the one state no test visited.
+ *
+ * THE TRAP this file must document rather than hide — revoking kills the process:
+ * revoking a runtime permission an app currently HOLDS kills that app's process, by OS
+ * design (a process must not keep using a permission it lost). Verified live on a stock
+ * API 35 emulator: `pm revoke <pkg> POST_NOTIFICATIONS` against a running holder killed
+ * its pid on the spot. In this seam the instrumentation lives IN the app's process, so
+ * "revoke my own held permission mid-test" is not a test step, it is the test shooting
+ * itself: the run dies as "Process crashed", attributing the kill to nothing. That is
+ * why this organ ships NO revoke bracket — [withPermissionDenied] instead runs your
+ * block when the permission is already denied (the honest, reachable version of the
+ * state) and SKIPs with the full story when it is not. To genuinely un-grant between
+ * runs, do it from OUTSIDE the process — `adb shell pm revoke <pkg> <permission>` from a
+ * terminal (the app dies; that is the documented behavior, happening where it can be
+ * seen) — or uninstall/reinstall; grants survive `install -r` but not uninstall.
+ *
+ * The second trap — only RUNTIME permissions are controllable, and failure is silent:
+ * `pm grant` on an install-time permission (INTERNET) throws a SecurityException that
+ * UiAutomation's channel cannot even see (stderr is dropped — [Shell]), and on an
+ * UNDECLARED permission it prints nothing and exits 0, a verified silent no-op. So
+ * [grantPermission] never trusts the command: it re-reads the grant, and on failure
+ * diagnoses WHICH misuse happened (undeclared vs install-time vs genuinely refused)
+ * from PackageManager instead of from output that does not exist.
+ */
+object PermissionControl {
+
+    private val context
+        get() = InstrumentationRegistry.getInstrumentation().targetContext
+
+    /** True when [permission] is currently granted to the app under test. */
+    fun isGranted(permission: String): Boolean =
+        context.checkSelfPermission(permission) == PackageManager.PERMISSION_GRANTED
+
+    /**
+     * Grant [permission] to the app under test via `pm grant`, verified by re-reading
+     * the grant — never by trusting the command (see the header for why its failures
+     * are invisible). ONE-WAY by design: there is no restoring revoke, because the
+     * revoke would kill the process doing the restoring. The grant persists until the
+     * app is uninstalled; a test that needs the denied state must run before anything
+     * grants (see [withPermissionDenied]).
+     */
+    fun grantPermission(permission: String) {
+        Shell.assumeOnEmulator(
+            "PermissionControl runs only on emulators (ro.kernel.qemu != 1 here). A " +
+                "grant on a real phone persists until uninstall — state the owner did " +
+                "not choose. Run this suite on a stock QA AVD instead.",
+        )
+        if (isGranted(permission)) return
+        Shell.exec("pm grant ${context.packageName} $permission")
+        if (!isGranted(permission)) {
+            fail(
+                "pm grant did not grant '$permission' — ${diagnoseUngrantable(permission)}",
+            )
+        }
+    }
+
+    /**
+     * Run [block] with [permission] DENIED — the fresh-install default on API 33+, and
+     * the state most escaped bugs live in. Two honest branches:
+     *
+     *  - Already denied: the block runs directly. Nothing is mutated, nothing needs
+     *    restoring — this bracket is safe anywhere, so it carries no emulator guard.
+     *  - Currently granted: SKIP (assumption violation), because the only path from
+     *    granted to denied kills this very process (header). The skip message carries
+     *    the outside-the-process command that reaches the state for real.
+     *
+     * Suite-order honesty: anything that grants — including the seam's own
+     * POST_NOTIFICATIONS setup — moves later tests into the skip branch, and the grant
+     * outlives the run. The denied state is guaranteed only on a fresh install; a SKIP
+     * here is the harness telling you that, not a flake.
+     */
+    fun <T> withPermissionDenied(permission: String, block: () -> T): T {
+        assumeTrue(
+            "'$permission' is currently GRANTED, and revoking a held permission kills " +
+                "the holding process — this very test. Reach the denied state from " +
+                "outside the process instead: `adb shell pm revoke " +
+                "${context.packageName} $permission` (the app is killed; that is the " +
+                "documented OS behavior), or uninstall and reinstall, then re-run.",
+            !isGranted(permission),
+        )
+        return block()
+    }
+
+    /**
+     * Name the reason a grant could not land, from PackageManager truth — the shell's
+     * own error surface is stderr, which the instrumentation channel drops.
+     */
+    private fun diagnoseUngrantable(permission: String): String {
+        val requested = context.packageManager
+            .getPackageInfo(context.packageName, PackageManager.GET_PERMISSIONS)
+            .requestedPermissions?.toList().orEmpty()
+        if (permission !in requested) {
+            return "it is not declared in the manifest, and pm grant on an undeclared " +
+                "permission is a verified silent no-op (no output, exit 0). Declare it " +
+                "with <uses-permission> first."
+        }
+        val protection = try {
+            val info = context.packageManager.getPermissionInfo(permission, 0)
+            if (android.os.Build.VERSION.SDK_INT >= android.os.Build.VERSION_CODES.P) {
+                info.protection
+            } else {
+                @Suppress("DEPRECATION")
+                info.protectionLevel and PermissionInfo.PROTECTION_MASK_BASE
+            }
+        } catch (e: PackageManager.NameNotFoundException) {
+            return "the permission itself does not exist on this device/API level."
+        }
+        if (protection != PermissionInfo.PROTECTION_DANGEROUS) {
+            return "it is not a runtime permission (protection level $protection): " +
+                "install-time permissions are 'not a changeable permission type' — " +
+                "granted at install or never, and pm grant/revoke cannot touch them."
+        }
+        return "it is a declared runtime permission, so this is a genuine refusal — " +
+            "check `dumpsys package ${context.packageName}` for a policy-fixed flag."
+    }
+}

package/template/composeApp/src/androidInstrumentedTest/kotlin/com/example/app/testing/ProcessControl.kt

@@ -0,0 +1,217 @@
+package __PACKAGE__.testing
+
+import android.app.Activity
+import android.os.Build
+import android.os.SystemClock
+import androidx.test.platform.app.InstrumentationRegistry
+import androidx.test.runner.lifecycle.ActivityLifecycleMonitorRegistry
+import androidx.test.runner.lifecycle.Stage
+import org.junit.Assert.fail
+import org.junit.Assume.assumeTrue
+
+/**
+ * Process-death and activity-reclaim control for the on-device tier — the classic
+ * Android state-loss class ("came back from the background and everything was gone"),
+ * made a test input.
+ *
+ * THE TRAP this file must document rather than hide — you cannot kill the process your
+ * test lives in: instrumentation runs INSIDE the app's process, and the OS pins an
+ * instrumented process at foreground importance so the test infrastructure survives.
+ * `am kill` — the command that models real low-memory reclaim, because it kills only
+ * processes the OS itself considers reclaimable (background, no foreground activity) —
+ * is therefore a NO-OP against the app under test while a test runs in it. Verified
+ * live on a stock API 35 emulator: `am kill` against a foreground app left its pid
+ * untouched; against the same app backgrounded, the pid died. (`am force-stop` is the
+ * other command and the WRONG model twice over: it is the user's Settings "Force stop"
+ * — kills every process unconditionally, cancels the app's alarms and jobs, and marks
+ * the app stopped so nothing re-launches it — and in this seam it would take the test
+ * down with the app.) So the honest primitive is not "kill my own process"; it is
+ * making the OS destroy and rebuild what it actually destroys and rebuilds — the
+ * ACTIVITY — through the same save/restore path a process death exercises.
+ *
+ * [withDontKeepActivities] brackets exactly that: `always_finish_activities 1` is the
+ * developer setting Android ships for reproducing this bug class ("Don't keep
+ * activities"), and under it a backgrounded activity is REALLY destroyed — not
+ * config-change recreated: `isChangingConfigurations` is false, the ViewModelStore is
+ * cleared, non-config instances are dropped, and the return trip rebuilds the activity
+ * from its saved-instance-state Bundle. That is the state-restoration path a real
+ * process death takes, minus two things the header must not let a green test overclaim:
+ *  - the process itself survives (verified: same pid across the round trip), so statics,
+ *    singletons, and Application state are NOT re-initialized — a bug hiding in "my
+ *    repository cache is a static" needs a true cold start to show;
+ *  - saved-instance state lives in the ActivityManager, not on disk — reboot loses it.
+ * The true full-process rehearsal stays a two-command manual step, from OUTSIDE the
+ * process: background the app, `adb shell am kill <pkg>`, relaunch — which is exactly
+ * what this organ's in-process bracket cannot be, and says so.
+ *
+ * ONE MORE TRAP, verified live on a stock API 35 image: `settings put global
+ * always_finish_activities 1` alone is a runtime no-op. ActivityTaskManagerService reads
+ * that setting ONCE at boot; the Developer-options toggle works because it calls
+ * `IActivityManager.setAlwaysFinish(..)`, which flips the live in-memory flag AND
+ * persists the setting. Observed: with only the settings write in place, a freshly
+ * launched activity backgrounded to STOPPED and sat there un-destroyed indefinitely.
+ * [withDontKeepActivities] therefore makes the same binder call the toggle makes —
+ * reflection under the shell's adopted permission identity (the shell uid holds
+ * SET_ALWAYS_FINISH on stock images; verified granted on API 35) — and proves the call
+ * landed by re-reading the setting the call itself writes.
+ *
+ * All commands verified root-free from the shell uid on a stock user-build image:
+ * `input keyevent KEYCODE_HOME`, `am start -W -n <component>`, `am kill <pkg>`,
+ * `settings get/put/delete global always_finish_activities` (restore bookkeeping only —
+ * the live flag travels through the binder call above).
+ */
+object ProcessControl {
+
+    private val instrumentation get() = InstrumentationRegistry.getInstrumentation()
+    private val context get() = instrumentation.targetContext
+
+    /**
+     * Run [block] with "Don't keep activities" on — the LIVE flag via
+     * `IActivityManager.setAlwaysFinish` (see the header: the settings write alone is a
+     * boot-time-only input), restoring both afterwards even when the block throws: the
+     * live flag is switched back, then a prior persisted value is put back and an absent
+     * one is deleted, not defaulted. SKIPs below API 29 (adoptShellPermissionIdentity is
+     * the root-free way to hold SET_ALWAYS_FINISH). Inside the block, [backgroundApp]
+     * destroys the foreground activity for real and [relaunchApp] brings it back through
+     * the saved-instance-state path — see RuntimeStateSeamTest for the exemplar shape
+     * (capture identity, plant a saved-state probe, background, await destruction,
+     * relaunch, assert a NEW instance resumed with the probe restored).
+     */
+    fun <T> withDontKeepActivities(block: () -> T): T {
+        Shell.assumeOnEmulator(
+            "ProcessControl runs only on emulators (ro.kernel.qemu != 1 here). " +
+                "Don't-keep-activities on a real phone destroys the owner's app state " +
+                "in every backgrounded app — run this suite on a stock QA AVD instead.",
+        )
+        assumeTrue(
+            "flipping the live always-finish flag needs adoptShellPermissionIdentity " +
+                "(API 29+); device is API ${Build.VERSION.SDK_INT}",
+            Build.VERSION.SDK_INT >= Build.VERSION_CODES.Q,
+        )
+        val prior = Shell.readSetting("global", "always_finish_activities")
+        setAlwaysFinish(true)
+        try {
+            return block()
+        } finally {
+            setAlwaysFinish(prior == "1")
+            Shell.restoreSetting("global", "always_finish_activities", prior)
+        }
+    }
+
+    /**
+     * The Developer-options toggle's own path: `IActivityManager.setAlwaysFinish`, called
+     * with the shell's adopted permission identity (shell holds SET_ALWAYS_FINISH). This
+     * is what actually updates ActivityTaskManagerService's in-memory flag at runtime —
+     * the settings provider write alone is read once at boot and never again (header).
+     * The call also persists the setting, which is the echo this method re-reads to prove
+     * the binder call landed rather than trusting it.
+     */
+    private fun setAlwaysFinish(enabled: Boolean) {
+        val uiAutomation = instrumentation.uiAutomation
+        uiAutomation.adoptShellPermissionIdentity("android.permission.SET_ALWAYS_FINISH")
+        try {
+            val service = Class.forName("android.app.ActivityManager")
+                .getMethod("getService")
+                .invoke(null)
+            Class.forName("android.app.IActivityManager")
+                .getMethod("setAlwaysFinish", java.lang.Boolean.TYPE)
+                .invoke(service, enabled)
+        } catch (e: ReflectiveOperationException) {
+            fail(
+                "IActivityManager.setAlwaysFinish is unreachable on this image " +
+                    "($e) — the hidden-API surface moved, so the don't-keep bracket " +
+                    "cannot flip the live flag; ProcessControl's header needs revisiting",
+            )
+        } finally {
+            uiAutomation.dropShellPermissionIdentity()
+        }
+        val echoed = Shell.readSetting("global", "always_finish_activities")
+        val expected = if (enabled) "1" else "0"
+        if (echoed != expected) {
+            fail(
+                "setAlwaysFinish($enabled) did not echo into the persisted setting " +
+                    "(read '$echoed') — the binder call did not reach the " +
+                    "ActivityTaskManager",
+            )
+        }
+    }
+
+    /**
+     * Send the app to the background (HOME key via the shell — the user's own gesture),
+     * then wait (bounded) until no activity of the app is in the RESUMED stage. Under
+     * [withDontKeepActivities] this is the destruction trigger.
+     */
+    fun backgroundApp(timeoutMs: Long = 10_000L) {
+        Shell.exec("input keyevent KEYCODE_HOME")
+        val deadline = SystemClock.elapsedRealtime() + timeoutMs
+        while (SystemClock.elapsedRealtime() < deadline) {
+            if (resumedActivity() == null) return
+            Thread.sleep(100)
+        }
+        fail("the app still has a RESUMED activity ${timeoutMs}ms after HOME")
+    }
+
+    /**
+     * Relaunch the app's launcher activity (`am start -W -n`, resolved from the app's own
+     * launch intent — never hardcoded) and return the newly RESUMED activity instance.
+     * The instance is how the exemplar proves destruction happened: same instance back
+     * means nothing was destroyed and the bracket proved nothing.
+     */
+    fun relaunchApp(timeoutMs: Long = 10_000L): Activity {
+        val component = context.packageManager.getLaunchIntentForPackage(context.packageName)
+            ?.component
+            ?: fail("no launch intent for ${context.packageName} — nothing to relaunch")
+                .let { error("unreachable") }
+        Shell.exec("am start -W -n ${component.flattenToShortString()}")
+        val deadline = SystemClock.elapsedRealtime() + timeoutMs
+        while (SystemClock.elapsedRealtime() < deadline) {
+            resumedActivity()?.let { return it }
+            Thread.sleep(100)
+        }
+        fail("no activity reached RESUMED within ${timeoutMs}ms of am start")
+        error("unreachable")
+    }
+
+    /**
+     * Wait (bounded) until [activity] is genuinely destroyed. Backgrounding and
+     * destruction are two separate asynchronous steps — relaunching between them brings
+     * the SAME instance back and the bracket proves nothing, so the exemplar waits for
+     * this before relaunching.
+     */
+    fun awaitDestroyed(activity: Activity, timeoutMs: Long = 10_000L) {
+        val deadline = SystemClock.elapsedRealtime() + timeoutMs
+        while (SystemClock.elapsedRealtime() < deadline) {
+            var destroyed = false
+            instrumentation.runOnMainSync { destroyed = activity.isDestroyed }
+            if (destroyed) return
+            Thread.sleep(100)
+        }
+        fail(
+            "the backgrounded activity was not destroyed within ${timeoutMs}ms — is " +
+                "don't-keep-activities actually on (withDontKeepActivities), and was " +
+                "the app really backgrounded first?",
+        )
+    }
+
+    /** The app's currently RESUMED activity, or null (read on the main thread, as the monitor requires). */
+    fun resumedActivity(): Activity? {
+        var current: Activity? = null
+        instrumentation.runOnMainSync {
+            current = ActivityLifecycleMonitorRegistry.getInstance()
+                .getActivitiesInStage(Stage.RESUMED).firstOrNull()
+        }
+        return current
+    }
+
+    /**
+     * `am kill` — the low-memory-reclaim model, exposed for the one thing it can honestly
+     * do in this seam: kill the app's AUXILIARY processes (components declared with
+     * `android:process`), which are not pinned the way the instrumented main process is.
+     * Against the main process it is a no-op while the test runs (header); the exemplar
+     * asserts that fact live, so the day an OS change breaks the assumption, the suite
+     * says so instead of this comment silently rotting.
+     */
+    fun killReclaimableProcesses(packageName: String = context.packageName) {
+        Shell.exec("am kill $packageName")
+    }
+}

package/template/composeApp/src/androidInstrumentedTest/kotlin/com/example/app/testing/Shell.kt

@@ -0,0 +1,79 @@
+package __PACKAGE__.testing
+
+import android.os.ParcelFileDescriptor
+import androidx.test.platform.app.InstrumentationRegistry
+import org.junit.Assume.assumeTrue
+
+/**
+ * The one shell channel for the on-device tier. Every organ in this package — the asserts
+ * that READ device state ([AlarmAsserts], [NotificationAsserts]) and the controls that
+ * MUTATE it ([TimeWarp], [DozeControl], [PermissionControl], [ProcessControl],
+ * [NetworkControl], [ConfigControl]) — goes through [exec], and every mutating organ gates
+ * on [assumeOnEmulator]. One channel, one guard, so a new organ can't quietly invent a
+ * weaker version of either.
+ *
+ * Why the shell at all: the states these organs put the device into (idle, offline,
+ * permission-denied, dark, warped clock) are deliberately not reachable from app APIs —
+ * they are the OS's side of the contract. The instrumentation's UiAutomation runs its
+ * shell commands with the SHELL uid, which is privileged enough for all of them and
+ * available on every stock emulator image. No root: `adb root` is refused on production
+ * (user-build) images, including the stock Play-image AVDs, and every command an organ
+ * issues has been verified to work without it.
+ *
+ * Constraints the code can't show:
+ *  - STDOUT ONLY. UiAutomation's channel returns the command's stdout and silently drops
+ *    stderr. This is not cosmetic: `pm grant` on an install-time permission prints its
+ *    SecurityException to stderr (invisible here), and `pm grant` on an UNDECLARED
+ *    permission prints nothing anywhere and exits 0 — a silent no-op (both verified on a
+ *    stock API 35 image). An organ must therefore prove its command worked by re-reading
+ *    the state it changed, never by trusting output or exit status it cannot see.
+ *  - No shell interpretation. The command string is tokenized, not run through `sh -c` —
+ *    no quoting, no pipes, no redirection. Compose commands accordingly (every organ's
+ *    commands are plain token lists).
+ */
+object Shell {
+
+    /** Runs [command] via UiAutomation (shell uid) and returns its full stdout. */
+    fun exec(command: String): String {
+        val pfd = InstrumentationRegistry.getInstrumentation().uiAutomation
+            .executeShellCommand(command)
+        ParcelFileDescriptor.AutoCloseInputStream(pfd).use { stream ->
+            return stream.readBytes().decodeToString()
+        }
+    }
+
+    /** True on an emulator (`ro.kernel.qemu == 1`) — the property every guard checks. */
+    fun isEmulator(): Boolean = exec("getprop ro.kernel.qemu").trim() == "1"
+
+    /**
+     * SKIPs the test (assumption violation, never a failure) unless it runs on an
+     * emulator. Every state-mutating organ calls this first with its own message saying
+     * what it would have done to a real phone's owner — a QA emulator is disposable
+     * state; a person's device never is. Call it at the top of your own test too, so the
+     * skip names the test rather than a helper frame.
+     */
+    fun assumeOnEmulator(message: String) {
+        assumeTrue(message, isEmulator())
+    }
+
+    /**
+     * A setting's current value, or null when unset — `settings get` prints the literal
+     * string "null" for absent keys, and this maps it back to the truth.
+     */
+    fun readSetting(namespace: String, key: String): String? =
+        exec("settings get $namespace $key").trim()
+            .takeUnless { it.isEmpty() || it == "null" }
+
+    /**
+     * Restore a setting to the state [readSetting] captured: a prior value is put back,
+     * an absent one is DELETED — putting a guessed default where none existed is itself
+     * drift, and the next test would inherit it.
+     */
+    fun restoreSetting(namespace: String, key: String, prior: String?) {
+        if (prior == null) {
+            exec("settings delete $namespace $key")
+        } else {
+            exec("settings put $namespace $key $prior")
+        }
+    }
+}