20 KiB
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
- 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 and18%on another). Point taps are relative to the current screenshot. - Prefer
id:(testID) for inputs/buttons; use point taps for everything else. RN text nodes are frequently invisible to Maestro's accessibility tree. - Never trust a "not visible" assertion on the RN app.
assertVisible/extendedWaitUntilontext:orid:can pass/fail incorrectly. Verify with a screenshot. - When an invariant matters, probe the backend directly (section 7). It is faster, deterministic, and gives authoritative evidence.
- Always include
device_idinrun. Prefer inlineyamlfor exploration. - 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 bytests/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: enteron 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 }(nohideKeyboard).
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:
- 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 })returnsnullon iOS but the image is still shown to you — rely on it.tools.maestro.inspect_screenoverflows 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= |
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
locationsubcommand needs a recent Xcode (present on Xcode 16.4 here). Confirm withxcrun 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,
bootedis ambiguous — use the UDID fromxcrun simctl list devices booted(ortools.maestro.list_devices()). - Persistence: the setting survives app relaunch, so it must be set before
the app's startup region resolution.
clearrestores "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:(notlaunchApp). - Superadmin Regions page is long —
scrollUntilVisibleis required. - Plain inputs (no testIDs) are addressed by their
topLabeltext. - 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 }
extendedWaitUntilwith a 60 s timeout is required — the JS bundle builds on first open.- Reloading = run
openLinkagain (this is the easiest CI-friendly reload); or shake the device → Reload; or pressrin 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. Theexp://link is routed through SpringBoard, so iOS shows a "back to Safari" affordance. The foreground app is still Expo Go — confirm withxcrun simctl launch <udid> host.exp.Exponentthen screenshot. Not a bug. launchAppcannot pick a project. It only resumes whatever Expo Go last opened, so always select the project withopenLink.expo-locationversion skew.admin-uideclaresexpo-location ^19.0.8(an SDK 54 line) while Expo Go 53 ships native 18.1. It is imported bymanage-orders,delivery-sequencesandOrderOptionsMenu, so those location calls may throw in Expo Go.user-uiis correct (~18.1.6). Pin admin-ui to~18.1.6if you hit it.expo-updatesis a no-op —updates.url/runtimeVersionare 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:
POSTwith 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:
GETwith?input=<urlencoded JSON>:/api/trpc/superadmin.regions.list?input=%7B%7D. (Posting a query to a mutation path returns405 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
ApiErrorstatuses are flattened to HTTP 500 (wrong-password → 500, not 401).admin.product.createProductrequires each SKU to have a feature withfeatureName: 'quantity'(lowercase) and a non-empty value.admin.store.updateStorerequiresowner(staff id);deleteStoretakesstoreId.- Admin order detail items are under
items, notorderItems. - Customer order detail items are under
itemstoo.
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 U2e2e_u2@test.com/ U5e5@…etc. - GPS
16.7489,77.9856resolves 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 isitems.
12. Run checklist
Before:
list_devices→ pick the connected iOS sim (and/orchromium).- 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.