# Maestro UI Flows

This directory's sibling `.maestro/` holds cross-platform UI tests driven by
[Maestro](https://maestro.mobile.dev/). The same YAML files run on both
Android and iOS because every selector uses an `id:` that resolves to an
`AccessibilityIds` test tag (Kotlin) or `AccessibilityIdentifiers` test tag
(Swift) — the two namespaces are kept in verbatim parity.

## Install

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

Verify:

```bash
maestro --version
```

## Run the suite

With an Android emulator running (API 34+) or an iOS simulator booted and
the HoneyDue debug build installed:

```bash
# All flows (reads .maestro/config.yaml)
maestro test .maestro/flows/

# Single flow
maestro test .maestro/flows/01-login.yaml
```

Override environment variables (see `09-notification-deeplink.yaml`,
`10-widget-complete.yaml`):

```bash
maestro test -e TASK_ID=123e4567-e89b-12d3-a456-426614174000 \
  .maestro/flows/09-notification-deeplink.yaml
```

## Available flows

| # | File | What it exercises |
|---|---|---|
| 01 | `01-login.yaml` | Email+password sign-in, land on tabs |
| 02 | `02-register.yaml` | New-user registration → verification stub |
| 03 | `03-create-residence.yaml` | Add a residence end-to-end |
| 04 | `04-create-task.yaml` | Add a task end-to-end |
| 05 | `05-complete-task.yaml` | Open task → complete → submit |
| 06 | `06-join-residence.yaml` | Join existing residence by share code |
| 07 | `07-upload-document.yaml` | Add a document |
| 08 | `08-theme-switch.yaml` | Profile → theme picker → Ocean |
| 09 | `09-notification-deeplink.yaml` | `honeydue://task/<id>` cold-launch |
| 10 | `10-widget-complete.yaml` | Android widget complete-intent (no-op on iOS) |

## Tips

- `maestro studio` opens an interactive inspector that lets you record
  taps/typing and see every `testTag` the app exposes. Easiest way to
  build new flows.
- `maestro test --debug-output /tmp/maestro` emits screenshots + logs for
  each step — check there first when CI fails.
- Pre-seed a test user and fixture data via the API before running the
  suite; the flows assume `testuser@example.com / TestPassword123!` exists.
- Keep new flows in sync with `AccessibilityIds.kt` (Kotlin) and
  `AccessibilityIdentifiers.swift` (iOS) — these are the single source of
  truth for every `id:` selector.