# Tara Mobile E2E Tests

End-to-end tests for the Tara mobile application using
[Maestro](https://maestro.mobile.dev/).

## Prerequisites

1. **Install Maestro CLI**:

   ```bash
   # macOS
   brew install mobile-dev-inc/tap/maestro

   # Linux/Windows (via curl)
   curl -Ls "https://get.maestro.mobile.dev" | bash
   ```

2. **Start the development server**:

   ```bash
   cd apps/tara/mobile
   pnpm start
   ```

3. **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

```
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

1. **Use multiple selectors**: Combine `text`, `id`, and `accessibilityLabel`
   with `anyOf` for robustness
2. **Add timeouts**: Use `extendedWaitUntil` for async operations
3. **Mark optional elements**: Use `optional: true` for elements that may not
   always appear
4. **Reuse common flows**: Import shared setup with `runFlow`
5. **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 `testID` or `accessibilityLabel` in 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
