freshyo/docs/maestro-mcp-agent-guidelines.md
2026-10-14 17:27:52 +05:30

20 KiB
Raw Blame History

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)
Expo Go (both apps) bundle host.exp.Exponent — xcrun simctl openurl <udid> exp://127.0.0.1:8081 (user-ui) / :8082 (admin-ui); see §6
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 (expo start) and often :8082 (expo run:ios) — both are the user's own processes, 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(). The booted simulator is not always the one in the table — always re-read xcrun simctl list devices booted (B1F98A94… and 5A64695E… have both been used). On this machine the Android emulator is usually not connected, so Android-only flows will not run. listapps to confirm which bundles are installed:

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 7). 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

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 "Meat" 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):

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

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

openLink: freshyo://login raises an iOS SpringBoard alert "Open in 'Freshyo'?" that survives launchApp. Dismiss it explicitly before asserting:

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

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= --interval=] <lat,lon> <lat,lon> …`
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 keeps the saved region (no hang) — 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. Running the apps in Expo Go (instead of a dev build)

You do not need expo run:ios to test the mobile apps. Both user-ui and admin-ui load in Expo Go, which is faster (no native build), survives a stale/absent dev build, and is fully driveable by Maestro. Verified 2026-10-12.

6.1 Is the project Expo Go-compatible?

List every third-party import and check it against Expo Go's bundled module set. Anything that ships its own native code and is imported is a blocker:

cd apps/<app>
grep -rhoE "from ['\"][^'\"]+['\"]" app components ../../packages/ui/src \
  | sed -E "s/from ['\"]//; s/['\"]//" | sort -u

In this repo no custom native module is actually imported: react-native-razorpay and @react-native-google-signin are declared in package.json but never imported in source (Google login goes through expo-auth-session), and expo-notifications is unused. Everything else is expo-* or JS-only. So both apps are Expo Go-safe.

6.2 Match the Expo Go client to the project SDK

Expo Go only runs one SDK version. Get the right client for the project's SDK from the versions API — then you know whether the installed client will work:

curl -s https://api.expo.dev/v2/versions/latest | python3 -c "
import sys,json; d=json.load(sys.stdin)['data']['sdkVersions']
for k in ['52.0.0','53.0.0','54.0.0']:
    print(k, d[k]['iosClientVersion'], d[k]['iosClientUrl'])"

Result here: SDK 53 → Expo Go 2.33.17, SDK 54 → 54.0.7, SDK 52 → 2.32.18. The repo is expo ~53.0.22, and host.exp.Exponent 2.33.17 was already installed, so it matched. Simulator clients are cached in ~/.expo/ios-simulator-app-cache/:

ls ~/.expo/ios-simulator-app-cache/                       # cached clients
xcrun simctl install <udid> ~/.expo/ios-simulator-app-cache/Expo-Go-2.33.17.tar.app
xcrun simctl listapps <udid> | grep -i exponent            # confirm

6.3 Launch a project in Expo Go

expo start and expo run:ios both serve a Metro bundle; Expo Go only needs the exp:// URL for that port. Find which project owns a port from the server's cwd (don't guess, don't start a second Metro):

lsof -a -p <metro_pid> -d cwd -Fn | grep '^n'   # → .../apps/user-ui or .../apps/admin-ui

Then open it headlessly (no terminal keystrokes needed):

UDID=$(xcrun simctl list devices booted | grep -oE '[0-9A-F-]{36}' | head -1)
xcrun simctl openurl $UDID "exp://127.0.0.1:8081"   # user-ui  (customer app)
xcrun simctl openurl $UDID "exp://127.0.0.1:8082"   # admin-ui (admin app)

The first bundle takes ~20–40 s (longer in a monorepo). 127.0.0.1 is correct for the simulator; use the LAN IP only for a physical device.

6.4 Driving Expo Go with Maestro MCP

Both projects share one bundle id (host.exp.Exponent), so launchApp cannot pick a project — select it with openLink inside the flow:

appId: host.exp.Exponent
---
- openLink: exp://127.0.0.1:8082          # admin-ui
- extendedWaitUntil: { visible: 'Dashboard', timeout: 60000 }
- tapOn: 'Manage Orders'
appId: host.exp.Exponent
---
- openLink: exp://127.0.0.1:8081          # user-ui
- extendedWaitUntil: { visible: 'Delivery Address', timeout: 60000 }
  • extendedWaitUntil with a 60 s timeout is required — the JS bundle builds on first open.
  • Reloading = run openLink again (this is the easiest CI-friendly reload); or shake the device → Reload; or press r in the Metro terminal.
  • testIDs behave exactly as in a dev build, so keep preferring id: selectors.

6.5 Expo Go quirks

  • The status bar shows ◀ Safari. The exp:// link is routed through SpringBoard, so iOS shows a "back to Safari" affordance. The foreground app is still Expo Go — confirm with xcrun simctl launch <udid> host.exp.Exponent then screenshot. Not a bug.
  • launchApp cannot pick a project. It only resumes whatever Expo Go last opened, so always select the project with openLink.
  • expo-location version skew. admin-ui declares expo-location ^19.0.8 (an SDK 54 line) while Expo Go 53 ships native 18.1. It is imported by manage-orders, delivery-sequences and OrderOptionsMenu, so those location calls may throw in Expo Go. user-ui is correct (~18.1.6). Pin admin-ui to ~18.1.6 if you hit it.
  • expo-updates is a no-op — updates.url / runtimeVersion are ignored and the bundle always comes from Metro.
  • Config plugins are not applied (custom splash, intentFilters, notification entitlements, …). Anything plugin-driven, plus SDK bumps and new native deps, must still be verified in a dev build (expo run:ios).

7. Backend probing (your fastest, most reliable tool)

7.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": …}:
    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": { … } }.

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

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

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


8. 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.

9. 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.

10. 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.

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).


11. 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.

12. 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.