simulator-audio-e2e

name	simulator-audio-e2e
description	Build and run repeatable react-native-nitro-sound recorder/player regression tests on an iOS Simulator or Android emulator, with explicit virtual-device selection, microphone permission, Maestro evidence, native log inspection, and cleanup. Use after dependency, Nitro, TypeScript, Swift, Kotlin, generated-binding, or audio state-machine changes when a physical device is not required.

Simulator Audio E2E

Verify real native recording and playback on virtual devices without touching a connected physical phone. Treat builds, UI automation, callback state, and log inspection as separate evidence.

Safety Boundary

• Require explicit permission in the current request before recording. State that sound.example records a short non-sensitive clip through the host or emulator microphone. A request to run audio E2E is sufficient permission.
• Select a concrete iOS Simulator UDID or Android serial beginning with emulator-. Never allow an implicit destination when physical devices are connected.
• Do not upload, transcribe, or retain the recording. Keep only screenshots, JUnit output, and redacted logs needed to diagnose the run.
• Do not claim Bluetooth, interruptions, backgrounding, audio focus, route changes, or audible fidelity from this lane; those require targeted tests and can require a physical device.

Preflight

1. Read AGENTS.md, .claude/commands/e2e-tests.md, the changed source, and references/flow-contract.md.
2. Preserve git status --short --branch; never clean unrelated work.
3. Run scripts/preflight.sh and select one available virtual destination.
4. Run yarn install --immutable, yarn prepare, yarn typecheck, yarn lint, and yarn test --runInBand.
5. Confirm sound.example declares microphone permission and no Metro process conflict exists on port 8081.

Build And Install

For iOS, boot the selected Simulator and build the Debug app for that exact UDID. Install the produced .app with xcrun simctl install. For Android, start the selected AVD, wait for boot completion, and build/install Debug with ANDROID_SERIAL set to the selected emulator serial.

Start Metro from the repository root with yarn start --reset-cache. Keep its session and save errors separately from native device logs. Grant microphone permission to sound.example on the selected virtual device before the flow.

Run The Runtime Contract

Run the repository flow through the guarded helper:

.codex/skills/simulator-audio-e2e/scripts/run-maestro.sh ios <simulator-udid>
.codex/skills/simulator-audio-e2e/scripts/run-maestro.sh android <emulator-serial>

The flow must prove both direct and hook APIs can:

1. Start recording and emit increasing record time.
2. Pause and resume the recorder without a crash or duplicate instance.
3. Stop and expose a playable path.
4. Start, pause, resume, and stop playback with matching UI state.
5. Complete with no visible error alert.

Do not weaken selectors or remove state assertions to make a failed flow pass. Fix the product or explain a platform limitation.

Inspect Native Evidence

After Maestro, inspect simulator logs for the current app process only:

• iOS: xcrun simctl spawn <udid> log show with a short time bound and a sound.example predicate.
• Android: adb -s <serial> logcat --pid=$(adb -s <serial> shell pidof sound.example) captured around the run.

Fail the runtime lane for uncaught exceptions, native crashes, rejected promises, MediaRecorder/AVAudio errors, or leaked-resource warnings attributable to the tested flow. Ignore unrelated host and OS noise with an explanation.

Report And Cleanup

Report BUILD PASS/FAIL and RUNTIME PASS/FAIL/BLOCKED per platform. Include the exact UDID/serial, OS/API level, RN and Nitro versions, flow path, callback states observed, JUnit result, and relevant redacted log findings. List every untested device-only row.

Terminate only Metro/emulators started by this run. Leave user-owned devices and processes intact. Use the guarded runner's mandatory cleanup and verify that no recording remains in the selected app container or e2e/artifacts/. Report RUNTIME BLOCKED if cleanup fails or cannot be confirmed. JUnit, screenshots, debug output, and redacted logs under e2e/artifacts/ remain disposable and ignored by Git.