create-cmp-cli 0.2.0 → 0.3.0

package/template/composeApp/src/commonTest/kotlin/com/example/app/domain/usecase/GetItemsUseCaseTest.kt

@@ -0,0 +1,37 @@
+package __PACKAGE__.domain.usecase
+
+import __PACKAGE__.domain.model.Item
+import __PACKAGE__.testing.fakes.FakeItemRepository
+import kotlin.test.Test
+import kotlin.test.assertEquals
+import kotlin.test.assertFailsWith
+import kotlinx.coroutines.test.runTest
+
+/**
+ * The exemplar use-case test. Use cases are pure business actions with no framework
+ * dependencies, so their tests are the simplest in the pyramid: fake in, behavior out.
+ */
+class GetItemsUseCaseTest {
+
+    private val repository = FakeItemRepository()
+    private val getItems = GetItemsUseCase(repository)
+
+    @Test
+    fun `returns the repository's items`() = runTest {
+        val expected = listOf(
+            Item(id = "1", title = "First", subtitle = "a"),
+            Item(id = "2", title = "Second", subtitle = "b"),
+        )
+        repository.items = expected
+
+        assertEquals(expected, getItems())
+        assertEquals(1, repository.getItemsCallCount)
+    }
+
+    @Test
+    fun `propagates repository failures to the caller`() = runTest {
+        repository.shouldFail = true
+
+        assertFailsWith<IllegalStateException> { getItems() }
+    }
+}

package/template/composeApp/src/commonTest/kotlin/com/example/app/presentation/home/HomeViewModelTest.kt

@@ -0,0 +1,104 @@
+package __PACKAGE__.presentation.home
+
+import app.cash.turbine.test
+import __PACKAGE__.domain.model.Item
+import __PACKAGE__.domain.usecase.GetItemsUseCase
+import __PACKAGE__.testing.fakes.FakeItemRepository
+import kotlin.test.AfterTest
+import kotlin.test.BeforeTest
+import kotlin.test.Test
+import kotlin.test.assertEquals
+import kotlin.test.assertNotNull
+import kotlin.test.assertNull
+import kotlin.test.assertTrue
+import kotlinx.coroutines.Dispatchers
+import kotlinx.coroutines.ExperimentalCoroutinesApi
+import kotlinx.coroutines.test.StandardTestDispatcher
+import kotlinx.coroutines.test.resetMain
+import kotlinx.coroutines.test.runTest
+import kotlinx.coroutines.test.setMain
+
+/**
+ * The exemplar ViewModel test — the pattern every generated ViewModel test follows:
+ *  - Arrange/Act/Assert with behavior-named backtick tests, one behavior per test.
+ *  - A [StandardTestDispatcher] installed as Main (viewModelScope launches on Main),
+ *    so coroutines run under the test scheduler's virtual time.
+ *  - Turbine (`state.test { … }`) for StateFlow assertions.
+ *  - Hand-written fakes from `testing/fakes` — never mocks.
+ */
+@OptIn(ExperimentalCoroutinesApi::class)
+class HomeViewModelTest {
+
+    private val dispatcher = StandardTestDispatcher()
+    private val repository = FakeItemRepository()
+
+    @BeforeTest
+    fun setUp() {
+        Dispatchers.setMain(dispatcher)
+    }
+
+    @AfterTest
+    fun tearDown() {
+        Dispatchers.resetMain()
+    }
+
+    private fun viewModel() = HomeViewModel(GetItemsUseCase(repository))
+
+    // SPEC: HOME-01
+    @Test
+    fun `starts in loading state`() = runTest(dispatcher) {
+        viewModel().state.test {
+            assertTrue(awaitItem().isLoading, "initial state should be loading")
+        }
+    }
+
+    @Test
+    fun `emits items when repository succeeds`() = runTest(dispatcher) {
+        repository.items = listOf(Item(id = "1", title = "First", subtitle = "sub"))
+
+        viewModel().state.test {
+            assertTrue(awaitItem().isLoading)
+
+            val loaded = awaitItem()
+            assertEquals(false, loaded.isLoading)
+            assertEquals(listOf("First"), loaded.items.map { it.title })
+            assertNull(loaded.errorMessage)
+        }
+    }
+
+    @Test
+    fun `emits error message when repository fails`() = runTest(dispatcher) {
+        repository.shouldFail = true
+        repository.failureMessage = "network down"
+
+        viewModel().state.test {
+            assertTrue(awaitItem().isLoading)
+
+            val failed = awaitItem()
+            assertEquals(false, failed.isLoading)
+            assertTrue(failed.items.isEmpty())
+            assertEquals("network down", failed.errorMessage)
+        }
+    }
+
+    // SPEC: HOME-04
+    @Test
+    fun `reload after failure clears the error and loads items`() = runTest(dispatcher) {
+        repository.shouldFail = true
+        val viewModel = viewModel()
+
+        viewModel.state.test {
+            assertTrue(awaitItem().isLoading)
+            assertNotNull(awaitItem().errorMessage, "first load should fail")
+
+            repository.shouldFail = false
+            repository.items = listOf(Item(id = "1", title = "Recovered", subtitle = "sub"))
+            viewModel.load()
+
+            assertTrue(awaitItem().isLoading, "reload should show loading again")
+            val recovered = awaitItem()
+            assertNull(recovered.errorMessage)
+            assertEquals(listOf("Recovered"), recovered.items.map { it.title })
+        }
+    }
+}

package/template/composeApp/src/commonTest/kotlin/com/example/app/testing/fakes/FakeItemRepository.kt

@@ -0,0 +1,29 @@
+package __PACKAGE__.testing.fakes
+
+import __PACKAGE__.domain.model.Item
+import __PACKAGE__.domain.repository.ItemRepository
+
+/**
+ * Hand-written fake — the template's testing convention (no mocking frameworks: they are
+ * JVM-only in KMP, and interface-driven fakes keep the architecture honest).
+ *
+ * The pattern every fake follows:
+ *  - configurable behavior (`items`, `shouldFail`) so a test arranges its scenario,
+ *  - recorded interactions (`getItemsCallCount`) so a test can assert usage,
+ *  - implements the DOMAIN interface, never a concrete data source.
+ */
+class FakeItemRepository : ItemRepository {
+
+    var items: List<Item> = emptyList()
+    var shouldFail: Boolean = false
+    var failureMessage: String = "fake failure"
+
+    var getItemsCallCount: Int = 0
+        private set
+
+    override suspend fun getItems(): List<Item> {
+        getItemsCallCount++
+        if (shouldFail) throw IllegalStateException(failureMessage)
+        return items
+    }
+}

package/template/composeApp/src/desktopTest/kotlin/com/example/app/conformance/A11yConformanceTest.kt

@@ -0,0 +1,64 @@
+package __PACKAGE__.conformance
+
+import androidx.compose.material3.MaterialTheme
+import androidx.compose.ui.semantics.SemanticsActions
+import androidx.compose.ui.semantics.SemanticsNode
+import androidx.compose.ui.semantics.SemanticsProperties
+import androidx.compose.ui.semantics.getOrNull
+import androidx.compose.ui.test.ExperimentalTestApi
+import androidx.compose.ui.test.hasText
+import androidx.compose.ui.test.onRoot
+import androidx.compose.ui.test.runComposeUiTest
+import __PACKAGE__.domain.model.Item
+import __PACKAGE__.domain.usecase.GetItemsUseCase
+import __PACKAGE__.presentation.home.HomeScreen
+import __PACKAGE__.presentation.home.HomeViewModel
+import __PACKAGE__.testing.awaitNode
+import __PACKAGE__.testing.fakes.FakeItemRepository
+import kotlin.test.Test
+import kotlin.test.fail
+
+/**
+ * A11y gate — SPEC: SHELL-04. Every interactive node must be perceivable by assistive
+ * technology and automation: a testTag, text, or contentDescription. Runs on the JVM tier;
+ * the verify lane's `a11y` step. (Deeper checks — touch-target size, contrast — come with
+ * the live-tier inspector audit.)
+ */
+@OptIn(ExperimentalTestApi::class)
+class A11yConformanceTest {
+
+    // SPEC: SHELL-04
+    @Test
+    fun `every clickable on Home is perceivable`() = runComposeUiTest {
+        val repository = FakeItemRepository().apply {
+            items = listOf(Item(id = "1", title = "A11y row", subtitle = "sub"))
+        }
+        setContent {
+            MaterialTheme {
+                HomeScreen(onItemClick = {}, viewModel = HomeViewModel(GetItemsUseCase(repository)))
+            }
+        }
+        awaitNode(hasText("A11y row"))
+
+        val offenders = mutableListOf<String>()
+        fun walk(node: SemanticsNode) {
+            val clickable = node.config.getOrNull(SemanticsActions.OnClick) != null
+            if (clickable) {
+                val perceivable =
+                    node.config.getOrNull(SemanticsProperties.TestTag) != null ||
+                        !node.config.getOrNull(SemanticsProperties.Text).isNullOrEmpty() ||
+                        !node.config.getOrNull(SemanticsProperties.ContentDescription).isNullOrEmpty() ||
+                        node.children.any { !it.config.getOrNull(SemanticsProperties.Text).isNullOrEmpty() }
+                if (!perceivable) offenders += "node@${node.id} (bounds=${node.boundsInRoot})"
+            }
+            node.children.forEach(::walk)
+        }
+        walk(onRoot(useUnmergedTree = true).fetchSemanticsNode())
+
+        if (offenders.isNotEmpty()) fail(
+            "[SHELL-04] Interactive nodes without testTag/text/contentDescription:\n  " +
+                offenders.joinToString("\n  ") +
+                "\n  Fix: give each clickable a testTag or visible text/contentDescription.",
+        )
+    }
+}

package/template/composeApp/src/desktopTest/kotlin/com/example/app/conformance/ArchitectureConformanceTest.kt

@@ -0,0 +1,143 @@
+package __PACKAGE__.conformance
+
+import java.io.File
+import kotlin.test.Test
+import kotlin.test.fail
+
+/**
+ * The conformance gates — `specs/app-base.spec.md`'s ARCH clauses as executable checks.
+ * These enforce the architecture mechanically: an AI (or human) that drifts from the
+ * contract gets a named clause violation with the offending files, not a style nit.
+ *
+ * Deliberately dependency-free (plain source scanning) rather than Konsist: the template's
+ * moat is a frozen, lockstep-safe version set, and Konsist would add a kotlin-compiler
+ * pin to track. Swap in Konsist if you want richer queries — keep the clause ids.
+ *
+ * Runs on the JVM tier (`:composeApp:desktopTest`), invoked by the verify lane's
+ * `conformance` step.
+ */
+class ArchitectureConformanceTest {
+
+    private val commonMain = File("src/commonMain/kotlin")
+    private val commonTest = File("src/commonTest/kotlin")
+
+    private fun sources(root: File): List<File> =
+        root.walkTopDown().filter { it.isFile && it.extension == "kt" }.toList()
+
+    private fun imports(file: File): List<String> =
+        file.readLines().filter { it.trimStart().startsWith("import ") }.map { it.trim() }
+
+    private fun under(file: File, segment: String): Boolean =
+        file.path.replace(File.separatorChar, '/').contains("/$segment/")
+
+    private fun violation(clause: String, rule: String, offenders: List<String>, fix: String): String =
+        "[$clause] $rule\n  Offending: ${offenders.joinToString("\n             ")}\n  Fix: $fix"
+
+    // SPEC: ARCH-01
+    @Test
+    fun `ARCH-01 presentation never imports the data layer`() {
+        val offenders = sources(commonMain)
+            .filter { under(it, "presentation") }
+            .filter { file -> imports(file).any { it.startsWith("import __PACKAGE__.data.") } }
+            .map { it.path }
+        if (offenders.isNotEmpty()) fail(
+            violation(
+                "ARCH-01", "presentation depends on domain only — it never imports the data layer.",
+                offenders,
+                "depend on a domain interface (domain/repository) and let di/ wire the data implementation.",
+            )
+        )
+    }
+
+    // SPEC: ARCH-02
+    @Test
+    fun `ARCH-02 domain is pure - no app layers, no frameworks`() {
+        val banned = listOf(
+            "import __PACKAGE__.presentation.", "import __PACKAGE__.data.", "import __PACKAGE__.di.",
+            "import androidx.compose.", "import org.koin.",
+        )
+        val offenders = sources(commonMain)
+            .filter { under(it, "domain") }
+            .filter { file -> imports(file).any { imp -> banned.any { imp.startsWith(it) } } }
+            .map { it.path }
+        if (offenders.isNotEmpty()) fail(
+            violation(
+                "ARCH-02", "domain imports nothing app-internal and no UI/DI frameworks.",
+                offenders,
+                "move framework-touching code out to presentation/data; domain stays pure Kotlin.",
+            )
+        )
+    }
+
+    // SPEC: ARCH-03
+    @Test
+    fun `ARCH-03 every ViewModel has a test`() {
+        val testNames = sources(commonTest).map { it.name }.toSet()
+        val offenders = sources(commonMain)
+            .filter { it.name.endsWith("ViewModel.kt") }
+            .filterNot { "${it.name.removeSuffix(".kt")}Test.kt" in testNames }
+            .map { it.path }
+        if (offenders.isNotEmpty()) fail(
+            violation(
+                "ARCH-03", "every ViewModel has a corresponding *ViewModelTest in commonTest.",
+                offenders,
+                "add the test mirroring HomeViewModelTest (Turbine + fakes; loading/success/error paths).",
+            )
+        )
+    }
+
+    // SPEC: ARCH-04
+    @Test
+    fun `ARCH-04 every Screen composable declares a testTag`() {
+        val offenders = sources(commonMain)
+            .filter { it.name != "Screen.kt" && it.name.endsWith("Screen.kt") }
+            .filterNot { under(it, "components") || under(it, "navigation") }
+            .filterNot { it.readText().contains("testTag") }
+            .map { it.path }
+        if (offenders.isNotEmpty()) fail(
+            violation(
+                "ARCH-04", "every screen is automation-reachable: *Screen files declare at least one testTag.",
+                offenders,
+                "add Modifier.semantics { testTag = \"<feature>_<element>\" } to the screen's key nodes.",
+            )
+        )
+    }
+
+    // SPEC: ARCH-05
+    @Test
+    fun `ARCH-05 no hardcoded Color literals outside the theme`() {
+        val colorLiteral = Regex("""Color\(0x""")
+        val offenders = sources(commonMain)
+            .filterNot { under(it, "theme") }
+            .filter { colorLiteral.containsMatchIn(it.readText()) }
+            .map { it.path }
+        if (offenders.isNotEmpty()) fail(
+            violation(
+                "ARCH-05", "design colors come from the token catalog, never Color(0x…) literals.",
+                offenders,
+                "add/use a token in presentation/theme instead of the literal.",
+            )
+        )
+    }
+
+    // SPEC: SHELL-03
+    @Test
+    fun `SHELL-03 insets are owned by BaseScreen - screens never touch inset APIs`() {
+        val insetApi = Regex(
+            "WindowInsets|safeDrawingPadding|safeContentPadding|systemBarsPadding|" +
+                "statusBarsPadding|navigationBarsPadding|imePadding"
+        )
+        val offenders = sources(commonMain)
+            .filterNot { under(it, "components") }
+            .filterNot { under(it, "navigation") }
+            .filter { insetApi.containsMatchIn(it.readText()) }
+            .map { it.path }
+        if (offenders.isNotEmpty()) fail(
+            violation(
+                "SHELL-03", "window insets are solved once, in BaseScreen/AppShell — screens never call inset APIs directly.",
+                offenders,
+                "compose your content inside BaseScreen (or the shell) and remove the direct inset call.",
+            )
+        )
+    }
+}

package/template/composeApp/src/desktopTest/kotlin/com/example/app/presentation/home/HomeGoldenTreeTest.kt

@@ -0,0 +1,78 @@
+package __PACKAGE__.presentation.home
+
+import androidx.compose.material3.MaterialTheme
+import androidx.compose.ui.test.ExperimentalTestApi
+import androidx.compose.ui.test.hasText
+import androidx.compose.ui.test.onRoot
+import androidx.compose.ui.test.runComposeUiTest
+import __PACKAGE__.domain.model.Item
+import __PACKAGE__.domain.usecase.GetItemsUseCase
+import __PACKAGE__.testing.StructuralTree
+import __PACKAGE__.testing.awaitNode
+import __PACKAGE__.testing.fakes.FakeItemRepository
+import java.io.File
+import kotlin.test.Test
+import kotlin.test.fail
+
+/**
+ * Golden-tree structural baseline — SPEC: HOME-06.
+ *
+ * Renders Home headlessly with FIXED fake data and diffs the semantics structure against the
+ * committed baseline (`qa/golden/home.json`). No pixels, no flake: a failure means the
+ * screen's STRUCTURE changed.
+ *
+ * Unintended drift → fix your change. Intended drift → regenerate the baseline explicitly
+ * and declare it in your summary/PR:
+ *
+ *   UPDATE_GOLDEN=1 ./gradlew :composeApp:desktopTest --tests "*GoldenTree*"
+ */
+@OptIn(ExperimentalTestApi::class)
+class HomeGoldenTreeTest {
+
+    private val baseline = File("../qa/golden/home.json")
+
+    // Fixed dataset — golden renders must be deterministic; never use live/random data here.
+    private val goldenItems = listOf(
+        Item(id = "1", title = "Golden first", subtitle = "Structural baseline row one"),
+        Item(id = "2", title = "Golden second", subtitle = "Structural baseline row two"),
+    )
+
+    // SPEC: HOME-06
+    @Test
+    fun `home structure matches the committed golden tree`() = runComposeUiTest {
+        val repository = FakeItemRepository().apply { items = goldenItems }
+
+        setContent {
+            MaterialTheme {
+                HomeScreen(onItemClick = {}, viewModel = HomeViewModel(GetItemsUseCase(repository)))
+            }
+        }
+        awaitNode(hasText("Golden first"))
+
+        val rendered = StructuralTree.serialize(onRoot(useUnmergedTree = true).fetchSemanticsNode())
+
+        if (System.getenv("UPDATE_GOLDEN") == "1") {
+            baseline.parentFile.mkdirs()
+            baseline.writeText(rendered)
+            return@runComposeUiTest
+        }
+
+        if (!baseline.exists()) fail(
+            "[HOME-06] Golden baseline missing (qa/golden/home.json). " +
+                "Generate it explicitly: UPDATE_GOLDEN=1 ./gradlew :composeApp:desktopTest --tests \"*GoldenTree*\"",
+        )
+
+        val expected = baseline.readText()
+        if (rendered != expected) {
+            val diffAt = rendered.zip(expected).indexOfFirst { (a, b) -> a != b }
+                .let { if (it == -1) minOf(rendered.length, expected.length) else it }
+            fail(
+                "[HOME-06] Home's rendered structure drifted from qa/golden/home.json (first diff at char $diffAt).\n" +
+                    "If this drift is UNINTENDED: fix your change.\n" +
+                    "If it is the intended change: regenerate with UPDATE_GOLDEN=1 and declare it.\n" +
+                    "--- rendered (excerpt) ---\n${rendered.substring(maxOf(0, diffAt - 120), minOf(rendered.length, diffAt + 240))}\n" +
+                    "--- baseline (excerpt) ---\n${expected.substring(maxOf(0, diffAt - 120), minOf(expected.length, diffAt + 240))}",
+            )
+        }
+    }
+}

package/template/composeApp/src/desktopTest/kotlin/com/example/app/presentation/home/HomeScreenTest.kt

@@ -0,0 +1,77 @@
+package __PACKAGE__.presentation.home
+
+import androidx.compose.material3.MaterialTheme
+import androidx.compose.ui.test.ExperimentalTestApi
+import androidx.compose.ui.test.assertCountEquals
+import androidx.compose.ui.test.hasTestTag
+import androidx.compose.ui.test.hasText
+import androidx.compose.ui.test.onAllNodesWithText
+import androidx.compose.ui.test.onFirst
+import androidx.compose.ui.test.onNodeWithTag
+import androidx.compose.ui.test.performClick
+import androidx.compose.ui.test.runComposeUiTest
+import __PACKAGE__.domain.model.Item
+import __PACKAGE__.domain.usecase.GetItemsUseCase
+import __PACKAGE__.testing.awaitNode
+import __PACKAGE__.testing.fakes.FakeItemRepository
+import kotlin.test.Test
+
+/**
+ * Durable screen tests — first-party Compose UI Test, spec-cited, testTag selectors.
+ * These are the long-lived regression layer (TESTING-ARCHITECTURE tier 3b): each test
+ * verifies a clause from `specs/home.spec.md`, one behavior per test.
+ */
+@OptIn(ExperimentalTestApi::class)
+class HomeScreenTest {
+
+    private val repository = FakeItemRepository()
+
+    private fun viewModel() = HomeViewModel(GetItemsUseCase(repository))
+
+    // SPEC: HOME-02
+    @Test
+    fun `renders loaded items with title and subtitle`() = runComposeUiTest {
+        repository.items = listOf(
+            Item(id = "1", title = "First title", subtitle = "First subtitle"),
+            Item(id = "2", title = "Second title", subtitle = "Second subtitle"),
+        )
+
+        setContent {
+            MaterialTheme { HomeScreen(onItemClick = {}, viewModel = viewModel()) }
+        }
+
+        awaitNode(hasText("First title"))
+        onAllNodesWithText("Second subtitle").assertCountEquals(1)
+        onNodeWithTag("home_title", useUnmergedTree = true).assertExists()
+    }
+
+    // SPEC: HOME-03
+    @Test
+    fun `shows the error message when loading fails`() = runComposeUiTest {
+        repository.shouldFail = true
+        repository.failureMessage = "network down"
+
+        setContent {
+            MaterialTheme { HomeScreen(onItemClick = {}, viewModel = viewModel()) }
+        }
+
+        awaitNode(hasTestTag("home_error"))
+        onAllNodesWithText("network down").assertCountEquals(1)
+    }
+
+    // SPEC: HOME-05
+    @Test
+    fun `tapping an item reports its id for navigation`() = runComposeUiTest {
+        repository.items = listOf(Item(id = "item-42", title = "Tap me", subtitle = "sub"))
+        var clickedId: String? = null
+
+        setContent {
+            MaterialTheme { HomeScreen(onItemClick = { clickedId = it }, viewModel = viewModel()) }
+        }
+
+        awaitNode(hasText("Tap me"))
+        onAllNodesWithText("Tap me").onFirst().performClick()
+        waitUntil(timeoutMillis = 5_000) { clickedId != null }
+        kotlin.test.assertEquals("item-42", clickedId)
+    }
+}

package/template/composeApp/src/desktopTest/kotlin/com/example/app/presentation/navigation/AppShellTest.kt

@@ -0,0 +1,79 @@
+package __PACKAGE__.presentation.navigation
+
+import androidx.compose.material.icons.Icons
+import androidx.compose.material.icons.filled.Home
+import androidx.compose.material3.MaterialTheme
+import androidx.compose.material3.Text
+import androidx.compose.ui.Modifier
+import androidx.compose.ui.semantics.semantics
+import androidx.compose.ui.semantics.testTag
+import androidx.compose.ui.test.ExperimentalTestApi
+import androidx.compose.ui.test.assertIsDisplayed
+import androidx.compose.ui.test.hasTestTag
+import androidx.compose.ui.test.onNodeWithTag
+import androidx.compose.ui.test.onNodeWithText
+import androidx.compose.ui.test.performClick
+import androidx.compose.ui.test.runComposeUiTest
+import __PACKAGE__.testing.awaitNode
+import kotlin.test.Test
+
+/**
+ * Durable shell tests — first-party Compose UI Test, spec-cited, testTag selectors.
+ * Verifies `specs/app-base.spec.md`'s SHELL-01/SHELL-02 clauses directly against [AppShell]
+ * with trivial in-test tabs (no ViewModel/DI wiring — the shell itself is under test), so no
+ * scaffold flag combination (in particular `--no-e2e`, which removes qa/e2e) orphans these
+ * clauses. `qa/e2e/smoke.yaml` remains the on-device citation of the same clauses — being
+ * cited by both a durable JVM test and the E2E flow is expected, not redundant.
+ */
+@OptIn(ExperimentalTestApi::class)
+class AppShellTest {
+
+    private fun testTabs(): List<AppTab> = listOf(
+        AppTab(
+            label = "Tab One",
+            icon = Icons.Filled.Home,
+            content = {
+                Text("Tab one content", modifier = Modifier.semantics { testTag = "tab_one_content" })
+            },
+        ),
+        AppTab(
+            label = "Tab Two",
+            icon = Icons.Filled.Home,
+            content = {
+                Text("Tab two content", modifier = Modifier.semantics { testTag = "tab_two_content" })
+            },
+        ),
+    )
+
+    // SPEC: SHELL-01
+    @Test
+    fun `first tab renders inside the shell with the bottom nav visible on launch`() = runComposeUiTest {
+        setContent {
+            MaterialTheme { AppShell(tabs = testTabs()) }
+        }
+
+        awaitNode(hasTestTag("tab_one_content"))
+        onNodeWithTag("tab_one_content").assertIsDisplayed()
+        onNodeWithTag("app_bottom_nav").assertIsDisplayed()
+    }
+
+    // SPEC: SHELL-02
+    @Test
+    fun `tapping another tab renders its screen and keeps the bottom nav visible`() = runComposeUiTest {
+        setContent {
+            MaterialTheme { AppShell(tabs = testTabs()) }
+        }
+
+        awaitNode(hasTestTag("tab_one_content"))
+
+        onNodeWithText("Tab Two").performClick()
+        awaitNode(hasTestTag("tab_two_content"))
+        onNodeWithTag("tab_two_content").assertIsDisplayed()
+        onNodeWithTag("app_bottom_nav").assertIsDisplayed()
+
+        onNodeWithText("Tab One").performClick()
+        awaitNode(hasTestTag("tab_one_content"))
+        onNodeWithTag("tab_one_content").assertIsDisplayed()
+        onNodeWithTag("app_bottom_nav").assertIsDisplayed()
+    }
+}

package/template/composeApp/src/desktopTest/kotlin/com/example/app/testing/ComposeTestExt.kt

@@ -0,0 +1,16 @@
+package __PACKAGE__.testing
+
+import androidx.compose.ui.test.ComposeUiTest
+import androidx.compose.ui.test.ExperimentalTestApi
+import androidx.compose.ui.test.SemanticsMatcher
+
+/**
+ * Waits until at least one node matches. Portable helper (the upstream
+ * waitUntilAtLeastOneExists is not exposed on this CMP version's desktop test artifact).
+ */
+@OptIn(ExperimentalTestApi::class)
+fun ComposeUiTest.awaitNode(matcher: SemanticsMatcher, timeoutMillis: Long = 5_000) {
+    waitUntil(timeoutMillis = timeoutMillis) {
+        onAllNodes(matcher).fetchSemanticsNodes().isNotEmpty()
+    }
+}