End-to-end tests for the Tara mobile application using Maestro.
Prerequisites#
-
Install Maestro CLI:
bash# macOS brew install mobile-dev-inc/tap/maestro # Linux/Windows (via curl) curl -Ls "https://get.maestro.mobile.dev" | bash -
Start the development server:
bashcd apps/tara/mobile pnpm start -
Have an iOS Simulator or Android Emulator running, or a physical device connected.
Running Tests#
Run All E2E Tests#
bash
maestro test e2e/flows/
Run Smoke Tests (Quick Validation)#
bash
maestro test e2e/flows/smoke-suite.yaml
Run Full Regression Suite#
bash
maestro test e2e/flows/regression-suite.yaml
Run Specific Test Flow#
bash
maestro test e2e/flows/auth/login.yaml
Run Tests by Tag#
bash
# Run only authentication tests
maestro test e2e/flows/ --include-tags=auth
# Run smoke tests
maestro test e2e/flows/ --include-tags=smoke
Test Structure#
text
e2e/
├── config.yaml # Global configuration
├── flows/
│ ├── common/ # Reusable flows
│ │ ├── launch-app.yaml
│ │ └── clear-and-launch.yaml
│ ├── auth/ # Authentication tests
│ │ ├── login.yaml
│ │ ├── signup.yaml
│ │ └── logout.yaml
│ ├── meditation/ # Meditation browsing/playback
│ │ ├── browse.yaml
│ │ ├── play.yaml
│ │ ├── favorite.yaml
│ │ ├── library-actions.yaml
│ │ ├── resume-across-devices.yaml
│ │ ├── session-state.yaml
│ │ ├── save-resume.yaml
│ │ ├── audio-accessibility.yaml
│ │ └── session-state-save-resume-audio-suite.yaml
│ ├── timer/ # Timer functionality
│ │ ├── basic.yaml
│ │ └── settings.yaml
│ ├── offline/ # Offline mode
│ │ ├── download.yaml
│ │ ├── play-offline.yaml
│ │ └── manage-downloads.yaml
│ ├── notifications/ # Push notifications
│ │ ├── permission.yaml
│ │ ├── settings.yaml
│ │ └── reminder.yaml
│ ├── progress/ # Progress tracking
│ │ ├── view.yaml
│ │ └── achievements.yaml
│ ├── settings/ # App settings
│ │ ├── general.yaml
│ │ └── account.yaml
│ ├── onboarding/ # Onboarding flow
│ │ └── complete.yaml
│ ├── smoke-suite.yaml # Quick smoke tests
│ └── regression-suite.yaml # Full regression
└── README.md
Environment Variables#
Configure test credentials via environment variables:
bash
# Set test user credentials
export TEST_USER_EMAIL="e2e-test@tara.app"
export TEST_USER_PASSWORD="TestPassword123!"
export PREMIUM_USER_EMAIL="e2e-premium@tara.app"
export PREMIUM_USER_PASSWORD="PremiumPassword123!"
# Or pass inline
maestro test -e TEST_USER_EMAIL=test@example.com e2e/flows/auth/login.yaml
CI/CD Integration#
GitHub Actions#
yaml
name: Mobile E2E Tests
on: [push, pull_request]
jobs:
e2e-ios:
runs-on: macos-latest
steps:
- uses: actions/checkout@v4
- name: Install Maestro
run: brew install mobile-dev-inc/tap/maestro
- name: Start iOS Simulator
run: xcrun simctl boot "iPhone 15"
- name: Install dependencies
run: pnpm install
- name: Build app
run: pnpm --filter @tara/mobile expo build:ios -p simulator
- name: Run E2E tests
run: maestro test apps/tara/mobile/e2e/flows/smoke-suite.yaml
e2e-android:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Install Maestro
run: curl -Ls "https://get.maestro.mobile.dev" | bash
- name: Setup Android Emulator
uses: reactivecircus/android-emulator-runner@v2
with:
api-level: 33
script: |
pnpm install
pnpm --filter @tara/mobile expo build:android
maestro test apps/tara/mobile/e2e/flows/smoke-suite.yaml
Maestro Cloud (Recommended for CI)#
yaml
- uses: mobile-dev-inc/action-maestro-cloud@v1
with:
api-key: ${{ secrets.MAESTRO_CLOUD_API_KEY }}
app-file: app.apk
flows: apps/tara/mobile/e2e/flows/
Writing New Tests#
Basic Test Flow Structure#
yaml
appId: ${APP_ID}
tags:
- feature
- regression
---
# Test description
- runFlow: ../common/launch-app.yaml
# Navigate to feature
- tapOn:
text: 'Feature'
# Perform action
- tapOn:
id: 'action-button'
# Assert result
- assertVisible:
text: 'Success'
timeout: 5000
Best Practices#
- Use multiple selectors: Combine
text,id, andaccessibilityLabelwithanyOffor robustness - Add timeouts: Use
extendedWaitUntilfor async operations - Mark optional elements: Use
optional: truefor elements that may not always appear - Reuse common flows: Import shared setup with
runFlow - Tag tests appropriately: Use tags for filtering (
smoke,regression,feature)
Debugging#
Interactive Mode#
bash
maestro studio
Verbose Output#
bash
maestro test --debug e2e/flows/auth/login.yaml
Screenshots#
Configure automatic screenshots on failure in config.yaml:
yaml
defaults:
screenshotOnFailure: true
Test Coverage#
| Feature | Flow Files | Tests |
|---|---|---|
| Authentication | 3 | Login, Signup, Logout |
| Meditation | 10 | Browse, Play, Favorite, Library Actions, Resume, Session State, Save/Resume, Audio Accessibility |
| Timer | 3 | Basic, Settings, Breathing Tactile Pacing |
| Offline | 3 | Download, Play, Manage |
| Notifications | 3 | Permission, Settings, Reminder |
| Progress | 2 | View, Achievements |
| Settings | 2 | General, Account |
| Onboarding | 1 | Complete |
| Total | 27 |
Troubleshooting#
Tests failing to find elements#
- Verify element
testIDoraccessibilityLabelin React Native code - Use Maestro Studio to inspect element hierarchy
- Add more selector alternatives with
anyOf
Timeout errors#
- Increase timeout values in flows
- Check network conditions for API-dependent tests
- Verify app is actually running
Permission dialogs blocking tests#
- Handle system dialogs in
launch-app.yaml - Add permission handling steps before test actions