SwiftUI/UIKit to Android: Automated UI & E2E Testing

Official Framework: Jetpack Compose UI Testing (ComposeTestRule / AndroidComposeTestRule Kotlin UI tests). Extension: .kt

1. Jetpack Compose UI Test Structure

When porting an iOS XCUITest user journey or view assertion, you Must generate a native Jetpack Compose UI test using createComposeRule() or createAndroidComposeRule<T>().

Core Elements:

  • @get:Rule val composeTestRule = createComposeRule() : Initializes the testing environment.
  • composeTestRule.setContent { ... } : Sets the composable hierarchy under test.
  • onNodeWithText("..."), onNodeWithTag("..."), onNodeWithContentDescription("...") : Semantics tree finders.
  • .performClick(), .performTextInput("..."), .performScrollTo() : User interaction actions.
  • .assertIsDisplayed(), .assertTextEquals("..."), .assertIsEnabled() : State assertions.

2. Mapping iOS XCUITest to Jetpack Compose UI Tests

A. Launch & Visual Parity

iOS Context (XCUITest): swift app.launch() XCTAssertTrue(app.staticTexts["Welcome"].exists)

Jetpack Compose UI Test (WelcomeScreenTest.kt): kotlin @Test fun validateWelcomeScreenParity() { composeTestRule.setContent { MyAppTheme { WelcomeScreen() } } composeTestRule.onNodeWithText("Welcome").assertIsDisplayed() }

B. Functional Interactions & User Flows

iOS Context (XCUITest): swift app.buttons["Login"].tap() app.textFields["Email"].typeText("user@example.com") XCTAssertTrue(app.staticTexts["Home Dashboard"].exists)

Jetpack Compose UI Test (LoginJourneyTest.kt): kotlin @Test fun validateLoginJourney() { composeTestRule.setContent { MyAppTheme { LoginScreen() } } composeTestRule.onNodeWithTag("email_field").performTextInput("user@example.com") composeTestRule.onNodeWithText("Login").performClick() composeTestRule.onNodeWithText("Home Dashboard").assertIsDisplayed() }

C. Verifying Layout & Vector Assets

iOS Context (XCUITest): Verify my_icon.imageset rendering and visibility.

Jetpack Compose UI Test (IconCompatibilityTest.kt): kotlin @Test fun validateVectorCompatibility() { composeTestRule.setContent { MyAppTheme { HomeScreen() } } composeTestRule.onNodeWithContentDescription("my_icon").assertIsDisplayed() }

3. Storage Convention

All generated UI and journey validation tests MUST be written to the standard Android Gradle instrumentation test directory: app/src/androidTest/java/

Unit tests for ViewModels, repositories, and business logic must be placed in: app/src/test/java/


4. Forced Build Verification & Command Matrix

The agent MUST execute and observe standard Gradle CLI commands to verify that the project builds and tests pass cleanly:

Verification Gate Command Passing Criterion
Debug Build Compilation ./gradlew :app:assembleDebug Exit code 0, 0 compiler errors
Unit & ViewModel Tests ./gradlew :app:testDebugUnitTest --continue Exit code 0, 0 failed test cases
Compose UI Instrumented Tests ./gradlew :app:connectedDebugAndroidTest Exit code 0 on connected emulator/device
Multi-Module Full Check ./gradlew check -x lint Exit code 0 across all modules

Compiler Error Recovery Loop

If ./gradlew assembleDebug or tests fail, the agent MUST follow this iterative recovery cycle:

  1. Parse Root Cause: Inspect standard error output for compiler errors, KSP code-generation failures (Room @Entity missing primary key, mismatched column types), or Hilt @Inject graph errors.
  2. Locate Conflicting Declarations: Check gradle/libs.versions.toml for version conflicts between Kotlin compiler and Compose compiler extension, or missing KSP plugins.
  3. Apply Targeted Fix: Edit the offending files without rewriting unaffected code.
  4. Re-run Command: Execute ./gradlew :app:assembleDebug. Never advance while the build is failing.

5. Prioritized Quality Gate & Refinement Triage

To prevent open-ended refinement loops and avoid token thrashing, apply this strict 3-tier triage hierarchy:

[Quality Gate Triage]
  │
  ├──► Priority #1: STABILITY (Crashes & Build Blockers)
  │      └── Unconditional loop: Fix all crashes and fatal exceptions until the app runs cleanly.
  │
  ├──► Priority #2: CORE FEATURE PARITY (Missing CUJs)
  │      └── Single (1x) refinement loop: Compare against `.migration/feature_specification.md`.
  │          If still failing after 1 loop, document as an open gap in `migration_walkthrough.md`.
  │
  └──► Priority #3: CRITICAL UI DEFECTS (Layout, Missing Assets, Edge-to-Edge)
         └── Single (1x) refinement loop: Fix broken margins/padding, jarring unstyled colors,
             or missing Drawables.
         └── RULE: Ignore minor typography/aesthetic nitpicks unless specified in migration brief.

6. Migration Walkthrough Specification (migration_walkthrough.md)

Upon completing migration and validation, the agent Must generate .migration/migration_walkthrough.md to provide full transparency:

# Migration Walkthrough: [App Name]

## 1. Migration Executive Summary
- **Source Platform**: iOS (SwiftUI / UIKit, Xcode [version])
- **Target Platform**: Android (Jetpack Compose, Kotlin [version], AGP [version])
- **Final Build Status**: `./gradlew assembleDebug` EXIT 0
- **Test Suite Status**: [X] unit tests passed, [Y] Compose UI tests passed

## 2. Subsystem Transformation Log
| Subsystem | iOS Source | Android Target | Verification Method | Status |
| :--- | :--- | :--- | :--- | :--- |
| Local Storage | Core Data `Model.xcdatamodeld` | Room Database + KSP | Unit test (`DaoTest.kt`) | VERIFIED |
| Network Layer | `URLSession` + Combine | Retrofit + Coroutines Flow | MockWebServer test | VERIFIED |
| UI Hierarchy | SwiftUI `ContentView` | Compose `MainScreen.kt` | `@Preview` + ComposeTestRule | VERIFIED |
| In-App Billing | StoreKit 2 `Product.purchase` | Google Play Billing Library 8 | Integration test | STUBBED |

## 3. Known API Gaps & Manual Action Items
- **Apple Sign-In**: Stubbed with `AuthenticationProviderStub.kt`. Action: Replace with Google Credential Manager.
- **Push Notification Token**: FCM receiver configured in `AndroidManifest.xml`. Action: Download `google-services.json` from Firebase Console.