552 lines
24 KiB
Markdown
552 lines
24 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) |
|
||
| 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:
|
||
|
||
```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 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
|
||
```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`.
|
||
- Admin slot form (DEV-only): `test-set-current-datetime` plus the
|
||
`dev-*` ids listed in §10.1.
|
||
|
||
### 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 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:
|
||
|
||
```bash
|
||
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-google-signin` is 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:
|
||
|
||
```bash
|
||
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/`:
|
||
|
||
```bash
|
||
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):
|
||
|
||
```bash
|
||
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):
|
||
|
||
```bash
|
||
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:
|
||
|
||
```yaml
|
||
appId: host.exp.Exponent
|
||
---
|
||
- openLink: exp://127.0.0.1:8082 # admin-ui
|
||
- extendedWaitUntil: { visible: 'Dashboard', timeout: 60000 }
|
||
- tapOn: 'Manage Orders'
|
||
```
|
||
|
||
```yaml
|
||
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": …}`:
|
||
```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": { … } }`.
|
||
|
||
### 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).
|
||
|
||
### 10.1 Admin slot form: hidden datetime hook (DEV only)
|
||
|
||
The native iOS/Android date+time scrollers are unusable from Maestro. `SlotForm`
|
||
(add **and** edit screens) therefore has a `__DEV__`-only hook that sets both
|
||
datetimes from plain text inputs.
|
||
|
||
| ID | What it is |
|
||
|---|---|
|
||
| `test-set-current-datetime` | Invisible 1×1 button at the form's top-left corner. Opens the dialog. |
|
||
| `dev-delivery-date` | Delivery date, `YYYY-MM-DD` |
|
||
| `dev-delivery-time` | Delivery time, 24h `HH:MM` |
|
||
| `dev-freeze-date` | Freeze date, `YYYY-MM-DD` |
|
||
| `dev-freeze-time` | Freeze time, 24h `HH:MM` |
|
||
| `dev-datetime-header` | Dialog title area; tapping it dismisses the keyboard |
|
||
| `dev-datetime-error` | Inline validation message (bad format, or freeze > delivery) |
|
||
| `dev-cancel-datetime` | Close without touching the form |
|
||
| `dev-apply-datetime` | Apply both fields at once |
|
||
|
||
Important details:
|
||
- **The button is 1×1 and transparent, not `left: -1000`.** iOS removes
|
||
off-screen views from the accessibility tree, so Maestro cannot find an
|
||
off-screen `testID`. Do not "fix" the style back to an off-screen position.
|
||
- Both times are interpreted as **IST (UTC+5:30)** and sent as UTC. If you
|
||
compute them in `evalScript`, remember `toISOString()` is UTC — add
|
||
`5.5*60*60*1000` before slicing, or your slot lands 5.5 hours early.
|
||
- The dialog opens **blank every time** (no prefill). Cancel leaves the form
|
||
untouched.
|
||
- After typing a field, tap `dev-datetime-header` before targeting the next
|
||
field that may sit under the keyboard. On iOS the keyboard covers the lower
|
||
fields and the Apply row, and a `tapOn` on a covered `testID` silently types
|
||
into the still-focused field above. `hideKeyboard` is unreliable (§4.1); the
|
||
header tap is ID-based.
|
||
|
||
Reusable flow: `tests/e2e/dev/add-slot-dev-datetime.yaml` (delivery = now + 2h,
|
||
freeze = now + 1h). Run it against a dev build:
|
||
|
||
```bash
|
||
STAFF_NAME=... STAFF_PASSWORD=... maestro test tests/e2e/dev/add-slot-dev-datetime.yaml
|
||
```
|
||
|
||
Or against Expo Go (verified; pass env with `-e`, not shell env):
|
||
|
||
```bash
|
||
maestro test \
|
||
-e APP_ID=host.exp.Exponent \
|
||
-e EXPO_URL=exp://127.0.0.1:8082 \
|
||
-e STAFF_NAME=... -e STAFF_PASSWORD=... \
|
||
tests/e2e/dev/add-slot-dev-datetime.yaml
|
||
```
|
||
|
||
If Expo Go is already showing an old screen/dialog, terminate it first so the
|
||
flow starts clean:
|
||
|
||
```bash
|
||
xcrun simctl terminate <udid> host.exp.Exponent
|
||
```
|
||
|
||
Key steps:
|
||
```yaml
|
||
- scrollUntilVisible: { element: { id: delivery-slots-menu-item }, direction: DOWN }
|
||
- tapOn: { id: delivery-slots-menu-item }
|
||
- tapOn: { id: add-slot-fab }
|
||
- tapOn: { id: test-set-current-datetime }
|
||
- tapOn: { id: dev-delivery-date }
|
||
- inputText: '2026-10-25'
|
||
- tapOn: { id: dev-datetime-header }
|
||
- tapOn: { id: dev-delivery-time }
|
||
- inputText: '08:00'
|
||
- tapOn: { id: dev-datetime-header }
|
||
- tapOn: { id: dev-freeze-date }
|
||
- inputText: '2026-10-25'
|
||
- tapOn: { id: dev-datetime-header }
|
||
- tapOn: { id: dev-freeze-time }
|
||
- inputText: '07:00'
|
||
- tapOn: { id: dev-datetime-header } # dismiss the keyboard, no point taps
|
||
- tapOn: { id: dev-apply-datetime }
|
||
- scrollUntilVisible: { element: { id: create-slot-button }, direction: DOWN }
|
||
- tapOn: { id: create-slot-button }
|
||
```
|
||
|
||
---
|
||
|
||
## 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.
|