Native Testing¶
How to QA the native iOS and Android apps — simulators, real devices, OAuth caveats, and the failures you'll see most often.
For the release workflow see Native Release. For local Android dev environment (Android Studio, keystores, SHA-1) see Local development.
Local development modes¶
There are three ways to run the app locally, in increasing order of fidelity to a production build:
1. Expo Go (web / quick-look only)¶
task dev:frontend starts the Expo dev server on :8081. You can scan the QR with the Expo Go app for the fastest possible loop, but this has hard limits:
- No native modules outside the Expo Go SDK (rules out Google Sign-In, certain camera/payment features).
- No custom URL schemes / deep links.
Useful for UI-only changes. For everything else, use a dev client.
2. iOS Simulator¶
# First run on the Simulator (or after a native dep change)
task dev:ios # = npx expo run:ios
# Day-to-day after that
task dev:frontend # starts Metro; then press "i"
The first run installs the dev client into the Simulator. Subsequent runs reuse it; JS edits hot-reload via Fast Refresh without rebuilding the binary.
The same pattern applies to Android with task dev:android then task dev:frontend + a.
If you need a build that more closely matches production (signed, release config), build the store artifact locally with task native:beta:ios and install the resulting .ipa on a device via Xcode or TestFlight. See Native Release.
3. Real device via a local dev-client build¶
task dev:ios # = npx expo run:ios, builds + installs onto a tethered device
# or task dev:android for Android
Once installed, point the dev client at your local Metro server (task dev:frontend); the dev client landing page has a field to paste the URL.
This is the only way to test features that need a real device — native push notifications, biometric auth, camera, payments, deep links from third-party apps.
Pointing at different backends¶
Native builds bake in the EXPO_PUBLIC_API_URL and EXPO_PUBLIC_WS_URL at build time. To test against a non-production backend:
- Local backend: in a dev-client build with Metro pointing at
http://localhost:8081, the JS bundle is built on the fly and you can override env vars in your shell before running Metro. On Android emulator, usehttp://10.0.2.2:8080instead oflocalhost— the emulator can't see your host'slocalhostdirectly. - Dev backend: build locally with the dev API URL exported in your shell (or in
frontend/.env) before running the build.
OAuth client IDs¶
Google Sign-In needs a different OAuth client ID per platform. The native app reads three:
EXPO_PUBLIC_GOOGLE_WEB_CLIENT_ID— needed for the ID token exchange on both platformsEXPO_PUBLIC_GOOGLE_IOS_CLIENT_ID— iOS bundle ID-registeredEXPO_PUBLIC_GOOGLE_ANDROID_CLIENT_ID— Android package + SHA-1 registered
For production builds these come from frontend/.env at build time (native binaries are built locally). For local dev builds these come from your shell environment when running Metro / npx expo run:*. If you're testing OAuth on a dev build, make sure you've got the right values exported and they match the keystore SHA-1 of the build you're running. See Local Development for the Android SHA-1 details.
Common issues¶
Metro cache weirdness¶
If a JS change isn't showing up, or you see errors referencing modules that no longer exist:
task dev:frontend:clear
That clears Metro's transform cache. If it's still wrong, also cd frontend && rm -rf node_modules && npm install.
Android emulator can't see localhost¶
Symptom: backend requests fail immediately with a network error on the Android emulator, but iOS Simulator works fine.
Fix: use 10.0.2.2 instead of localhost for the API URL. The Android emulator runs its own NAT and localhost resolves to the emulator itself, not your host.
Google Sign-In: DEVELOPER_ERROR on Android¶
Symptom: Google Sign-In on Android fails immediately with DEVELOPER_ERROR (code 10).
Cause: the SHA-1 fingerprint of the keystore used to sign your current build is not registered with the Android OAuth client.
Fix:
- Get the SHA-1 of your debug or release keystore.
- Add it to the OAuth client in Google Cloud Console → APIs & Services → Credentials.
- Rebuild the app — the change is read at runtime so a rebuild isn't strictly necessary, but
expo prebuildartifacts may need refreshing.
Details and the keystore commands in Local Development.
Push notifications not arriving on iOS¶
Push only works on a real device with a build that includes the push entitlement and is signed against an APNs key. The iOS Simulator can't receive remote push at all (only foreground simulated ones).
Real-time updates stop arriving¶
Likely the WebSocket connection dropped and isn't reconnecting (or backed off too far). Check the device's network state, then check whether the backend Pod is healthy (see Getting Started → Investigate WebSocket flapping). The native WS client has the same idle-timeout sensitivity as the web client.
Focus / keyboard verification (shared-component refactor)¶
The shared-component refactor (field-rows, sheets, VisibilityPicker, ChatSettings) has so far been verified on web only. TextInput focus, keyboard-avoidance, and TrueSheet present/dismiss behave differently on native, so every input + sheet below needs a native pass. tsc / eslint / jest do NOT catch these; they are hand-QA on a device or emulator.
Keyboard avoidance is standardized on react-native-keyboard-controller: KeyboardProvider at the app root, useKeyboard/useKeyboardVisible, KeyboardAwareScroll for normal screens, and KeyboardStickyView for docked bars. Sheets keep TrueSheet's native handling (never nest a keyboard-controller view inside a TrueSheet). The Android side of this was validated separately: see Keyboard Android Handoff.
Quick Android emulator (Linux-doable; no Mac needed)¶
export ANDROID_HOME=$HOME/Android/Sdk
SDKM=$ANDROID_HOME/cmdline-tools/latest/bin/sdkmanager
# One-time: emulator + a system image (needs /dev/kvm for acceleration)
yes | "$SDKM" --install "emulator" "system-images;android-34;google_apis;x86_64" "platforms;android-34"
echo no | "$ANDROID_HOME/cmdline-tools/latest/bin/avdmanager" create avd -n tomoda -k "system-images;android-34;google_apis;x86_64" -d pixel_6
"$ANDROID_HOME/emulator/emulator" -avd tomoda -gpu swiftshader_indirect & # add -no-window for headless
# Build + install the dev client, then Metro hot-reloads JS:
task dev:android # = npx expo run:android
iOS has no Linux path; use a Mac simulator (task dev:ios) or a real device.
The checklist (walk each on Android + iOS)¶
| Surface | What to verify | Risk |
|---|---|---|
| ChatSettings nickname sheet | bottom Sheet lifts above the keyboard; input never hidden |
high (was a top overlay; now bottom-anchored) |
| ChatSettings nickname input | autoFocus actually focuses inside TrueSheet (can race the present animation on native) |
high |
| ChatSettings nickname | focus border toggles (primary↔surface); Save disabled on empty/whitespace + during save; dismiss via X, backdrop, swipe-down | med |
| ChatSettings group-rename inline edit | autofocus, returnKeyType=done, submit renames, disabled during save |
med |
| ChatSettings disappearing-messages | SelectionSheet tap-to-select updates + auto-closes; selected row highlighted |
low |
InlineEditField (profile-edit name / bio) |
always-editable; dirty reveals revert/confirm; keyboard doesn't cover the confirm buttons; save flashes ✓ | high |
change-username / change-email / change-password |
FocusField input focus + keyboard-avoid; submit; error surfacing |
med |
QuickAddSheet / ItemSheet inputs |
sheet input not clipped by keyboard; docked footer rides the keyboard (default keyboardOffset) |
high |
| compose-moment caption + Publish | caption scrolls clear; the absolute Publish footer (KeyboardStickyView) rides the keyboard, not covered |
high |
| QuickReplyBar (moment reply) | reply bar rests just above the keyboard; no double-lift; dismiss via backdrop | high |
| MomentEditSheet form | caption scrolls above the keyboard so lifetime / companions / delete stay reachable | high |
Chat composer (MessageInput) |
composer + send stay above the keyboard; picker toggle doesn't double-pad | high |
VisibilityPicker pills |
tap selects; wraps correctly; no keyboard involvement | low |
Any Sheet with a SearchField (People add-friends, message search) |
autofocus + keyboard-avoid | med |
| Safe-area insets | notch/gesture-bar devices: headers + docked footers respect insets | med |
Log results against this table per platform; file a bug for any row that fails and reference the surface name.
End-to-end flows (Maestro)¶
Scripted flows live in frontend/.maestro/ and drive the native app on a booted iOS Simulator against the local backend and seed data. Setup, conventions, and how to write new flows are in frontend/.maestro/README.md.
How to run¶
Prerequisites: task dev (backend), task test:simulation (seed data, creates testuser1@tomoda.life / password), and the app installed on a booted simulator (task dev:ios).
task e2e:ios # whole suite, in app-navigation order
task e2e:smoke # smoke-tagged flows (one core path per section)
task e2e:ios FLOW=.maestro/flows/06-social # one section
task e2e:ios FLOW=.maestro/flows/06-social/03-chat.yaml # one flow
Results and failure screenshots land in ~/.maestro/tests/<timestamp>/.
The 10-backstage flows need a personal account linked to a Tomoda account, which the seed data does not create. Pass the accounts with -e, never in a committed file:
maestro test .maestro/flows/10-backstage/01-switch.yaml -e E2E_USER=<personal email> -e E2E_PASS=<password> -e TOMODA_PASS=<Tomoda password>
maestro test .maestro/flows/10-backstage/02-people.yaml ... -e PEOPLE_QUERY=<handle> -e PEOPLE_NAME=<display name>
maestro test .maestro/flows/10-backstage/04-report-filing.yaml -e E2E_USER=<member email> -e E2E_PASS=<password> -e REPORT_HANDLE=<another member's handle>
03-triage-swipe needs at least two open, non-urgent report groups.
Structure¶
flows/<NN-section>/<NN-feature>.yaml, sections in navigation order:01-auth,02-home,03-discover,04-search,05-planner,06-social,07-hub,08-profile-settings,09-app-lifecycle,10-backstage.config.yamlglobsflows/**and lists every flow'sname:inexecutionOrder.flowsOrder.- Tags: all flows are
full; 11 are alsosmoke. The10-backstageflows are also taggedbackstage. subflows/:ensure-session(every flow starts with it, except auth flows that need a signed-out start),do-login,dismiss-dev-toast,nav-to-<tab>,open-first-plan,login-as(a fresh sign-in as${E2E_USER}),enter-backstage(Hub row and password step-up with${TOMODA_PASS}).- Flows are read-only where possible. The flows that create data name it "E2E test plan", "E2E test idea" or "E2E archived idea" and delete it before finishing.
Coverage matrix¶
Status: covered (asserted by a flow), partial (renders, some actions not driven), skipped (cannot run locally, with the reason).
| Section | Screen | Feature | Flow | Status |
|---|---|---|---|---|
| Auth | Welcome, login | Cold start, two-step login to home | 01-auth/01-login (smoke) |
covered |
| Auth | Login | Wrong password error, Back out to welcome | 01-auth/02-login-errors |
covered |
| Auth | Register, forgot password | Screens render and link to each other (no submit) | 01-auth/03-sign-up-and-recovery |
covered |
| Auth | Complete profile | Incomplete account lands on the username step | 01-auth/04-complete-profile |
covered |
| Auth | Account | Log out to welcome, log back in | 01-auth/05-logout |
covered |
| Auth | Login | Apple / Google sign-in, passkey | - | skipped: external identity providers |
| Home | Discover digest | Hero cards, For You list | 02-home/01-digest (smoke) |
covered |
| Home | Discover digest | Card links to Events, Notifications, Connect | 02-home/02-digest-links |
covered |
| Discover | Map | Opens from Explore nearby, controls render, Back | 03-discover/01-map (smoke) |
partial: basemap tiles need a map key, so only map chrome is asserted |
| Discover | Map | Zoom, layers sheet | 03-discover/02-map-controls |
covered |
| Search | Search tab, event detail | Event results, open detail, Back | 04-search/01-events (smoke) |
covered |
| Search | Filter overlay, results | Overlay lists the filter sections, query filters results in place, Filters button with a count badge stays in the bar, clear exits search | 04-search/02-filters |
covered |
| Search | Places and events browse | Quick chips, cards, section headings | 04-search/04-places-browse, 04-search/05-events-browse |
covered |
| Search | Typed search groups | Area first, header per far group, each tab keeps its own keyword, clear exits | 04-search/06-typed-groups |
covered |
| Search | Quick chips and overlay | Selected state, Clear all, overlay seeded with live filters, count button, Reset | 04-search/07-quick-chips, 04-search/08-overlay-seeded, 04-search/10-saved-chip |
covered |
| Search | Sort and time of day | Overlay Sort and Time of day apply on submit, seed the next open, per-mode sort values, each tab keeps its filters | 04-search/11-sort-time |
covered |
| Search | See all | Applies the chip, clear returns to browse scrolled | 04-search/09-see-all |
covered |
| Search | Locations mode, place sheet | Nearby places, place actions | 04-search/03-locations |
covered |
| Planner | Saved ideas, item sheet | List, search, item sheet labels, Archived view and back | 05-planner/01-saved |
covered |
| Planner | Plans list | Plan cards, sub-tab switch | 05-planner/02-plans (smoke) |
covered |
| Planner | Plan detail | People sheet, options sheet, reopen from cache | 05-planner/03-plan-detail |
covered |
| Planner | Place map | Plan Map action opens the place map | 05-planner/04-plan-map |
covered |
| Planner | Create plan | Create, empty state, archive, delete | 05-planner/05-create-plan |
covered |
| Planner | Quick add, archive | Save an idea, archive, delete forever | 05-planner/06-quick-add-idea |
covered |
| Planner | Events shortcut | Header Events opens the events list | 05-planner/07-events-entry |
covered |
| Planner | Saved-ideas search | Archived matches listed under an Archived header, restore moves one back | 05-planner/08-search-archived |
covered |
| Planner | Join plan by invite link | Accept an invite token | - | skipped: needs an invite minted by a second account |
| Social | Friends, close friends, blocked | Rows, scroll, sub-pages (loaded or empty) | 06-social/01-friends (smoke) |
covered |
| Social | Connect inbox | Chat list, filters, New chat sheet | 06-social/02-inbox (smoke) |
covered |
| Social | Chat, chat settings | Messages, composer, settings | 06-social/03-chat |
partial: read-only, nothing is sent |
| Social | Notifications | Rows, scroll both ways, Back | 06-social/04-notifications |
covered |
| Social | Moments feed | Moments / Events modes, close | 06-social/05-moments |
covered |
| Social | User profile | Friend profile from the friends list | 06-social/06-friend-profile |
covered |
| Social | Draft chat, single moment, moments viewer | Start a DM, moment permalink | - | not yet covered |
| Hub | Hub | Passport card, sections, sub-page nav | 07-hub/01-hub (smoke) |
covered |
| Hub | Horizon events, event detail | Sub-tabs, detail, Create Event sheet (no submit) | 07-hub/02-events |
covered |
| Hub | Horizon voyages | Active / Planning / Past groups | 07-hub/03-voyages |
covered (opened by deep link; no in-app entry yet) |
| Hub | Passport (profile Journal / Atlas) | Stamps, voyage detail | 07-hub/04-passport |
covered |
| Profile and settings | Own profile, edit profile | Stats, editor opens (nothing saved) | 08-profile-settings/01-profile (smoke) |
covered |
| Profile and settings | Preferences | Sections render | 08-profile-settings/02-preferences |
partial: toggles are not flipped |
| Profile and settings | Appearance | Dark, Light, back to System | 08-profile-settings/03-appearance |
covered |
| Profile and settings | Security, change username | Rows, username form (no submit) | 08-profile-settings/04-security |
covered |
| Profile and settings | Change email, change password | Verification code flow | - | skipped: opening sends a verification code |
| Profile and settings | Account | Email, join date, Log Out / Delete visible | 08-profile-settings/05-account |
covered |
| Profile and settings | Account | Delete account | - | skipped: destructive |
| App lifecycle | Relaunch | Session and cached Planner list survive a kill | 09-app-lifecycle/01-resume (smoke) |
covered |
| App lifecycle | Background / foreground | Same screen and session on return | 09-app-lifecycle/02-background |
covered |
| App lifecycle | Deep links | tomoda:// links route into a session |
09-app-lifecycle/03-deep-links |
covered |
| Capture | Camera, preview, compose moment, check-in | Native capture | - | skipped: needs a device camera (capture routes are native-only) |
| Partner | Dashboard, events, members, hub | Partner tools | - | skipped: needs a partner account |
| Backstage | Hub row, step-up, Today | Switch with a password step-up, sign out back to the personal account | 10-backstage/01-switch (smoke) |
covered (passkey step-up skipped: the simulator has no passkey for a local domain) |
| Backstage | People | Search, open a member, actions visible (none run) | 10-backstage/02-people |
covered |
| Backstage | Reports triage | Swipe right skips, swipe left dismisses | 10-backstage/03-triage-swipe |
covered |
| Report | Report sheet | Report a profile from its overflow menu | 10-backstage/04-report-filing |
covered |
| Support | Contact us | Open a request, land on its thread | 10-backstage/05-contact-us |
covered |
| - | Payments | - | - | n/a: the app has no payment surface |
See also¶
- Local Development — Android Studio, SDK, emulator, signing
- Native Release — local build + manual store upload flow
- Secrets — what
EXPO_PUBLIC_*actually means