Skip to content

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, use http://10.0.2.2:8080 instead of localhost — the emulator can't see your host's localhost directly.
  • 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 platforms
  • EXPO_PUBLIC_GOOGLE_IOS_CLIENT_ID — iOS bundle ID-registered
  • EXPO_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:

  1. Get the SHA-1 of your debug or release keystore.
  2. Add it to the OAuth client in Google Cloud Console → APIs & Services → Credentials.
  3. Rebuild the app — the change is read at runtime so a rebuild isn't strictly necessary, but expo prebuild artifacts 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.yaml globs flows/** and lists every flow's name: in executionOrder.flowsOrder.
  • Tags: all flows are full; 11 are also smoke. The 10-backstage flows are also tagged backstage.
  • 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