freshyo/docs/maestro-mcp-agent-guidelines.md
2026-10-13 19:10:27 +05:30

358 lines
16 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# Maestro MCP — agent field guide (Freshyo)
Hard-won, trial-and-error notes for driving this repo with the Maestro MCP
server (iOS simulator + Chromium) plus direct backend probes. Read this before
you start; it will save you an hour of the exact mistakes listed at the end.
Written after the 2026-10-10 E2E run (see
`docs/test reports/e2e-sanity-test-results-2026-10-10-1310.md` and
`docs/test reports/e2e-sanity-failed-cases-2026-10-10-1310.md`).
---
## 1. Environment map (verify, don't assume)
| Surface | How to reach it |
|---|---|
| Customer app (iOS) | bundle `com.freshyotrial.app`, device `B1F98A94-9733-46A6-9EB2-76F33C15240D` |
| Admin app (iOS) | bundle `in.freshyo.adminui` (same simulator) |
| Superadmin UI (web) | Chromium `http://localhost:4175` |
| Admin web | Chromium `http://localhost:4176` |
| Customer web | Chromium `http://localhost:4174/home` |
| Backend | `http://localhost:8787` — tRPC at `/api/trpc` |
| Metro | `:8081` (usually the user's own process — **do not start another**) |
| Maestro live view | `http://127.0.0.1:9999/` (surface this to the user when it appears) |
Discover devices with `tools.maestro.list_devices()`. On this machine the Android
emulator is usually **not connected**, so Android-only flows will not run.
`listapps` to confirm which bundles are installed:
```bash
xcrun simctl listapps <device_id> | grep -E 'CFBundleIdentifier|CFBundleDisplayName'
```
---
## 2. Golden rules
1. **Screenshot before every percentage tap.** Layout shifts between screens and
even between visits (e.g. the "DELIVER TO" bar sat at `10%` on one screen and
`18%` on another). Point taps are relative to the **current** screenshot.
2. **Prefer `id:` (testID) for inputs/buttons; use point taps for everything else.**
RN text nodes are frequently invisible to Maestro's accessibility tree.
3. **Never trust a "not visible" assertion on the RN app.** `assertVisible` /
`extendedWaitUntil` on `text:` or `id:` can pass/fail incorrectly. Verify with
a screenshot.
4. **When an invariant matters, probe the backend directly** (section 6). It is
faster, deterministic, and gives authoritative evidence.
5. **Always include `device_id`** in `run`. Prefer inline `yaml` for exploration.
6. **Budget time.** One UI flow + screenshot is ~30–60 s; cache-dependent checks
add ~60 s. Do not chain 30-case UI suites without checkpointing.
---
## 3. Maestro run patterns that work
Call through the Code Mode tool:
`tools.maestro.run({ yaml, device_id })`.
### 3.1 Basic shape
```yaml
appId: com.freshyotrial.app
---
- launchApp: { clearState: true }
- extendedWaitUntil:
visible: { id: home-search }
timeout: 90000
```
### 3.2 Text selection is regex + substring
`text: 'Me'` also matches "**Me**at" and other labels. Use anchors
(`^Me$`) — but tab-bar labels are often **not text nodes**, so `tapOn: text: '^Me$'`
fails with "Element not found". Tap the tab by **point** instead.
### 3.3 testIDs that exist (verified)
- Customer login: `user-login-mobile`, `user-login-identifier`, `user-login-password`,
`user-login-other-ways`, `user-login-submit`.
- Admin login: `login-name-input`, `login-password-input`, `login-button`.
- Home/search: `home-search`, `search-input-input`.
- Cart/checkout: `checkout-button`, `place-order-button`, `address-option-0`,
`select-address-error`, `go-to-cart`, `add-to-cart-confirm`, `slot-<date>-<hh>-<mm>`.
- Admin dashboard: `add-product-menu-item`, `delivery-slots-menu-item`, and the
product/slot form ids used by `tests/e2e/*.yaml`.
### 3.4 `scrollUntilVisible` works
Use it for long forms/screens (it needs an `id:` element):
```yaml
- scrollUntilVisible:
element: { id: checkout-button }
direction: DOWN
timeout: 20000
```
### 3.5 Swipes
`swipe` with `start`/`end` percentages works, but a horizontal carousel (e.g. the
cart address carousel) often **refuses to advance** — the card captures the
gesture. If it won't move after 2 tries, stop and find another path (e.g. set the
target address as default via API, then relaunch).
---
## 4. iOS simulator gotchas (the big time sinks)
### 4.1 `hideKeyboard` fails
It errors with `Couldn't hide the keyboard. This can happen if the app uses a
custom input…`. **Do not rely on it.** Instead tap a neutral area to dismiss the
keyboard, e.g. `tapOn: { point: '50%,25%' }`, then tap the submit button.
### 4.2 Secure password fields DO accept `inputText`
The value is **masked** in screenshots — it looks empty. Do not conclude input
failed. To confirm, toggle the field's eye icon (makes it plain text) or proceed
and check the result. The earlier "secure field is broken" conclusion was a
misread of the masked screenshot.
**Reliable customer-login recipe:**
```yaml
appId: com.freshyotrial.app
---
- launchApp
- extendedWaitUntil: { visible: { id: home-search }, timeout: 90000 }
- tapOn: { point: '90%,92%' } # Me tab
- extendedWaitUntil: { visible: { text: 'Log In' }, timeout: 20000 }
- tapOn: { text: 'Log In' }
- extendedWaitUntil: { visible: { id: user-login-mobile }, timeout: 20000 }
- tapOn: { id: user-login-mobile }
- inputText: '9676651496'
- tapOn: { id: user-login-other-ways } # jumps to password step, no OTP
- extendedWaitUntil: { visible: { id: user-login-password }, timeout: 15000 }
- tapOn: { id: user-login-password }
- inputText: 'meatfarmer@123'
- tapOn: { point: '50%,25%' } # dismiss keyboard
- tapOn: { text: 'Login' } # submit
```
- **Do not `pressKey: enter` on the mobile step** — that submits and sends an OTP.
- **Admin login** is simpler and works including the secure field:
type name → type password → `tapOn: { id: login-button }` (no `hideKeyboard`).
### 4.3 `eraseText`
Deletes from the **cursor**. After `tapOn` the field the cursor may be mid-string,
so `eraseText` may not clear everything. Focus the field, erase a generous count,
then verify with a screenshot (or the eye toggle).
### 4.4 `pasteText`
On iOS it opens the edit menu (Paste / Select All / AutoFill) instead of pasting
directly. Follow it with `tapOn: { point: … }` on "Paste". Setting the simulator
clipboard first: `printf 'text' | xcrun simctl pbcopy <device_id>`.
### 4.5 Deep-link confirm dialog
`openLink: freshyo://login` raises an iOS SpringBoard alert **"Open in 'Freshyo'?"**
that **survives `launchApp`**. Dismiss it explicitly before asserting:
```yaml
- launchApp
- tapOn: { text: 'Cancel', optional: true }
- tapOn: { text: 'Open', optional: true }
- extendedWaitUntil: { visible: { id: home-search }, timeout: 60000 }
```
Deep link on the admin app works for routes: `openLink: freshyoadmin://dashboard/slots/add`.
### 4.6 Screenshots and hierarchy
- `tools.maestro.take_screenshot({ device_id })` returns `null` on iOS but the
image is still shown to you — rely on it.
- `tools.maestro.inspect_screen` overflows depth on content-heavy screens; don't
depend on it for the customer app.
### 4.7 Permissions
Maestro `permissions: { location: allow }` is rejected on iOS
(`wrong argument value 'allow'`). Handle the OS permission alert manually, or rely
on the already-granted permission in the dev build.
### 4.8 Simulated location (change it from the CLI)
Set the iOS simulator's GPS location with `xcrun simctl location` — no Xcode UI,
no Maestro flow. The device is addressed by UDID, or the literal `booted` for the
currently booted sim:
```bash
xcrun simctl location booted set 16.7489,77.9856 # inside region A (Mahabubnagar)
xcrun simctl location booted set 0.0,0.0 # outside every bound
xcrun simctl location booted set 17.3850,78.4867 # inside region B (Hyderabad) — if its polygon exists
```
`set <lat>,<lon>` is the everyday command. The full action list:
| Action | What it does |
|---|---|
| `set <lat>,<lon>` | Pin a fixed coordinate (persists until changed/cleared). |
| `clear` | Stop any scenario and remove the simulated location (device falls back to none). |
| `list` | List built-in simulation **scenarios** (e.g. City Run, Freeway Drive, custom). |
| `run <scenario>` | Run a named scenario from `list`. |
| `start [--speed=<m/s>] [--distance=<m>|--interval=<s>] <lat,lon> <lat,lon> …` | Walk through waypoints, interpolating over time (≥2 waypoints; `-` reads from stdin). Good for a GPS "move across bounds" / region-race test. |
```bash
xcrun simctl location booted clear # reset before/after a test
xcrun simctl location booted list # see scenarios
xcrun simctl location booted run 'City Run' # simulate movement
# move A → B over ~5 min, an update every 250 m:
xcrun simctl location booted start --speed=20 --distance=250 16.7489,77.9856 17.3850,78.4867
```
Notes:
- **Format:** decimal separator must be `.`, field separator `,` (`16.7489,77.9856`);
do not use a locale comma-decimal or a space.
- **Availability:** the `location` subcommand needs a recent Xcode (present on
Xcode 16.4 here). Confirm with `xcrun simctl help | grep -i location`; if it is
missing, use Xcode → Simulator → **Features ▸ Location** (GUI) instead.
- **Target the right sim:** if more than one is booted, `booted` is ambiguous — use
the UDID from `xcrun simctl list devices booted` (or `tools.maestro.list_devices()`).
- **Persistence:** the setting survives app relaunch, so it must be set *before*
the app's startup region resolution. `clear` restores "no location" — do this
after a location-dependent test so later runs are not biased.
- A location outside all bounds does not hang; with no default address the chooser appears (the region is never persisted) — good for RG-04.
- There is no continuous region tracking while the app is open; resolution is a
one-shot startup check, so change location then **relaunch** to re-resolve.
---
## 5. Web (Chromium) gotchas
- Web flows **must** start with `openLink:` (not `launchApp`).
- Superadmin Regions page is long — `scrollUntilVisible` is required.
- Plain inputs (no testIDs) are addressed by their `topLabel` text.
- Prefer the web UIs for superadmin/admin setup when a native picker would be
painful (iOS date/time pickers, photo pickers).
---
## 6. Backend probing (your fastest, most reliable tool)
### 6.1 tRPC wire format (important!)
- Base: `http://localhost:8787/api/trpc/<router.procedure>`.
- **Mutations:** `POST` with a **plain JSON body** — no batch wrapper, no
`{"json": …}`:
```bash
curl -s -X POST http://localhost:8787/api/trpc/superadmin.auth.login \
-H 'content-type: application/json' \
-d '{"username":"superadmin","password":"superadmiN123"}'
```
- **Queries:** `GET` with `?input=<urlencoded JSON>`:
`/api/trpc/superadmin.regions.list?input=%7B%7D`.
(Posting a query to a mutation path returns `405 Unsupported POST-request to query procedure`.)
- Auth header: `authorization: Bearer <token>`.
- Responses: `{ "result": { "data": … } }` or `{ "error": { … } }`.
### 6.2 Logins
- Superadmin: `superadmin.auth.login {username,password}` → `data.token`.
- Admin (staff): `admin.staffUser.login {name,password}` → `data.token`.
- Customer: `user.auth.login {identifier,password}` → `data.data.token`.
- Region is derived from the staff row server-side, never from client input.
### 6.3 Known quirks
- `ApiError` statuses are flattened to **HTTP 500** (wrong-password → 500, not 401).
- `admin.product.createProduct` requires each SKU to have a feature with
`featureName: 'quantity'` (lowercase) and a non-empty value.
- `admin.store.updateStore` requires `owner` (staff id); `deleteStore` takes `storeId`.
- Admin order detail items are under `items`, not `orderItems`.
- Customer order detail items are under `items` too.
### 6.4 Authoritative DB reads
The local D1 file is readable with `sqlite3` for ground truth (never run
migrations):
```
apps/backend/.wrangler/state/v3/d1/miniflare-D1DatabaseObject/da3a80bd….sqlite
```
Use it to confirm orders/items/addresses after a UI action.
---
## 7. Cache & versioning (why "the app didn't update")
The customer app reads catalog/availability/slots from published cache files at
`https://assets2.freshyo.in/…` (region + version), not from the DB directly.
- After an admin write, the backend bumps a per-region version
(`products_version_num`, `availability_version_num`, `slots_version_num`) and
regenerates files.
- The app picks up a new version **on relaunch** or within the ~60 s discovery
poll (`refetchInterval: 60000`).
- To check what the app will see:
```
common.essentialConsts?boundId=<id> → assetsDomain, apiCacheKey, versions
https://assets2.freshyo.in/api-cache-dev/regions/<r>/v-<pv>/products.json
https://assets2.freshyo.in/regions/<r>/av-<av>/availability.json
https://assets2.freshyo.in/regions/<r>/slots/v-<sv>/slots.json
```
- **Relaunch the app after fixture changes**, and give the cache a few seconds.
---
## 8. Fixtures & test data
- Prefer creating fixtures through the **same tRPC mutations the UIs call** (the
plan sanctions a fixture API). Faster and deterministic.
- Known-good test accounts created for the run: staff `e2eadminA`/`e2eadminB`
(`Test@12345`, regions 1/2), customers U2 `e2e_u2@test.com` / U5 `e5@…` etc.
- GPS `16.7489,77.9856` resolves to region 1 (Mahabubnagar), bound 1.
- Region 2's bound has an **empty polygon** — GPS can never resolve to it; select
it manually to test region B.
- Clean up disposable fixtures when done (delete the extra products/slots/regions
you created) so the region selector and catalog stay tidy.
---
## 9. Verified reusable recipes
**Region switch:** Home → `point 50%,10%` (or `18%` — screenshot first) DELIVER TO
bar → region row → "Switch & clear cart".
**Add to cart (scheduled):** `home-search` → `search-input-input` → type name →
`pressKey: enter` → product ADD TO CART (`point`, text match fails) → select slot
row → "Add to Cart" → "Go to Cart".
**Place COD order:** cart → scroll → `checkout-button` → checkout → scroll →
"Place Order" (`point 50%,72%`) → "Order Placed Successfully!".
**Cart login wall:** signed out, open cart → "Please log in … view your cart" with
"Log In" + "Go Back". Login returns to the cart with items intact.
**Cart first-address gate:** signed in with zero addresses, open cart → the
add-address gate shows *before* the cart (even when the cart is empty); the first
saved address becomes the default, then the cart renders.
**Logout:** Me tab → gear → scroll down → "Logout".
**Flash:** enable flash in the region (`superadmin.regions.updateRegionConstants`),
then 1 Hr Delivery tab → product detail → "Get in 1 Hour" (separate flash cart).
---
## 10. Things that look like bugs but are NOT
- **"Empty" secure password field** → it is filled; it's masked.
- **"Out of Stock" all over Home** → slot-driven (`isOutOfStock || (slotsLoaded && !slotId)`).
Products without a current active slot show OOS. Not a product-flag bug.
- **Cart shows "FREE DELIVERY UNLOCKED" after relaunch** → the explicit address
selection isn't persisted, so the active bound (lowest-priority address bound)
applies instead of the previously selected address's bound.
- **Region B not reachable by GPS** → its bound polygon is empty (fixture).
- **Admin order items empty** → you read `orderItems`; the key is `items`.
---
## 11. Run checklist
Before:
- [ ] `list_devices` → pick the connected iOS sim (and/or `chromium`).
- [ ] Confirm Metro/backend/web ports are up (`lsof -nP -iTCP -sTCP:LISTEN`).
- [ ] Screenshot the current screen before the first percentage tap.
During:
- [ ] Use `id:` selectors; screenshot to confirm; point taps as fallback.
- [ ] Dismiss the "Open in Freshyo?" alert if you used `openLink`.
- [ ] Dismiss the keyboard by tapping a neutral area before submitting.
- [ ] For invariants, probe tRPC/DB rather than trusting the UI.
After:
- [ ] Restore any global/region toggles you changed (flash, consts, tagsOrder).
- [ ] Delete disposable fixtures; verify regions/consts/products are back to baseline.
- [ ] Record results with entity IDs and screenshots; mark harness failures BLOCKED,
not FAIL.