reis-mobile 0.6.0 → 0.7.0

package/skills/mobile-test/SKILL.md

@@ -22,14 +22,27 @@ Detect the stack first (the router result, or `pubspec.yaml`, Gradle files, the
 
 A cross-platform app with native code (`android/`, `ios/`, native modules) uses the native reference for that code.
 
-## 2. Follow the project before this skill
+## 2. Bind the request to the project
 
-Read the existing tests, test dependencies, helpers and folder layout before writing anything. A project that already uses mockito, XCTest or Detox gets tests in that style unless the user asks to migrate; consistency beats preference.
+Use the [shared project brief](../../docs/agent-context.md). Reuse a supplied brief and fill only missing evidence; do not repeat discovery performed by the calling command or agent. Read the relevant implementation, nearest tests, fixtures, dependency injection and test configuration before proposing a test.
+
+Infer the operation from the request:
+
+| Operation | Work |
+|---|---|
+| Run | Execute the requested existing suite or the smallest relevant suite; report failures without silently changing application behavior. |
+| Write | Add tests for the named behavior using the current framework and fixtures. |
+| Fix | Reproduce the failing test, distinguish a product defect from a test defect, and preserve the intended assertion while fixing the cause. |
+| Audit | Inspect existing tests and give evidence-backed gaps; do not add dependencies or rewrite suites as part of a review. |
+
+For each selected behavior, record an actual **source path and symbol → input/trigger → observable result → dependency seam → test path → execution command**. Name the repository, service, state owner or native bridge involved instead of returning a generic testing checklist. An unknown product rule is a gap to surface, not a fixture to invent.
+
+A project that already uses mockito, XCTest or Detox gets tests in that style unless the user asks to migrate. Use its existing build variant, test target and helper conventions. Examples in references illustrate a technique; their application symbols and command placeholders must be replaced with repository evidence.
 
 ## 3. What to test, in order of value
 
 1. **Business rules** — use cases, view models, reducers, mappers — with their edge cases: empty data, missing fields, boundary values.
-2. **State changes** — the exact sequence of states on success and on failure.
+2. **State changes** — observable states and transitions on success and failure; require an exact sequence only when the contract guarantees every emission. A conflating state holder may skip intermediate values.
 3. **Error handling** — a failing data source becomes the expected user-facing state.
 4. **Critical UI states** — loading, error, empty, content, and what the user can do in each.
 5. **End-to-end flows** — only the few journeys that must never break (sign-in, purchase), because they are slow and fragile.
@@ -44,7 +57,7 @@ Most tests belong at the top of this list. If a behavior can be verified without
 
 ## 5. Determinism
 
-- No real network, disk, clock, randomness or sleeps. Inject a clock and dispatchers or schedulers; use the platform's virtual time or fake async.
+- Isolate network, time and randomness in unit tests. Integration tests may use a temporary database or filesystem when that is the behavior under test; create and clean it per test. Avoid production services and arbitrary sleeps. Inject a clock and dispatchers or schedulers; use the platform's virtual time or fake async.
 - Each test sets up its own state; order must not matter.
 - A flaky test is a bug. Find the race (unawaited async work, animations, shared state) instead of adding retries or longer timeouts.
 
@@ -56,8 +69,10 @@ Most tests belong at the top of this list. If a behavior can be verified without
 
 ## 7. Run before reporting
 
-Run the tests you wrote with the command in the platform reference and fix until they pass. Never weaken an assertion or delete a test to make the suite green. Instrumented, UI and end-to-end tests need a device, emulator or simulator: ask before starting one.
+Resolve the command from the project's scripts, Gradle tasks, Xcode scheme/test plan or CI before execution; do not run an example with guessed names. Run the relevant existing test first when reproducing a failure, then run the changed tests and their affected suite. Never weaken an assertion or delete a test to make the suite green.
+
+For instrumented, UI and end-to-end tests, discover available devices and the project's runner policy. Use a compatible local emulator or simulator when authorized by the task; do not erase its data or silently switch to a physical device. If the SDK, runtime or destination is unavailable, report the exact blocker and the resolved command that remains unrun. A build, a skipped test or an empty filtered run is not a passing test: inspect the test count and results.
 
 ## Output
 
-When writing tests, report the files created, what each test covers and the command that ran them. When auditing, list the files reviewed, fragile or flaky tests with the reason, and untested scenarios prioritized by risk, each with a concrete suggestion.
+Report the operation, source symbols and behaviors covered, files changed, exact command and working directory, executed test counts/result and any report artifact. Separate passed, failed, skipped and blocked checks. When auditing, link each gap or flaky test to a concrete path, the missing assertion or race, and the smallest useful test to add.

package/skills/mobile-test/references/android.md

@@ -1,83 +1,95 @@
 # Testing native Android apps
 
-For setting up a test stack from scratch (dependencies, UI tests, screenshot tests, Hilt), follow [android/setup/GUIDE.md](android/setup/GUIDE.md). This file covers writing tests in an existing setup.
+Use this reference for Kotlin/Java tests, including native Android modules inside Flutter or React Native apps. For a new test setup, use [android/setup/GUIDE.md](android/setup/GUIDE.md); first inspect the current module rather than installing its entire example stack.
 
-## Detect the setup
+## Resolve the module and test environment
 
-- Test dependencies in the module build files and `gradle/libs.versions.toml`: JUnit 4 or 5, `kotlinx-coroutines-test`, Turbine, MockK or Mockito-Kotlin, Truth or AssertJ, Robolectric, `androidx.compose.ui:ui-test-junit4`, Espresso, `hilt-android-testing`.
-- Source sets: **local tests** in `src/test` run on the JVM; **instrumented tests** in `src/androidTest` need a device or emulator.
-- Existing helpers: a `MainDispatcherRule`, fakes, a `:core:testing` module, custom test runners.
+1. Read `settings.gradle` or `settings.gradle.kts` to find the owning module. Inspect its build file, convention plugins, version catalog and CI invocation for the active build type and product flavors.
+2. Locate the subject and its nearest test. Identify the real constructor, injected repository/dispatcher, observable state, test fixture and source set. `src/test` normally holds JVM tests; `src/androidTest` holds device tests. Check variant-specific and custom source sets before choosing a destination file.
+3. Reuse the installed JUnit engine, assertion library, coroutine test helpers and mocking tool. Do not switch a JUnit 4 suite to JUnit 5 because an example uses another runner.
+4. For instrumentation, inspect `testInstrumentationRunner`, runner arguments, AndroidX test dependencies and any Hilt runner. `AndroidJUnitRunner` is the standard runner; preserve a configured custom subclass. Espresso needs the module's `androidTestImplementation` setup, including `espresso-core` and the test runner. Resolve versions from the project instead of copying documentation versions. See [Espresso setup](https://developer.android.com/training/testing/espresso/setup).
 
-## Local unit tests: ViewModels, coroutines and Flow
+From the directory containing the wrapper, discover available tasks before choosing one:
 
-```kotlin
-class MainDispatcherRule(val dispatcher: TestDispatcher = UnconfinedTestDispatcher()) : TestWatcher() {
-    override fun starting(description: Description) = Dispatchers.setMain(dispatcher)
-    override fun finished(description: Description) = Dispatchers.resetMain()
-}
+```bash
+./gradlew projects
+./gradlew '<module-path>:tasks' --all
+adb devices -l
+```
 
-class LoginViewModelTest {
-    @get:Rule val mainDispatcherRule = MainDispatcherRule()
+Replace `<module-path>` with the discovered Gradle path, including its leading colon. The task listing determines the unit, connected or managed-device task for the requested variant. Do not assume `:app`, `Debug` or a connected device exists.
 
-    private val repository = FakeAuthRepository()
+## Select the smallest test that proves the behavior
 
-    @Test
-    fun `emits success when credentials are valid`() = runTest {
-        repository.nextResult = Result.success(fakeUser)
-        val viewModel = LoginViewModel(repository)
+| Subject | Test and concrete observation |
+|---|---|
+| Mapper, validator, use case | JVM test with inputs and expected domain result, including a meaningful boundary or failure case. |
+| ViewModel or Flow producer | JVM coroutine test with the project's dispatcher rule; trigger the action and observe the state or emitted event. |
+| Stateless composable | Existing Compose test harness; interact with a semantic node and assert the resulting state or callback effect. |
+| Android Views screen | Espresso instrumentation test against real view IDs and a controlled dependency seam. |
+| DAO, worker or persistent store | Existing Room/WorkManager/DataStore harness; assert stored values, constraints or work outcome and clean resources. |
 
-        viewModel.uiState.test {                       // Turbine
-            assertEquals(LoginUiState.Idle, awaitItem())
-            viewModel.submit("user@example.com", "secret")
-            assertEquals(LoginUiState.Loading, awaitItem())
-            assertEquals(LoginUiState.Success(fakeUser), awaitItem())
-        }
-    }
-}
-```
+## Coroutines and Flow
 
-- `runTest` skips `delay` with virtual time; `advanceUntilIdle()` and `advanceTimeBy()` control it with a `StandardTestDispatcher`.
-- Inject dispatchers into repositories and use cases instead of hardcoding `Dispatchers.IO`; tests pass the test dispatcher.
-- Code that uses `viewModelScope` needs `Dispatchers.Main` replaced (the rule above).
-- The names above are illustrative; use the project's classes.
+- Reuse the project's `MainDispatcherRule` or equivalent when the subject uses `viewModelScope`. Share the test scheduler across injected dispatchers; hardcoded `Dispatchers.IO` work is not controlled by virtual time.
+- Use `runTest` and the project's Flow helper, such as Turbine. Start collection before the action when the contract requires observing emissions; launch long-lived collectors in a scope cancelled at test completion.
+- A `StateFlow` can conflate rapid updates. Assert its stable final state unless intermediate states are part of the contract; to test loading, pause a fake dependency until the assertion has observed that state, then complete it. Do not assume a synchronous fake guarantees `Idle → Loading → Success` emissions.
+- With `StandardTestDispatcher`, explicitly drive scheduled work where necessary using `runCurrent`, `advanceTimeBy` or `advanceUntilIdle`. Do not replace a race with a real delay. See [testing Kotlin coroutines](https://developer.android.com/kotlin/coroutines/test) and [testing flows](https://developer.android.com/kotlin/flow/test).
 
-## Compose UI tests
+## Espresso: action, synchronization and assertion
 
-```kotlin
-class LoginScreenTest {
-    @get:Rule val composeRule = createComposeRule()
+Bind the test to a real Activity/Fragment, view IDs, launch state and expected result. Reuse an existing fake backend or dependency override before launch. Use the app's actual validation rule or response; checking that a button exists does not prove submitting the form works.
 
-    @Test
-    fun showsErrorWhenLoginFails() {
-        composeRule.setContent { LoginScreen(state = LoginUiState.Error("Invalid credentials"), onSubmit = {}) }
+This illustrative body assumes the inspected app rejects an empty form and exposes these IDs/resources. Replace them with the actual screen's symbols and use the project's test imports and runner:
 
-        composeRule.onNodeWithText("Invalid credentials").assertIsDisplayed()
-        composeRule.onNodeWithText("Sign in").performClick()
+```kotlin
+@Test
+fun submittingEmptyFormShowsRequiredEmailError() {
+    ActivityScenario.launch(SignInActivity::class.java).use {
+        onView(withId(R.id.email)).perform(clearText(), closeSoftKeyboard())
+        onView(withId(R.id.submit)).perform(click())
+        onView(withId(R.id.email_error))
+            .check(matches(withText(R.string.email_required)))
+            .check(matches(isDisplayed()))
     }
 }
 ```
 
-- Test stateless composables with state passed in; they need no ViewModel or DI.
-- Prefer finding nodes by text or content description; add `Modifier.testTag` only where there is no user-visible handle.
-- These tests are instrumented by default; with Robolectric configured, they can run as local tests.
+`ActivityScenario` is `androidx.test.core.app.ActivityScenario`; the other calls come from Espresso's `Espresso`, `ViewActions`, `ViewMatchers` and `ViewAssertions`. Match resource imports to the owning module. `use` closes the activity after the assertion, including on failure. See [testing activities](https://developer.android.com/guide/components/activities/testing).
+
+For asynchronous work outside Espresso's built-in synchronization:
+
+1. Identify the operation that makes the assertion race. Use the app's existing `IdlingResource`, or connect one to that operation's actual lifecycle. An unconnected counter cannot synchronize anything.
+2. Register it through `IdlingRegistry.getInstance().register(resource)` before the first Espresso interaction that needs it. If startup work is under test, arrange the dependency and registration before launching the activity; an auto-launch rule can run before `@Before`.
+3. With `CountingIdlingResource`, increment before scheduling work and decrement on every completion path, including errors and cancellation. Finish relevant state updates before marking the operation idle.
+4. Unregister through `IdlingRegistry.getInstance().unregister(resource)` in `@After` or guaranteed cleanup. Restore dependency overrides as well. Avoid `Thread.sleep`, unbounded waits and increasing timeouts to hide a race.
+
+Keep idling resources free of Activity/View references. See [Espresso idling resources](https://developer.android.com/training/testing/espresso/idling-resource).
 
-## Views, Espresso and Hilt
+## Compose, Hilt and storage
 
-- Espresso: `onView(withId(R.id.submit)).perform(click())`, `check(matches(isDisplayed()))`. Disable animations on test devices, and use idling resources for background work instead of sleeps.
-- Hilt: annotate the test with `@HiltAndroidTest`, add `HiltAndroidRule`, use a custom runner that sets `HiltTestApplication`, and replace modules with `@TestInstallIn`. Details in [android/setup/references/android/training/dependency-injection/hilt-testing.md](android/setup/references/android/training/dependency-injection/hilt-testing.md).
+- Compose: use the installed `createComposeRule` or `createAndroidComposeRule` harness. Assert after an interaction, including a callback value when testing a stateless composable. Prefer semantics such as text/content description, using a test tag when a node otherwise cannot be identified. Run through the project's configured instrumentation or Robolectric setup.
+- Hilt: preserve `@HiltAndroidTest`, `HiltAndroidRule`, custom runner and module replacement conventions; install fakes before the subject is created. See [the Hilt test guide](android/setup/references/android/training/dependency-injection/hilt-testing.md).
+- Room: use an isolated database for DAO behavior and `MigrationTestHelper` for migrations. WorkManager: use the existing `work-testing` harness. DataStore: use a temporary location and cancel its scope during teardown. Do not replace a persistence test with a mock of the persistence operation.
 
-## Other components
+## Run and inspect evidence
 
-- **Room**: test DAOs against `Room.inMemoryDatabaseBuilder`; test migrations with `MigrationTestHelper` in instrumented tests.
-- **WorkManager**: `work-testing` provides test drivers to run workers synchronously.
-- **DataStore**: create it in a temporary folder per test.
+The following commands are templates. Replace task paths and class names with values found above; use `--tests` only for a Gradle JVM test task:
 
-## Commands
+```bash
+./gradlew '<unit-test-task-path>' --tests '<fully-qualified-test-class>'
+./gradlew '<instrumentation-test-task-path>'
+```
+
+For one instrumentation class or method, reuse the project's runner-argument convention. Alternatively, after building and installing the matching app/test APKs, inspect the installed instrumentation component and select it explicitly:
 
 ```bash
-./gradlew :app:testDebugUnitTest                               # local tests of one module
-./gradlew :app:testDebugUnitTest --tests '*LoginViewModelTest'
-./gradlew :app:connectedDebugAndroidTest                       # instrumented tests, needs a device or emulator
+adb -s '<serial>' shell pm list instrumentation
+adb -s '<serial>' shell am instrument -w \
+  -e class '<fully-qualified-test-class>#<test-method>' \
+  '<test-package>/<runner-class>'
 ```
 
-For coverage, enable `enableUnitTestCoverage` / `enableAndroidTestCoverage` on the build type and run the coverage report task the Android Gradle plugin creates for it; check the task name for the project's AGP version.
+Do not infer the test package from the app namespace. Read the runner output and test counts: no matching tests is not success. Gradle local reports live under the module's `build/reports/tests` and XML results under `build/test-results`; connected-test output is under `build/reports/androidTests/connected` and `build/outputs/androidTest-results/connected`. Report the actual generated path and selected device. See [command-line testing](https://developer.android.com/studio/test/command-line).
+
+For coverage, inspect the module's AGP version and existing configuration, then discover the generated report task. Do not add a coverage plugin or change toolchain versions just to execute an existing test suite.

package/skills/mobile-test/references/ios.md

@@ -1,79 +1,102 @@
 # Testing native iOS apps
 
-## Detect the setup
+Use this reference for Swift/Objective-C tests and native iOS modules inside Flutter or React Native apps. Keep XCTest, Swift Testing and XCUITest in the roles already established by the target.
 
-- Framework: **Swift Testing** (`import Testing`, `@Test`, `#expect`) or **XCTest** (`XCTestCase`). Swift Testing needs Xcode 16 or later; both can live in the same test target, so follow what the file or target already uses.
-- Test targets, test plans and schemes in the Xcode project, or test targets in `Package.swift`.
-- Whether unit tests run inside a host app (the app target launches) or as a logic test bundle.
-- Existing doubles and fixtures; snapshot testing only if the project already has a library for it.
+## Resolve the container, target and destination
 
-## Unit tests with Swift Testing
+1. Find the owning `.xcworkspace`, `.xcodeproj` or `Package.swift`, and read CI's test invocation. Use the app's workspace when that is how its dependencies are integrated; do not select a dependency's internal project/workspace.
+2. Inspect the scheme's Test action and `.xctestplan` files. Identify the unit/UI test target, test host, source membership, exclusions and configurations. A new file outside the test target or a target excluded by the plan contributes no tests.
+3. Inspect `import XCTest` / `XCTestCase` versus `import Testing` / `@Test`, the toolchain version and existing helpers. Preserve the framework used by the nearest tests. Swift Testing is available with Xcode 16 and later; it can coexist with XCTest in a test target. See [adding tests to Xcode projects](https://developer.apple.com/documentation/xcode/adding-tests-to-your-xcode-project).
+4. Map the real source symbol to its protocol dependencies, actor isolation, input and observable result. Read the existing fixture builders rather than inventing application entities.
 
-```swift
-import Testing
-@testable import App
+These are command templates: replace every `<...>` from repository or tool output. Use `-project '<path>.xcodeproj'` instead of `-workspace '<path>.xcworkspace'` throughout when the project has no relevant workspace.
 
-@MainActor
-struct LoginViewModelTests {
-    @Test func emitsSuccessWhenCredentialsAreValid() async {
-        let viewModel = LoginViewModel(authService: FakeAuthService(result: .success(.fixture)))
+```bash
+xcodebuild -list -workspace '<workspace-path>.xcworkspace'
+xcodebuild -workspace '<workspace-path>.xcworkspace' -scheme '<scheme>' -showTestPlans
+xcodebuild -workspace '<workspace-path>.xcworkspace' -scheme '<scheme>' -showdestinations
+xcrun simctl list devices available
+```
 
-        await viewModel.submit(email: "user@example.com", password: "secret")
+Choose a compatible destination listed for that scheme, using its simulator ID to avoid ambiguous device names. A listed simulator may still need to boot. Preserve the project's destination policy and avoid selecting a physical device implicitly. If there is no compatible runtime, record the blocker. See [Xcode command-line discovery](https://developer.apple.com/library/archive/technotes/tn2339/_index.html) and [test plans](https://developer.apple.com/documentation/xcode/organizing-tests-to-improve-feedback).
 
-        #expect(viewModel.state == .success(.fixture))
-    }
+## XCTest: choose the async mechanism that matches the subject
+
+- Synchronous function: invoke it and assert its returned value or observable state with `XCTAssert...`; use `try XCTUnwrap` for values required by subsequent steps.
+- `async` function: use a `test...` method marked `async` or `async throws`, await the operation, then assert. Apply `@MainActor` when the subject requires it; do not add an unawaited `Task` inside a synchronous test.
+- Callback, delegate or publisher: create an expectation before triggering work, assert the callback's result, fulfill it, and wait for completion. For an async XCTest method use `await fulfillment(of:timeout:)` when supported by the project's toolchain; a synchronous method can use `wait(for:timeout:)`. Avoid a blocking wait inside an async test.
+- If the method only starts background work, awaiting that method alone may not prove completion. Observe the completion callback/state transition rather than immediately asserting a value that races.
 
-    @Test(arguments: ["", "no-at-sign", "a@"])
-    func rejectsInvalidEmails(_ email: String) {
-        #expect(EmailValidator.isValid(email) == false)
+See [asynchronous XCTest tests](https://developer.apple.com/documentation/xctest/asynchronous-tests-and-expectations) and [async expectation fulfillment](https://developer.apple.com/documentation/xctest/xctestcase/fulfillment%28of%3Atimeout%3Aenforceorder%3A%29).
+
+The following method illustrates a callback test. `repository`, `cachedOrder` and `loadCachedOrder` stand for an inspected project fixture and API, not generated application types. Arrange an isolated repository fixture that contains the expected order before invoking it:
+
+```swift
+func testLoadsPreviouslySavedOrder() async {
+    let loaded = expectation(description: "Cached order is delivered")
+
+    repository.loadCachedOrder { result in
+        switch result {
+        case .success(let order):
+            XCTAssertEqual(order, cachedOrder)
+        case .failure(let error):
+            XCTFail("Expected the saved order, received \(error)")
+        }
+        loaded.fulfill()
     }
+
+    await fulfillment(of: [loaded], timeout: 1.0)
 }
 ```
 
-- `#expect` records a failure and continues; `try #require(...)` stops the test (use it to unwrap optionals the rest of the test depends on).
-- `#expect(throws: SomeError.self) { try parser.parse(data) }` checks thrown errors.
-- Parameterized tests (`arguments:`) replace copy-pasted test methods.
-- Suites are plain types; setup goes in `init`, teardown in `deinit`.
+Choose a bounded timeout appropriate to the isolated operation. Keep captured values compatible with the API's actor/Sendable requirements. Fulfill on both success and failure so assertion failures do not become unexplained timeouts; clean subscriptions and tasks during teardown.
 
-## Unit tests with XCTest
+## Swift Testing and dependency isolation
 
-```swift
-final class LoginViewModelTests: XCTestCase {
-    @MainActor
-    func testEmitsSuccessWhenCredentialsAreValid() async {
-        let viewModel = LoginViewModel(authService: FakeAuthService(result: .success(.fixture)))
+- Follow the target's current `@Test`, `#expect` and `#require` conventions. Parameterize genuinely identical behavior with different inputs instead of duplicating bodies. Preserve the suite's isolation and parallelization assumptions; do not migrate XCTest UI tests to Swift Testing.
+- Inject the app's existing protocol-based services, clock and persistence boundary. When testing URL loading, a custom `URLProtocol` belongs on an isolated `URLSessionConfiguration`, with a deterministic handler scoped to that test.
+- Use a dedicated `UserDefaults` suite or temporary persistence store with cleanup. Keep real Keychain/network access out of unit tests unless those integrations are explicitly the subject and have an isolated test setup. Reset fixtures in setup/teardown; avoid global state shared by parallel tests.
 
-        await viewModel.submit(email: "user@example.com", password: "secret")
+## XCUITest: launch state, interaction, observable result
 
-        XCTAssertEqual(viewModel.state, .success(.fixture))
-    }
-}
-```
+Use the UI test target with `XCTestCase` and `XCUIApplication`. It runs separately from the app, so an in-process fake in the test does not replace the app's services. Reuse launch arguments/environment that the app actually reads to select a deterministic fixture; do not invent flags such as `--uitesting` and assume they work.
 
-- Use `async` test methods and `await` the work instead of `XCTestExpectation` with timeouts where possible.
-- Methods must start with `test`; `setUp`/`tearDown` (or their `async throws` variants) reset state.
+Locate elements through identifiers found in SwiftUI's `.accessibilityIdentifier(...)` or UIKit's `accessibilityIdentifier`. Wait for the relevant state using `waitForExistence(timeout:)` rather than sleeping. Element existence alone does not guarantee it is enabled or hittable; inspect those states when the action requires them. See [XCUIElement](https://developer.apple.com/documentation/xcuiautomation/xcuielement).
 
-## Test doubles and determinism
+Illustrative method: replace the identifiers and expected error with the inspected screen's values. This scenario assumes an empty form is submitted and the app shows a required-field error:
 
-- Inject dependencies through protocols in initializers; fakes return canned results and record calls when the test needs them.
-- No real network: fake the API client, or register a custom `URLProtocol` on the test `URLSessionConfiguration`.
-- No shared `UserDefaults.standard` or real Keychain: inject a store, or use `UserDefaults(suiteName:)` removed after each test.
-- Inject a clock or date provider instead of reading `Date()` in code under test.
+```swift
+func testSubmittingEmptyFormShowsRequiredEmailError() {
+    let app = XCUIApplication()
+    app.launch()
+    defer { app.terminate() }
+
+    let submit = app.buttons["signIn.submit"]
+    XCTAssertTrue(submit.waitForExistence(timeout: 5))
+    XCTAssertTrue(submit.isEnabled)
+    XCTAssertTrue(submit.isHittable)
+    submit.tap()
+
+    let error = app.staticTexts["signIn.emailError"]
+    XCTAssertTrue(error.waitForExistence(timeout: 5))
+    XCTAssertEqual(error.label, "Email is required")
+}
+```
 
-## UI tests (XCUITest)
+Set the app's existing fixture arguments/environment before `launch()` when needed to reach a fresh form. The post-tap assertion proves the behavior; a launch-only smoke test does not. For network-driven flows, make the app consume a controlled response and assert the resulting screen/state.
 
-- Find elements by accessibility identifier: set `.accessibilityIdentifier("loginButton")` in SwiftUI or `accessibilityIdentifier` in UIKit.
-- Launch into a known state with `app.launchArguments` / `app.launchEnvironment` read by the app (for example to use fake services or skip onboarding).
-- Wait with `waitForExistence(timeout:)` on the element, never with `sleep`.
-- Keep UI tests to critical flows; they are slow and the first to go flaky.
+## Run the selected tests and inspect the result
 
-## Commands
+Use actual names found above. The `-only-testing` identifier uses the test target name, then the XCTest class and optionally method. Select a plan only when the scheme has that plan; omit `-testPlan` for schemes without one:
 
 ```bash
-xcrun simctl list devices available            # pick a simulator that exists on this machine
-xcodebuild test -scheme App -destination 'platform=iOS Simulator,name=<Device>'
-xcodebuild test -scheme App -destination 'platform=iOS Simulator,name=<Device>' -only-testing:AppTests/LoginViewModelTests
-xcodebuild test -scheme App -destination '...' -enableCodeCoverage YES -resultBundlePath TestResults.xcresult
-xcrun xccov view --report TestResults.xcresult
-swift test                                      # Swift packages
+xcodebuild test -workspace '<workspace-path>.xcworkspace' \
+  -scheme '<scheme>' -testPlan '<test-plan>' \
+  -destination 'platform=iOS Simulator,id=<simulator-id>' \
+  '-only-testing:<test-target>/<test-class>' \
+  -resultBundlePath '<new-result-path>.xcresult'
 ```
+
+Use a new result-bundle path per run, then inspect executed tests, failures and skips. A successful build or zero matching tests is not a passing suite. Preserve the `.xcresult` path in the report. For coverage, add `-enableCodeCoverage YES` when requested and inspect the bundle with `xcrun xccov view --report '<result-path>.xcresult'`; verify command support with the installed Xcode. See [running tests and interpreting results](https://developer.apple.com/documentation/xcode/running-tests-and-interpreting-results).
+
+For a Swift package whose tests support the host platform, run `swift test` from the package directory, using its supported filter when narrowing scope. iOS-only package tests still need the app/Xcode scheme and compatible simulator; `swift test` on macOS does not supply an iOS runtime.