create-cmp-cli 0.11.0 → 0.12.0

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

@@ -0,0 +1,277 @@
+package __PACKAGE__
+
+import android.app.AlarmManager
+import android.app.Notification
+import android.app.NotificationChannel
+import android.app.NotificationManager
+import android.content.BroadcastReceiver
+import android.content.Context
+import android.content.Intent
+import android.content.IntentFilter
+import android.app.PendingIntent
+import android.os.Build
+import android.os.SystemClock
+import android.util.Log
+import androidx.test.core.app.ActivityScenario
+import androidx.test.ext.junit.runners.AndroidJUnit4
+import androidx.test.platform.app.InstrumentationRegistry
+import __PACKAGE__.testing.AlarmAsserts
+import __PACKAGE__.testing.NotificationAsserts
+import __PACKAGE__.testing.TimeWarp
+import java.util.concurrent.CountDownLatch
+import java.util.concurrent.TimeUnit
+import java.util.concurrent.atomic.AtomicLong
+import org.junit.After
+import org.junit.Assert.assertNotNull
+import org.junit.Assert.assertTrue
+import org.junit.Assume.assumeTrue
+import org.junit.Before
+import org.junit.Test
+import org.junit.runner.RunWith
+
+/**
+ * The exemplar for the on-device behavior tier — and the proof that the seam works.
+ *
+ * This seam exists because platform behavior escapes every desktop tier; when your feature
+ * touches alarms, notifications, or locks, its behavior test lives here. Desktop unit tests
+ * run on a JVM, golden trees pin structure, the conformance suite is static, and the
+ * Maestro smoke taps UI without asserting anything about the notification shade or the OS
+ * alarm table — so a feature whose whole point is "the phone alerts" can ship fully green
+ * and never alert. In two real apps built on this template, that exact class produced nine
+ * escaped defects across multiple releases; the hand-built version of this source set
+ * caught two more bugs the week it landed.
+ *
+ * What the template can honestly exemplify: the stamped app ships no notification or alarm
+ * feature yet, so these tests assert universal facts through the app's REAL process on a
+ * real device — the app boots (its Android DI graph resolves for real, which desktop fakes
+ * cannot prove), and the tier's helpers observe true OS state (a posted notification is
+ * seen in the shade, a scheduled alarm is seen in the alarm table, and the
+ * PendingIntent-identity collision is demonstrated live). When your first feature posts
+ * its own notification, replace the direct NotificationManager call below with your
+ * feature's real path and keep the assertions — that is the whole pattern.
+ *
+ * Runs via `:composeApp:connectedDebugAndroidTest` — the verify lane's `androidChecks`
+ * step (SKIPs when no device is attached; cite platform-behavior spec clauses from here).
+ */
+@RunWith(AndroidJUnit4::class)
+class PlatformBehaviorSeamTest {
+
+    private val context: Context
+        get() = InstrumentationRegistry.getInstrumentation().targetContext
+
+    private val notificationManager: NotificationManager
+        get() = context.getSystemService(Context.NOTIFICATION_SERVICE) as NotificationManager
+
+    private val alarmManager: AlarmManager
+        get() = context.getSystemService(Context.ALARM_SERVICE) as AlarmManager
+
+    @Before
+    fun setUp() {
+        // A fresh install has no POST_NOTIFICATIONS grant on API 33+, and without it every
+        // post is dropped before it reaches the shade — the notification test would then
+        // fail about the harness, not the app. The grant is taken, never hoped for.
+        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.TIRAMISU) {
+            runCatching {
+                InstrumentationRegistry.getInstrumentation().uiAutomation.grantRuntimePermission(
+                    context.packageName,
+                    "android.permission.POST_NOTIFICATIONS",
+                )
+            }
+        }
+    }
+
+    @After
+    fun tearDown() {
+        // Leave the device as found: this tier asserts real OS state, so real OS state
+        // must be cleaned up — a leaked notification or alarm pollutes the NEXT test run.
+        notificationManager.cancelAll()
+        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) {
+            notificationManager.deleteNotificationChannel(PROBE_CHANNEL)
+        }
+        listOf(REQUEST_A, REQUEST_B, REQUEST_SHARED).forEach { code ->
+            alarmManager.cancel(probePendingIntent(code, ACTION_PROBE))
+        }
+        alarmManager.cancel(probePendingIntent(REQUEST_WARP, ACTION_WARP))
+    }
+
+    @Test
+    fun theRealAppBootsOnTheDevice() {
+        // Not a tautology: this launches MainActivity in the app's real process with the
+        // real AppApplication — Koin's ANDROID graph resolves for real (desktop DI
+        // substitutes fakes, so an androidMain-only wiring bug is invisible to every other
+        // tier; a real app on this template shipped exactly that crash). If the app cannot
+        // boot, nothing else in this tier means anything, so this is the tier's smoke.
+        ActivityScenario.launch(MainActivity::class.java).use { scenario ->
+            assertNotNull(scenario.state)
+        }
+    }
+
+    @Test
+    fun aPostedNotificationIsVisibleToTheShadeAndItsChannelHoldsItsImportance() {
+        assumeTrue(Build.VERSION.SDK_INT >= Build.VERSION_CODES.O)
+        // The template has no notification feature yet, so the post goes through
+        // NotificationManager directly — proving the helpers see true OS state. In your
+        // feature's test, this arrange step becomes a call into YOUR notification path.
+        notificationManager.createNotificationChannel(
+            NotificationChannel(PROBE_CHANNEL, "Seam probe", NotificationManager.IMPORTANCE_HIGH),
+        )
+        notificationManager.notify(
+            PROBE_ID,
+            Notification.Builder(context, PROBE_CHANNEL)
+                .setSmallIcon(android.R.drawable.ic_dialog_info)
+                .setContentTitle("seam probe")
+                .build(),
+        )
+
+        // The assertions cross the process boundary: the OS accepted the channel at the
+        // importance the app created it with, and the notification actually reached the
+        // shade — the two facts that silently broke in production, repeatedly.
+        NotificationAsserts.assertChannelExists(
+            PROBE_CHANNEL,
+            importanceFloor = NotificationManager.IMPORTANCE_HIGH,
+        )
+        NotificationAsserts.awaitNotification(id = PROBE_ID)
+    }
+
+    @Test
+    fun twoLogicalAlarmsNeedTwoPendingIntentIdentities() {
+        val base = System.currentTimeMillis() + HOUR_MS
+
+        // Distinct request codes -> distinct PendingIntent identities -> two rows in the
+        // OS alarm table. This is the correct shape for "N independent schedules".
+        alarmManager.set(AlarmManager.RTC, base, probePendingIntent(REQUEST_A, ACTION_PROBE))
+        alarmManager.set(AlarmManager.RTC, base + 60_000, probePendingIntent(REQUEST_B, ACTION_PROBE))
+        AlarmAsserts.assertDistinctAlarms(
+            expected = 2,
+            what = "seam-probe alarms (distinct request codes)",
+        ) { it.whenMs == base || it.whenMs == base + 60_000 }
+
+        // The trap, demonstrated live: same request code + filter-equal intent (extras do
+        // NOT count) is ONE identity, so the second set() silently REPLACES the first —
+        // no error, no log, and only this table shows it. This exact shape shipped as two
+        // "independent" alarms sharing a slot.
+        val t3 = base + HOUR_MS
+        alarmManager.set(AlarmManager.RTC, t3, probePendingIntent(REQUEST_SHARED, ACTION_PROBE))
+        alarmManager.set(AlarmManager.RTC, t3 + 60_000, probePendingIntent(REQUEST_SHARED, ACTION_PROBE))
+        AlarmAsserts.assertDistinctAlarms(
+            expected = 1,
+            what = "seam-probe alarms (shared identity — the later set replaces the earlier)",
+        ) { it.whenMs == t3 || it.whenMs == t3 + 60_000 }
+    }
+
+    @Test
+    fun anExactAlarmScheduledForTheFutureActuallyDeliversWhenItsTimeArrives() {
+        // The proof shape for "my scheduled thing actually fires": registration says the
+        // OS *holds* the alarm ([twoLogicalAlarmsNeedTwoPendingIntentIdentities] stops
+        // there); this test warps the clock past the trigger time and watches DELIVERY —
+        // the onReceive that no other tier can observe, in seconds instead of hours. In
+        // your feature's test, the arrange step becomes YOUR scheduling path (the ladder
+        // that computes "tomorrow at 08:00") and the receiver becomes YOUR receiver —
+        // keep the shape: schedule → assert registered → warp past T → await delivery →
+        // assert the OS slot is consumed. Emulator-only via TimeWarp's guard.
+        TimeWarp.assumeOnEmulator()
+
+        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.S) {
+            // Exact alarms are permission-gated from API 31. The debug manifest declares
+            // SCHEDULE_EXACT_ALARM (≤32, granted by default there) and USE_EXACT_ALARM
+            // (33+, granted at install) — see androidDebug/AndroidManifest.xml for why
+            // they live in the debug manifest and not the shipped one.
+            assertTrue(
+                "canScheduleExactAlarms() is false — the debug-manifest exact-alarm " +
+                    "grant (androidDebug/AndroidManifest.xml) is missing or was removed; " +
+                    "setExactAndAllowWhileIdle would throw SecurityException",
+                alarmManager.canScheduleExactAlarms(),
+            )
+        }
+
+        val delivered = CountDownLatch(1)
+        val deliveredAtElapsed = AtomicLong(0)
+        val receiver = object : BroadcastReceiver() {
+            override fun onReceive(receiverContext: Context?, intent: Intent?) {
+                deliveredAtElapsed.set(SystemClock.elapsedRealtime())
+                delivered.countDown()
+            }
+        }
+        // Dynamic registration: the receiver lives exactly as long as the test, no
+        // manifest entry to leak. NOT_EXPORTED is correct because AlarmManager sends the
+        // PendingIntent's broadcast with this app's own identity (API 33+ requires the
+        // exported flag to be stated for context-registered receivers).
+        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.TIRAMISU) {
+            context.registerReceiver(
+                receiver,
+                IntentFilter(ACTION_WARP),
+                Context.RECEIVER_NOT_EXPORTED,
+            )
+        } else {
+            @Suppress("UnspecifiedRegisterReceiverFlag")
+            context.registerReceiver(receiver, IntentFilter(ACTION_WARP))
+        }
+
+        try {
+            // Far enough ahead that nothing fires before the warp; close enough that a
+            // registration-time sanity read stays cheap.
+            val target = System.currentTimeMillis() + 2 * 60_000L
+            alarmManager.setExactAndAllowWhileIdle(
+                AlarmManager.RTC_WAKEUP,
+                target,
+                probePendingIntent(REQUEST_WARP, ACTION_WARP),
+            )
+            AlarmAsserts.assertAlarmRegistered("the warp-probe exact alarm") {
+                it.whenMs == target
+            }
+
+            TimeWarp.withWarpedClock(target + 5_000L) {
+                val warpedAtElapsed = SystemClock.elapsedRealtime()
+                // Bounded on monotonic time (latch.await is nanoTime-based), so the
+                // warped wall clock cannot distort the timeout.
+                assertTrue(
+                    "the exact alarm did not deliver within 60s of the clock warping " +
+                        "past its trigger time — scheduled for $target, clock warped to " +
+                        "${target + 5_000L}",
+                    delivered.await(60, TimeUnit.SECONDS),
+                )
+                Log.i(
+                    "PlatformBehaviorSeam",
+                    "warp-probe alarm delivered ${deliveredAtElapsed.get() - warpedAtElapsed}ms " +
+                        "after the clock warp",
+                )
+            }
+
+            // Delivery consumes the OS slot: the registry entry must be gone. Bounded
+            // poll on monotonic time — the table update can trail the broadcast slightly.
+            val goneDeadline = SystemClock.elapsedRealtime() + 10_000L
+            while (SystemClock.elapsedRealtime() < goneDeadline &&
+                AlarmAsserts.registeredAlarms().any { it.whenMs == target }
+            ) {
+                Thread.sleep(200)
+            }
+            assertTrue(
+                "the warp-probe alarm fired but its entry is still in the OS alarm table " +
+                    "— a fired one-shot alarm must be consumed, not re-armed",
+                AlarmAsserts.registeredAlarms().none { it.whenMs == target },
+            )
+        } finally {
+            context.unregisterReceiver(receiver)
+        }
+    }
+
+    private fun probePendingIntent(requestCode: Int, action: String): PendingIntent =
+        PendingIntent.getBroadcast(
+            context,
+            requestCode,
+            Intent(action).setPackage(context.packageName),
+            PendingIntent.FLAG_UPDATE_CURRENT or PendingIntent.FLAG_IMMUTABLE,
+        )
+
+    private companion object {
+        const val PROBE_CHANNEL = "seam_probe"
+        const val PROBE_ID = 424_242
+        const val ACTION_PROBE = "cmp.seam.PROBE_ALARM"
+        const val REQUEST_A = 424_301
+        const val REQUEST_B = 424_302
+        const val REQUEST_SHARED = 424_303
+        const val ACTION_WARP = "cmp.seam.WARP_ALARM"
+        const val REQUEST_WARP = 424_304
+        const val HOUR_MS = 60L * 60 * 1000
+    }
+}

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

@@ -0,0 +1,308 @@
+package __PACKAGE__
+
+import android.app.AlarmManager
+import android.app.Notification
+import android.app.NotificationChannel
+import android.app.NotificationManager
+import android.app.PendingIntent
+import android.content.BroadcastReceiver
+import android.content.Context
+import android.content.Intent
+import android.content.IntentFilter
+import android.os.Build
+import android.os.Bundle
+import android.os.Process
+import android.os.SystemClock
+import androidx.savedstate.SavedStateRegistryOwner
+import androidx.test.ext.junit.runners.AndroidJUnit4
+import androidx.test.platform.app.InstrumentationRegistry
+import __PACKAGE__.testing.AlarmAsserts
+import __PACKAGE__.testing.DozeControl
+import __PACKAGE__.testing.NotificationAsserts
+import __PACKAGE__.testing.PermissionControl
+import __PACKAGE__.testing.ProcessControl
+import __PACKAGE__.testing.Shell
+import __PACKAGE__.testing.TimeWarp
+import java.util.concurrent.CountDownLatch
+import java.util.concurrent.TimeUnit
+import org.junit.After
+import org.junit.Assert.assertEquals
+import org.junit.Assert.assertNotEquals
+import org.junit.Assert.assertTrue
+import org.junit.Assume.assumeTrue
+import org.junit.Test
+import org.junit.runner.RunWith
+
+/**
+ * The exemplars for RUNTIME STATE CONTROL — the seam's second organ family.
+ *
+ * One principle: a claim is provable when the test can put the system into the state the
+ * claim is about. Most unprovable mobile claims are unprovable for exactly that reason —
+ * the state is hard to reach. You'd have to wait hours for Doze, ship to a user who
+ * denies the permission, or hope the OS reclaims your process while you watch. The
+ * organs in `testing/` reach those states on demand and restore them in `finally`:
+ * [TimeWarp] (the clock), [DozeControl] (device idle), [PermissionControl] (grants),
+ * [ProcessControl] (activity reclaim), NetworkControl (offline), ConfigControl (dark
+ * mode / font scale / locale). Emulator-only by guard, root-free by construction, and
+ * composable — the flagship below nests two of them.
+ *
+ * These tests assert universal facts through the app's real process, like
+ * [PlatformBehaviorSeamTest] does: the stamped app has no alarm or notification feature
+ * yet, so the arrange steps talk to the OS directly. When your feature exists, its
+ * behavior test replaces the arrange step with YOUR scheduling/posting/restoring path
+ * and keeps the shape — state in, act, observe, state restored.
+ *
+ * Runs via `:composeApp:connectedDebugAndroidTest` — the verify lane's `androidChecks`
+ * step (SKIPs when no device is attached).
+ */
+@RunWith(AndroidJUnit4::class)
+class RuntimeStateSeamTest {
+
+    private val context: Context
+        get() = InstrumentationRegistry.getInstrumentation().targetContext
+
+    private val notificationManager: NotificationManager
+        get() = context.getSystemService(Context.NOTIFICATION_SERVICE) as NotificationManager
+
+    private val alarmManager: AlarmManager
+        get() = context.getSystemService(Context.ALARM_SERVICE) as AlarmManager
+
+    @After
+    fun tearDown() {
+        // Leave the device as found — real OS state was asserted, so real OS state is
+        // cleaned up (the organs restore their own brackets; this catches the probes).
+        notificationManager.cancelAll()
+        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) {
+            notificationManager.deleteNotificationChannel(PROBE_CHANNEL)
+        }
+        alarmManager.cancel(probePendingIntent())
+    }
+
+    @Test
+    fun anExactAllowWhileIdleAlarmDeliversFromInsideForcedDeepIdle() {
+        // THE FLAGSHIP. `setExactAndAllowWhileIdle` exists entirely to survive Doze, and
+        // that half of its name had never been verified: registration was proven
+        // (AlarmAsserts), delivery-on-an-awake-device was proven (TimeWarp), but
+        // delivery FROM INSIDE the idle state — the production claim, the #1 escaped-bug
+        // class in real apps on this template — required a device nobody was willing to
+        // leave motionless on battery for an hour. Composed organs make it a
+        // sixty-second test: force deep idle, warp the clock past the trigger, and the
+        // OS either honors the API's promise or the test says it didn't. In your
+        // feature's test, the arrange step becomes YOUR scheduling ladder; keep the
+        // shape: schedule → assert registered → force idle → warp → await delivery.
+        TimeWarp.assumeOnEmulator()
+
+        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.S) {
+            assertTrue(
+                "canScheduleExactAlarms() is false — the debug-manifest exact-alarm " +
+                    "grant (androidDebug/AndroidManifest.xml) is missing; " +
+                    "setExactAndAllowWhileIdle would throw SecurityException",
+                alarmManager.canScheduleExactAlarms(),
+            )
+        }
+
+        val delivered = CountDownLatch(1)
+        val receiver = object : BroadcastReceiver() {
+            override fun onReceive(receiverContext: Context?, intent: Intent?) {
+                delivered.countDown()
+            }
+        }
+        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.TIRAMISU) {
+            context.registerReceiver(
+                receiver,
+                IntentFilter(ACTION_DOZE_PROBE),
+                Context.RECEIVER_NOT_EXPORTED,
+            )
+        } else {
+            @Suppress("UnspecifiedRegisterReceiverFlag")
+            context.registerReceiver(receiver, IntentFilter(ACTION_DOZE_PROBE))
+        }
+
+        try {
+            val target = System.currentTimeMillis() + 2 * 60_000L
+            alarmManager.setExactAndAllowWhileIdle(
+                AlarmManager.RTC_WAKEUP,
+                target,
+                probePendingIntent(),
+            )
+            AlarmAsserts.assertAlarmRegistered("the doze-probe exact alarm") {
+                it.whenMs == target
+            }
+
+            // Doze outside, clock inside: the device is idle FIRST, then its trigger
+            // time arrives — the same order the world runs in.
+            DozeControl.withDeviceIdle(DozeControl.IdleMode.DEEP) {
+                TimeWarp.withWarpedClock(target + 5_000L) {
+                    assertTrue(
+                        "the exact allow-while-idle alarm did not deliver within 60s of " +
+                            "its trigger time arriving inside forced deep idle — the one " +
+                            "job the API's name promises",
+                        delivered.await(60, TimeUnit.SECONDS),
+                    )
+                }
+            }
+
+            // Delivery consumes the OS slot (bounded poll; the table can trail the
+            // broadcast slightly).
+            val goneDeadline = SystemClock.elapsedRealtime() + 10_000L
+            while (SystemClock.elapsedRealtime() < goneDeadline &&
+                AlarmAsserts.registeredAlarms().any { it.whenMs == target }
+            ) {
+                Thread.sleep(200)
+            }
+            assertTrue(
+                "the doze-probe alarm fired but is still in the OS alarm table — a " +
+                    "fired one-shot must be consumed, not re-armed",
+                AlarmAsserts.registeredAlarms().none { it.whenMs == target },
+            )
+        } finally {
+            context.unregisterReceiver(receiver)
+        }
+    }
+
+    @Test
+    fun aNotificationPostedWithoutTheGrantNeverReachesTheShade() {
+        // The permission-denied exemplar: the fresh-install default on API 33+ is
+        // DENIED, and in that state the OS drops every post silently — code runs, phone
+        // stays dark, no error anywhere. This proves that drop mechanically: post under
+        // denial, then hold assertNoNotification's full window. The bracket SKIPs when
+        // the grant is already held (the seam's other suite takes it, and un-granting
+        // in-process would kill this test — PermissionControl's header carries the
+        // whole trap). In your feature's test, the act step becomes YOUR notification
+        // path, and the assertion becomes "it degrades the way the spec says" —
+        // re-prompt, in-app banner, queued — instead of "nothing happened".
+        // The permission only exists — and only gates posting — from API 33; below that
+        // a post lands regardless, so there is no denied state to prove.
+        assumeTrue(
+            "POST_NOTIFICATIONS gates posting only from API 33 " +
+                "(device is ${Build.VERSION.SDK_INT})",
+            Build.VERSION.SDK_INT >= Build.VERSION_CODES.TIRAMISU,
+        )
+        Shell.assumeOnEmulator(
+            "this exemplar reads and posts against the real shade in a denied state — " +
+                "stock QA AVDs only",
+        )
+        PermissionControl.withPermissionDenied("android.permission.POST_NOTIFICATIONS") {
+            assertTrue(
+                "areNotificationsEnabled() is true while POST_NOTIFICATIONS is denied — " +
+                    "the two surfaces should agree on API 33+",
+                !notificationManager.areNotificationsEnabled(),
+            )
+            notificationManager.createNotificationChannel(
+                NotificationChannel(
+                    PROBE_CHANNEL,
+                    "Runtime-state probe",
+                    NotificationManager.IMPORTANCE_HIGH,
+                ),
+            )
+            notificationManager.notify(
+                PROBE_ID,
+                Notification.Builder(context, PROBE_CHANNEL)
+                    .setSmallIcon(android.R.drawable.ic_dialog_info)
+                    .setContentTitle("runtime-state probe")
+                    .build(),
+            )
+            NotificationAsserts.assertNoNotification { it.id == PROBE_ID }
+        }
+    }
+
+    @Test
+    fun theOsRebuildsTheActivityThroughTheSavedStatePathWhenItReclaimsIt() {
+        // The process-death exemplar — with the seam's honesty about what "process
+        // death" can mean in-process. Instrumentation lives in the app's process, and
+        // the OS pins that process at foreground importance, so `am kill` cannot
+        // reclaim it (asserted LIVE below, so the claim never rots into a stale
+        // comment). What the OS genuinely destroys and rebuilds is the ACTIVITY:
+        // under don't-keep-activities, backgrounding destroys it for real —
+        // ViewModelStore cleared, non-config instances dropped — and the return trip
+        // rebuilds it from saved-instance state, the same path a true process death
+        // takes at the activity layer. In your feature's test, the assertions become
+        // YOUR restored state: the half-typed form, the scroll position, the selection.
+        ProcessControl.withDontKeepActivities {
+            val first = ProcessControl.relaunchApp()
+            val firstIdentity = System.identityHashCode(first)
+
+            // The saved-state probe: a nonce registered into the FIRST instance's
+            // SavedStateRegistry (MainActivity is a ComponentActivity, and everything
+            // rememberSaveable/SavedStateHandle keeps rides this same registry). If the
+            // rebuild really runs through the saved-instance-state path, the SECOND
+            // instance restores it — asserted below, so "through the saved-state path"
+            // is observed, not inferred from a new instance existing.
+            assertTrue(
+                "the launcher activity is not a SavedStateRegistryOwner — the " +
+                    "template's MainActivity is a ComponentActivity, which is one; " +
+                    "the saved-state probe needs that registry",
+                first is SavedStateRegistryOwner,
+            )
+            val savedProbe = "probe-${SystemClock.elapsedRealtimeNanos()}"
+            InstrumentationRegistry.getInstrumentation().runOnMainSync {
+                (first as SavedStateRegistryOwner).savedStateRegistry
+                    .registerSavedStateProvider(SAVED_STATE_PROBE_KEY) {
+                        Bundle().apply { putString("token", savedProbe) }
+                    }
+            }
+
+            ProcessControl.backgroundApp()
+            // Backgrounding and destruction are separate asynchronous steps; relaunching
+            // between them would resume the SAME instance and prove nothing.
+            ProcessControl.awaitDestroyed(first)
+
+            // The live no-op proof: am kill against the pinned instrumented process
+            // must leave this very pid running (observed from the OS side, not from
+            // hope). If an OS change ever breaks the pinning, this line is where the
+            // suite says so.
+            ProcessControl.killReclaimableProcesses()
+            val pids = Shell.exec("pidof ${context.packageName}").trim()
+                .split(Regex("\\s+")).filter { it.isNotEmpty() }
+            assertTrue(
+                "am kill reclaimed the instrumented process (pid ${Process.myPid()} " +
+                    "not in '$pids') — the foreground pinning assumption no longer " +
+                    "holds on this image; ProcessControl's header needs revisiting",
+                pids.contains(Process.myPid().toString()),
+            )
+
+            val second = ProcessControl.relaunchApp()
+            try {
+                assertNotEquals(
+                    "the same Activity instance came back after backgrounding under " +
+                        "don't-keep-activities — nothing was destroyed, so nothing " +
+                        "about state restoration was proven",
+                    firstIdentity,
+                    System.identityHashCode(second),
+                )
+                var restored: Bundle? = null
+                InstrumentationRegistry.getInstrumentation().runOnMainSync {
+                    restored = (second as SavedStateRegistryOwner).savedStateRegistry
+                        .consumeRestoredStateForKey(SAVED_STATE_PROBE_KEY)
+                }
+                assertEquals(
+                    "a NEW instance resumed but the probe did not come back through " +
+                        "its SavedStateRegistry — destruction happened, restoration " +
+                        "did not, so the saved-state path is NOT proven",
+                    savedProbe,
+                    restored?.getString("token"),
+                )
+            } finally {
+                InstrumentationRegistry.getInstrumentation().runOnMainSync {
+                    second.finish()
+                }
+            }
+        }
+    }
+
+    private fun probePendingIntent(): PendingIntent =
+        PendingIntent.getBroadcast(
+            context,
+            REQUEST_DOZE_PROBE,
+            Intent(ACTION_DOZE_PROBE).setPackage(context.packageName),
+            PendingIntent.FLAG_UPDATE_CURRENT or PendingIntent.FLAG_IMMUTABLE,
+        )
+
+    private companion object {
+        const val PROBE_CHANNEL = "runtime_state_probe"
+        const val PROBE_ID = 434_242
+        const val ACTION_DOZE_PROBE = "cmp.seam.DOZE_PROBE_ALARM"
+        const val REQUEST_DOZE_PROBE = 434_301
+        const val SAVED_STATE_PROBE_KEY = "cmp.seam.savedStateProbe"
+    }
+}