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

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

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

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