Mobile end-to-end coverage for auth, onboarding, and session recovery using Maestro.
Prerequisites#
-
Install Maestro:
bashbrew install mobile-dev-inc/tap/maestro -
Start the OSHUN BFF:
bashpnpm nx run @oshun/bff:devFor the PRO-gated
shell/authenticated-domain-rooms.yamlflow (Arete room + week-posture strip), start the BFF with the dev-only tier seams instead, so a fresh sign-up is provisioned as a verifiedproaccount and lands in the room rather than the access-locked gate:bashOSHUN_DEV_SIGNUP_PLAN=pro OSHUN_DEV_AUTO_VERIFY_EMAIL=true \ pnpm nx run @oshun/bff:dev # or the convenience alias that bakes in both seams: pnpm nx run @oshun/bff:dev-e2e-proBoth vars are inert under a production runtime (
resolveDevSignupPlanreturnsfreewhenisProductionRuntimeis true), so they are safe dev/test-only seams. Start a fresh BFF per run — the in-memory auth store rejects a repeat sign-up with the same email (EMAIL_ALREADY_REGISTERED). -
Start Metro for the dev client with E2E hooks enabled:
bashEXPO_PUBLIC_OSHUN_BFF_URL=http://127.0.0.1:4010 \ EXPO_PUBLIC_E2E_DISABLE_AUTOFILL=true \ pnpm --dir apps/oshun/mobile exec expo start --dev-client --port 8081 -
Build and launch the iOS simulator app with the local BFF URL:
bashEXPO_PUBLIC_OSHUN_BFF_URL=http://127.0.0.1:4010 \ pnpm --dir apps/oshun/mobile exec expo run:ios --simulator "iPhone 16"
Commands#
pnpm --dir apps/oshun/mobile run e2e:smokepnpm --dir apps/oshun/mobile run e2e:corepnpm --dir apps/oshun/mobile run e2e:nisabapnpm --dir apps/oshun/mobile run e2e:signoffpnpm --dir apps/oshun/mobile run e2e:regressionpnpm --dir apps/oshun/mobile run e2e:offline-retrypnpm --dir apps/oshun/mobile run e2e:assistant-transportpnpm --dir apps/oshun/mobile run e2e:matrix:assistant-transportpnpm --dir apps/oshun/mobile run e2e:matrix:assistant-transport:drypnpm --dir apps/oshun/mobile run e2e:matrixpnpm --dir apps/oshun/mobile run e2e:matrix:drypnpm --dir apps/oshun/mobile run e2e:matrix:iospnpm --dir apps/oshun/mobile run e2e:matrix:androidpnpm --dir apps/oshun/mobile run e2e:matrix:nisabapnpm --dir apps/oshun/mobile run e2e:matrix:nisaba:drypnpm --dir apps/oshun/mobile run e2e:matrix:nisaba:iospnpm --dir apps/oshun/mobile run e2e:matrix:nisaba:androidpnpm --dir apps/oshun/mobile run e2e:matrix:signoffpnpm --dir apps/oshun/mobile run e2e:matrix:signoff:drypnpm --dir apps/oshun/mobile run e2e:matrix:signoff:iospnpm --dir apps/oshun/mobile run e2e:matrix:signoff:androidpnpm --dir apps/oshun/mobile run e2e:matrix:offline-retrypnpm --dir apps/oshun/mobile run e2e:matrix:offline-retry:drypnpm --dir apps/oshun/mobile run e2e:matrix:offline-retry:iospnpm --dir apps/oshun/mobile run e2e:matrix:offline-retry:androidpnpm --dir apps/oshun/mobile run e2e:authpnpm --dir apps/oshun/mobile run e2e:onboardingpnpm --dir apps/oshun/mobile run e2e:recovery
The suite runner generates unique account emails for each flow so the smoke and regression runs remain repeatable against the in-memory auth service.
Offline retry coverage:
offline-and-retry-suite.yamlgroups Android offline shell continuity, activity retry editing, manual retry, and Tara/Veritas/Nisaba cache replay.- QA can run that contract directly with:
pnpm --dir apps/oshun/mobile run e2e:offline-retrypnpm --dir apps/oshun/mobile run e2e:matrix:offline-retrypnpm --dir apps/oshun/mobile run e2e:matrix:offline-retry:drypnpm --dir apps/oshun/mobile run e2e:matrix:offline-retry:iospnpm --dir apps/oshun/mobile run e2e:matrix:offline-retry:android
Shell accessibility coverage:
shell/navigation-accessibility-audit.yamlvalidates structural tab reach, thumb-zone domain-switcher access, and the shell-to-domain handoff path.shell/assistant-accessibility-audit.yamlvalidates the assistant sheet disclosure stack, text prompt composer, and assisted-action handoff path.shell/external-app-links.yamlvalidates release-candidate Universal Links and Android App Links fromhttps://oshun.appandhttps://www.oshun.appinto domain and assistant destinations, plushttps://app.oshun.comV3 and V6 app-host handoffs.- The flow is included in both
smoke-suite.yamlandregression-suite.yaml.
Core experience coverage:
core-experience-suite.yamlgroups the launch-critical auth, navigation, home, search, library, and assistant flows into one repeatable signoff suite.shell/veritas-briefing-explainer-flows.yamlis now part of the active core and regression suites, proving the Veritas mobile handoff from Home briefing into claim briefs, the global assistant sheet, and the compact explainer assistant/follow-up lane.shell/tara-home-quick-start-completion.yamlnow proves a real Home Tara quick-start can launch live audio, complete through the route-scoped Tara E2E harness path, auto-save the reflection, and return to Home without splitting that journey across separate synthetic flows.shell/search-library-assistant-journey.yamlcloses the missing explore search coverage by saving a real search result into Library and continuing into Assistant from the preserved surface.shell/activity-metis-continuity.yamlnow signs off the native Metis continuity path from Activity into the mobile shell preview, then verifies the real study-entry contract from that route: free course preview handoff plus Pro and Premium upgrade gating for tutoring and assessments.
Nisaba study coverage:
nisaba-study-suite.yamlis the dedicated Maestro contract for the Nisaba mobile study loop.- It groups the task-critical Nisaba study flows into one explicit suite:
shell/nisaba-domain-home.yamlshell/nisaba-reading-queue.yamlshell/nisaba-daily-passage.yamlshell/nisaba-assistant-explanation.yamlshell/nisaba-highlights-annotations.yamlshell/nisaba-quick-compare.yamlshell/nisaba-lexicon-morphology.yamlshell/nisaba-saved-materials.yamlshell/nisaba-study-reminders.yaml
- Together those flows cover domain home, reading queue, daily passage, assistant-assisted explanation with inspectable citations, compact highlights, annotation flow, quick compare, glossary lookup, morphology lookup, saved manuscripts/editions, and study reminders.
- QA can run that contract directly with:
pnpm --dir apps/oshun/mobile run e2e:nisabapnpm --dir apps/oshun/mobile run e2e:matrix:nisabapnpm --dir apps/oshun/mobile run e2e:matrix:nisaba:iospnpm --dir apps/oshun/mobile run e2e:matrix:nisaba:android
Redesigned shell signoff coverage:
shell-redesign-signoff-suite.yamlis the dedicated release-review suite for the redesigned mobile shell.- It groups the strongest home, navigation, continuation, and contextual assistant-entry flows instead of asking QA to assemble that bar manually.
shell/home-daypart-and-return-journeys.yamlnow asserts the redesigned Home launcher, quick-action, and assistant-entry hierarchy before release signoff.shell/library-and-assistant-navigation.yamlnow signs off assistant entry continuity from Home through Explore, Activity, Profile, and Library while asserting the persistent shell launcher context in each state.shell/redesigned-shell-visual-captures.yamlis the device-specific visual capture flow for redesigned shell review.../scripts/capture-shell-redesign-visuals.shruns that capture flow againstios-current,android-lower-tier, or both profiles.- Capture outputs are written into the ignored
artifacts/shell-redesign-signoff/screenshots/tree so QA can review the finaliphone-17andandroid-lower-tierscreenshot sets without polluting the git worktree. - For Android Expo Go signoff, the capture runner accepts the existing
APP_ID,DEV_CLIENT_LINK,EXPO_GO_LINK, andVERITAS_ROUTE_LINKoverrides and now bootstraps the Maestro Android helper packages automatically when the emulator is missing them.
Device matrix coverage:
device-matrix.yamlis the canonical QA matrix for:ios-current->iPhone 17with fallback toiPhone 17 ProandiPhone 16android-lower-tier->OSHUN Lower Tier Android
scripts/run-maestro-device-matrix.shruns the core suite against one profile or both profiles.- The same runner accepts
signoffandoffline-retryas suite arguments for redesigned shell release review and offline/cache replay on either matrix profile. --dry-runvalidates the resolved matrix commands without requiring a booted simulator or emulator.assistant-transportexercises native cancel, background/foreground, no automatic replay, and transcript continuity on both matrix profiles, plus an Android-only airplane-mode recovery cell. Build/start the tested client withEXPO_PUBLIC_OSHUN_MOBILE_ASSISTANT_TRANSPORT=streaming; the default remains buffered until admission. The paired Android benchmark runner and preregistered thresholds are documented indocs/audits/eve-phase-8.4-mobile-assistant-transport-contract.md.- For Android runs, bind the lower-tier target explicitly when needed:
ANDROID_LOWER_TIER_DEVICE_NAME="OSHUN Lower Tier Android" pnpm --dir apps/oshun/mobile run e2e:matrix:androidANDROID_LOWER_TIER_DEVICE_ID="<adb-device-id>" pnpm --dir apps/oshun/mobile run e2e:matrix:android
Authenticated domain-room coverage (Arete, PRO-gated)#
-
shell/authenticated-domain-rooms.yamlsigns up a fresh user against the local BFF, opens Arete, and asserts the authenticatedarete-week-posture-striprenders (GET /v1/arete/room) instead of the anonymous fixture fallback. -
It is NOT wired into any named suite, so run it directly against a BFF started with the pro-tier seams (see step 2 above):
bash# In a separate shell, after the pro-tier BFF + Metro + simulator are up: maestro test apps/oshun/mobile/e2e/flows/shell/authenticated-domain-rooms.yaml -
e2e/config.yamlsupplies the defaultAUTH_FLOW_*env the sign-up sub-flow needs; pass-e AUTH_FLOW_EMAIL=<unique>(or restart the BFF) to avoid anEMAIL_ALREADY_REGISTEREDcollision on a repeat run against the same BFF.