# Maestro E2E — Local Setup (Phase A)

Phase A: lokales CLI, 0 Cost, kein Cloud-Account.
Phase B (post-TestFlight): Maestro Cloud fuer CI-Reports + Multi-Device-Parallel — Entscheidung steht aus.

---

## 1. Maestro CLI installieren

```bash
curl -Ls "https://get.maestro.mobile.dev" | bash
```

Danach Shell neu starten oder:

```bash
export PATH="$PATH:$HOME/.maestro/bin"
```

Verify:

```bash
maestro --version
# Erwarteter Output: Maestro CLI 1.x.x
```

---

## 2. App auf Device / Simulator bauen

Maestro benoetigt eine laufende App-Installation. Expo Dev-Client oder Production-Build.

### iOS Simulator

```bash
# Im rebreak-native Verzeichnis:
cd apps/rebreak-native

# Dev-Build auf Standard-Simulator (erster verfuegbarer):
pnpm exec expo run:ios

# Spezifischer Simulator (Name aus "xcrun simctl list devices"):
pnpm exec expo run:ios --device "iPhone 15"
```

Alternativ via konsolidiertem Dev-Script:

```bash
# Vollbuild auf iPhone via USB:
bash apps/rebreak-native/dev.sh ios

# WiFi-Modus (kein Kabel, Metro über LAN):
bash apps/rebreak-native/dev.sh ios --wifi

# Schneller JS-Reload ohne Native-Rebuild:
bash apps/rebreak-native/dev.sh ios --no-build
```

### Android Emulator

Emulator muss vorher gestartet sein (`Android Studio -> Device Manager`).

```bash
bash apps/rebreak-native/install-android.sh
```

Oder direkt:

```bash
pnpm exec expo run:android
```

### Bundle-ID

`org.rebreak.app` (iOS + Android identisch) — steht so in `app.config.ts` und in den
Flow-Headern als `appId: org.rebreak.app`.

---

## 3. Env-Vars setzen

Flows benoetigen Test-User-Credentials. **Nie** hardcoden — immer als Env-Vars uebergeben.

### Option A: direktes `--env` Flag

```bash
maestro test \
  --env=E2E_TEST_USER=admin \
  --env=E2E_TEST_PASSWORD=<Passwort aus Infisical> \
  apps/rebreak-native/.maestro/auth/email-signin.yaml
```

### Option B: Infisical Wrapper

```bash
infisical run -- maestro test apps/rebreak-native/.maestro/auth/email-signin.yaml
```

Voraussetzung: Infisical-Projekt hat `E2E_TEST_USER` und `E2E_TEST_PASSWORD` als Secrets.

Variablen die Flows erwarten:

| Var                  | Beschreibung                                          |
|----------------------|-------------------------------------------------------|
| `E2E_TEST_USER`      | Username-Teil der E-Mail (ohne @rebreak.internal)     |
| `E2E_TEST_PASSWORD`  | Passwort des Test-Users auf Staging                   |

Wichtig: Der Backend-Server haengt `@rebreak.internal` automatisch an den Username.
In den Flows steht deshalb `${E2E_TEST_USER}@rebreak.internal` als E-Mail-Input.

### Test-Account (aktueller Stand)

- **`admin@rebreak.org`** — email-basierter Account, Passwort in Infisical als `E2E_TEST_PASSWORD`
  Dann: `E2E_TEST_USER=admin`
- **`charioanouar@gmail.com`** — Google OAuth only, kein Passwort → kann NICHT fuer Maestro-Email-Login genutzt werden
- **`claude-android-test@rebreak.internal`** — dedizierter CI-Test-Account (Erstellung via Service-Role noetig wenn nicht vorhanden)

Empfehlung: `admin`-Account fuer lokale Flow-Tests nutzen.

---

## 4. Flows ausfuehren

### Einen einzelnen Flow

```bash
maestro test apps/rebreak-native/.maestro/auth/signin.yaml \
  --env=E2E_TEST_USER=claude-android-test \
  --env=E2E_TEST_PASSWORD=<passwort>
```

### Alle Flows (sequenziell)

```bash
maestro test apps/rebreak-native/.maestro/
```

Mit ENV-Datei-Uebergabe:

```bash
maestro test \
  --env=E2E_TEST_USER=claude-android-test \
  --env=E2E_TEST_PASSWORD=<passwort> \
  apps/rebreak-native/.maestro/
```

### Spezifische Subdirectory

```bash
maestro test apps/rebreak-native/.maestro/auth/
```

---

## 5. Flow-Entwicklung: Maestro Studio

Visual Flow-Builder im Browser — zeigt Screen-Snapshot + verfuegbare Elemente.

```bash
# App muss laufen auf Device/Simulator:
maestro studio
```

Browser oeffnet auf `http://localhost:9999`. Elemente anklicken, YAML auto-generieren,
dann in `.maestro/<area>/<scenario>.yaml` speichern.

---

## 6. Tipps fuer stabile Flows

**Warte auf Animationen:**
```yaml
- waitForAnimationToEnd:
    timeout: 4000
```
Splash-Screen, Screen-Transitions und API-Calls brauchen Zeit.
Faustregel: nach `launchApp` min. 5000ms, nach Navigation 2000-4000ms.

**Flaky Tests debuggen:**
```bash
# Output-Logs waehrend Run:
maestro test --format junit --output report.xml apps/rebreak-native/.maestro/auth/signin.yaml

# Screenshot bei Fehler: Maestro macht automatisch einen Screenshot im Fehlerfall.
# Findet sich unter ~/.maestro/tests/<timestamp>/
```

**Selektoren — Prioritaet:**
1. `id: "<testID>"` — stabielste Option. RN-Prop: `testID="mein-btn"`.
2. `text: "..."` — nur fuer statische, locale-unabhaengige Strings.
3. `point: "x%, y%"` — letzter Ausweg, bricht bei Screen-Size-Aenderungen.
4. Niemals `text:` fuer i18n-Strings (`t('...')`-Output) wenn Locale-Wechsel moeglich.

**Device angeben (Multi-Device):**
```bash
maestro test --device=<DEVICE_ID> apps/rebreak-native/.maestro/
# Device-IDs: `adb devices` (Android) / `xcrun simctl list` (iOS)
```

---

## 7. App-State vor Test-Lauf

`clearState: true` in jedem Flow-Header stellt sicher dass:
- Auth-Session geleert ist
- Kein persistierter State (MMKV / AsyncStorage) den Flow stoert
- Jeder Flow von einem definierten Ausgangspunkt startet (Login-Screen)

Test-User muss **vorab** auf dem Staging-Backend existieren:
- Username: `claude-android-test`
- E-Mail: `claude-android-test@rebreak.internal`
- Account: email-confirmed, kein Admin-Flag
- Erstellung: nur per Service-Role-Key + `auth.admin.createUser({ email_confirm: true })`
  (nicht im Flow selbst — Test-User ist persistent)

---

## 8. Flow-Uebersicht

### Bestehende Flows (Phase A)

| Flow | Was wird geprueft | Stabil? |
|---|---|---|
| `auth/signin.yaml` | App startet, Login via Email+Pw, Home-Feed sichtbar | Ja (text-selektoren) |
| `auth/email-signin.yaml` | Identisch — aktuelle Version mit besseren Kommentaren | Ja |
| `urge/start-session.yaml` | SOS im Dropdown erreichbar, Lyra-Screen laedt | Koordinaten-Fallback |
| `urge/sos-flow.yaml` | SOS → Lyra-Chat → "Atemübung" Chip → BreathingDrawer | LLM-abhaengig |
| `community/post.yaml` | ComposeCard, Text-Input, Submit | Ja |
| `community/create-post.yaml` | Identisch — aktuelle Version | Ja |
| `profile/view-profile.yaml` | Profil-Navigation, ProfileHeader, StatsBar | Koordinaten-Fallback |
| `profile/view-and-edit.yaml` | Profil → Edit → Nickname aendern → Speichern | Koordinaten-Fallback |
| `profile/demographics.yaml` | DemographicsAccordion toggle, WheelPicker oeffnet | Text-selektoren |
| `settings/dark-theme.yaml` | Settings → Theme → Dunkel | Native-Menu-Limitation |

### Neue Flows (Phase A+, kritische Coverage)

| Flow | Prioritaet | Was wird geprueft | Stabil? | Blocker |
|---|---|---|---|---|
| `onboarding/new-user-streak-guard.yaml` | HOCH | Streak-Counter nach Login nicht 0 — Regressions-Guard fuer current_days-Bug | Ja | Kein frischer-Account-Test ohne reset-Mechanismus |
| `sos/crisis-flow.yaml` | HOECHSTE | SOS-Navigation + Lyra antwortet + Atemübung erreichbar | LLM-abhaengig | Avatar-Tap Koordinaten-Fallback |
| `blocker/activation-smoke.yaml` | HOCH | Blocker-Tab erreichbar, Protection Card + URL-Filter-Layer sichtbar | Ja | Activation-Step selbst nicht testbar (System-Dialog) |
| `calls/incoming-call-screen.yaml` | MITTEL | Chat-Tab laedt, DM-Liste zeigt keine Phantom-Call-Artefakte | Teilweise | Echter Incoming-Call braucht 2 Devices (Phase B) |
| `dm/send-message.yaml` | HOCH | DM oeffnen, Nachricht senden, Bubble erscheint | Abhaengig von E2E_TEST_PEER_NICKNAME | Peer-Nickname-Env-Var noetig |
| `dm/realtime-receive.yaml` | MITTEL | Realtime-Empfang — Nachricht erscheint ohne Reload | SCAFFOLD ONLY | Braucht externen Trigger oder 2-Device-Setup |
| `stress/dm-scroll-performance.yaml` | MITTEL | DM-Scroll auf A50, kein ANR/Crash nach 8 Swipes | Geraete-abhaengig | Braucht 50+ Messages in Test-DM |
| `stress/rapid-post-submit.yaml` | MITTEL | 3 Posts hintereinander, ComposeCard resettet jedes Mal | Ja | Posts landen in Staging-DB — manuelles Cleanup |

**Koordinaten-Fallback** = Flow nutzt `point: "x%, y%"` fuer Avatar-Button, weil kein `testID` vorhanden.
Bricht wenn Header-Layout geaendert wird. Betroffene testIDs: `TODO_TESTIDS.md`.

**Native-Menu-Limitation** = `@react-native-menu/menu` (UIMenu auf iOS) kann Maestro moeglicherweise
nicht interagieren — Flow koennte an diesem Step haengen. Wenn `settings/dark-theme.yaml` immer
an "Systemstandard" haengt: bekanntes Problem, kein Maestro-Bug, sondern iOS-Restriktion.

**SCAFFOLD ONLY** = Flow ist dokumentiertes Intent, laeuft aber nicht im CI durch ohne
externe Infrastruktur (2. Device, API-Trigger). Nicht in den default Run aufnehmen bis Phase B.

---

## 9. Neue Env-Vars fuer Phase-A+-Flows

Bestehende Vars (`E2E_TEST_USER`, `E2E_TEST_PASSWORD`) werden weiterhin genutzt.
Zusaetzlich noetig fuer neue Flows:

| Var | Flow | Beschreibung |
|---|---|---|
| `E2E_TEST_PEER_NICKNAME` | `dm/send-message.yaml`, `dm/realtime-receive.yaml`, `stress/dm-scroll-performance.yaml` | Nickname des DM-Peers im Staging-Account des Test-Users (z.B. ein zweites CI-Test-Konto) |

Empfehlung: `claude-android-test` als Test-User + ein zweites Konto `claude-android-test-peer`
anlegen via Service-Role. Beide als DM-Kontakt seeden (ein manueller DM loest das).

---

## 10. Run-Befehle Phase A+

Nur stabile Flows (alles ausser SCAFFOLD ONLY):

```bash
maestro test \
  --env=E2E_TEST_USER=claude-android-test \
  --env=E2E_TEST_PASSWORD=<passwort> \
  --env=E2E_TEST_PEER_NICKNAME=<peer-nickname> \
  apps/rebreak-native/.maestro/onboarding/ \
  apps/rebreak-native/.maestro/sos/ \
  apps/rebreak-native/.maestro/blocker/ \
  apps/rebreak-native/.maestro/calls/ \
  apps/rebreak-native/.maestro/dm/send-message.yaml \
  apps/rebreak-native/.maestro/stress/rapid-post-submit.yaml
```

Stress-Tests separat (laenger, geraete-abhaengig):

```bash
maestro test \
  --env=E2E_TEST_USER=claude-android-test \
  --env=E2E_TEST_PASSWORD=<passwort> \
  --env=E2E_TEST_PEER_NICKNAME=<peer-nickname> \
  apps/rebreak-native/.maestro/stress/
```

---

## 11. Phase B — Maestro Cloud (Zukunft, post-TestFlight)

Was bei Cloud-Wechsel geaendert werden muss:

1. Maestro-Cloud-Account anlegen: `maestro cloud login`
2. CI-Run-Befehl aendern: `maestro cloud apps/rebreak-native/.maestro/`
3. ENV-Vars in CI-Secret-Store hinterlegen (GitHub Actions Secrets / Infisical CI-Integration)
4. Multi-Device-Matrix: `--device ios` / `--device android` separat schedulen
5. Report-URL aus Cloud-Output in PR-Kommentare posten (GitHub Actions Step)

Bis dahin: lokaler CLI reicht fuer Pre-Release-Smoke-Tests.
