358 lines
16 KiB
Markdown
358 lines
16 KiB
Markdown
# 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.
|