tools-only Mobile App Topology
This file documents the mobile application configuration for the /mobileappfix workflow.
IMPORTANT: Fill this out before using /mobileappfix. The workflow needs this configuration to run tests and verify fixes.
App Configuration
Basic Info
| Property | Value |
|---|---|
| App Name | [YOUR_APP_NAME] |
| App ID (iOS) | [com.example.yourapp] |
| App ID (Android) | [com.example.yourapp] |
| Framework | React Native / Expo SDK 52 |
| Bundler | Metro |
Project Paths
| Path | Purpose |
|---|---|
| Project Root | [/path/to/your/project] |
| Maestro Tests | .maestro/ |
| iOS Native | ios/ |
| Android Native | android/ |
Development Commands
Daily Development
# Start Metro bundler
npm start
# Run on iOS Simulator
npm run ios
# Run on Android Emulator
npm run android
# Clear cache and restart
npm run start:clear
Native Builds
# Regenerate native directories (after app.config.js changes)
npm run prebuild:clean
cd ios && pod install && cd ..
# Fresh iOS build
npm run ios
# Fresh Android build
npm run android
EAS Cloud Builds
# Development build (for Maestro testing)
eas build --profile development --platform ios
# Preview build (internal testing)
eas build --profile preview
# Production build
eas build --profile production
Maestro E2E Testing
Configuration
# .maestro/config.yaml
appId: [com.example.yourapp]
timeout: 60000
screenshots: .maestro/screenshots
env:
TEST_USER_EMAIL: [test@example.com]
TEST_USER_PASSWORD: ${MAESTRO_TEST_PASSWORD}
Test Commands
# Full test suite
npm run e2e
# or: maestro test .maestro/suite.yaml
# Quick smoke test (login flow)
maestro test .maestro/journeys/J2-returning-user-login.yaml
# Record new test
npm run e2e:record
# Debug element detection
maestro hierarchy
Test Organization
| Category | Path | Purpose |
|---|---|---|
| Journeys | .maestro/journeys/ |
User journey tests (J1-J5) |
| Negative | .maestro/negative/ |
Error path tests (N1-N3) |
| Flows | .maestro/flows/ |
Reusable helper flows |
| Audit | .maestro/audit/ |
Visual UI audits |
Key Journeys
| Journey | File | Tests |
|---|---|---|
| J1 | J1-new-user-onboarding.yaml |
Register → Onboarding → App |
| J2 | J2-returning-user-login.yaml |
Login → Main App (smoke) |
| J3 | J3-main-app-navigation.yaml |
Navigate all tabs/screens |
| J4 | J4-exercise-completion.yaml |
Complete exercise session |
| J5 | J5-profile-settings.yaml |
Profile & settings |
Simulator/Emulator Setup
iOS Simulators
# List available simulators
xcrun simctl list devices available
# Boot specific simulator
xcrun simctl boot "iPhone 15 Pro"
# Open Simulator app
open -a Simulator
# Install app on booted simulator
xcrun simctl install booted ./path/to/app.app
Android Emulators
# Set environment (add to ~/.zshrc)
export ANDROID_HOME=$HOME/Library/Android/sdk
export PATH=$PATH:$ANDROID_HOME/emulator:$ANDROID_HOME/platform-tools
# List available AVDs
$ANDROID_HOME/emulator/emulator -list-avds
# Start emulator
$ANDROID_HOME/emulator/emulator -avd Medium_Phone_API_36 &
# Check connected devices
adb devices
Available AVDs (This System)
Medium_Phone_API_36Pixel_Tablet
Log Sources
Metro Bundler
# Logs visible in terminal where npm start runs
# Look for:
# - JavaScript errors (red text)
# - Bundle build failures
# - Transform errors
iOS Console Logs
# Open Console.app
open -a Console
# Filter by app name: "[your-app-name]"
# Look for:
# - Native crashes
# - Memory warnings
# - Network errors
Android Logcat
# All logs from device
adb logcat
# React Native specific
adb logcat -s ReactNative:V ReactNativeJS:V
# Crashes only
adb logcat -s AndroidRuntime:E
Backend Dependencies
API Endpoints
| Service | URL | Purpose |
|---|---|---|
| Supabase | <project>.supabase.co |
Auth, Database |
| Backend API | [https://api.example.com] |
Backend service |
Health Checks
# Supabase health (via app)
# Check network tab in React Native Debugger
# Backend health
curl -sf [https://api.example.com/health]
TestID Conventions
| Pattern | Example | Usage |
|---|---|---|
{screen}_screen |
profile_screen |
Screen containers |
{screen}_{element} |
profile_settings_button |
Interactive elements |
auth_{action}_{element} |
auth_login_submit_button |
Auth screens |
stepping_stone_{id}_{status} |
stepping_stone_abc_current |
Dynamic elements |
Critical Paths to Verify
After any fix, these flows must work:
- Login Flow: Open app → Login → See stepping stones
- Exercise Start: Tap current stone → Select training → Start exercise
- Profile Access: Navigate to profile tab → See user stats
- Settings: Open settings → Logout works
Environment Variables
Required for E2E testing:
# .env (gitignored)
TEST_USER_EMAIL=[test@example.com]
TEST_USER_PASSWORD=<password>
EXPO_PUBLIC_IS_TEST_MODE=true
# Export for Maestro
export MAESTRO_TEST_PASSWORD=<password>
Notes
- Expo dev builds don't support
clearState: truein Maestro - Always use
clearState: falsefor development testing - TestIDs may not work if wrapped in TouchableWithoutFeedback (add
accessible={false}) - iOS builds require Xcode 15+ with iOS 17+ SDK
- Android builds require Android SDK 34+
Expo Dev Client + Maestro: Auto-Connect Solution
Issue: The Expo Dev Client launcher has a merged accessibility tree that makes automated taps unreliable.
Solution: Use deep linking to auto-connect to Metro, bypassing the launcher UI.
Recommended: Use run-e2e.sh Script
# Auto-connects to Metro and runs tests
./scripts/run-e2e.sh .maestro/journeys/J2-returning-user-login.yaml
The script:
- Starts Metro if not running
- Boots iOS simulator if needed
- Launches app via deep link:
exp+[your-app-slug]://expo-development-client/?url=http://localhost:8081 - Runs Maestro tests
Manual Alternative
# Start Metro
npm start &
# Wait for Metro, then connect app via deep link
xcrun simctl openurl booted "exp+[your-app-slug]://expo-development-client/?url=http://localhost:8081"
# Run tests (app already connected)
maestro test .maestro/journeys/J2-returning-user-login.yaml
Deep Link Format
exp+{app-slug}://expo-development-client/?url={metro-url}
Example: exp+[your-app-slug]://expo-development-client/?url=http://localhost:8081