Emulator Testing

Emulator Testing

Drive a booted Android emulator or iOS simulator from the CLI for agent-in-the-loop testing: launch it headless, wait for a real boot, act on it with adb/simctl, verify with a real file parser (not a vibe check), shut it down clean.

Out of scope: installing the Android SDK, creating AVDs, or setting up Xcode/simulators. Assume $ANDROID_HOME/PATH and an existing AVD, or Xcode + simulator runtimes, are already in place. This skill is about driving them.

§2's adb primitives work unmodified against a real physical device over USB (same commands, target it with adb -s <device_serial>). §1's boot/lifecycle flags and §4's simctl lane are emulator/simulator-only and don't apply to physical hardware.

Decision Tree

Target platform?
├─ Android → live on this host → §1 boot the emulator → §2 drive it → §3 Flutter tests
└─ iOS     → needs a Mac → run over ssh to your macOS host → §4 simctl lane → §3 Flutter tests

1. Android Emulator Lifecycle

Headless Boot

emulator -avd <avd_name> \
  -no-window -no-audio -no-boot-anim \
  -gpu swiftshader_indirect \
  -no-snapshot-save \
  -read-only &

Match the system image ABI to the host arch (x86_64 image on an x86_64 host); an ARM image on x86 needs per-instruction translation and is dramatically slower.

Boot-Completion Detection

adb wait-for-device only confirms the adb bridge is up, not that Android finished booting:

adb -s emulator-5554 wait-for-device
until [[ "$(adb -s emulator-5554 shell getprop sys.boot_completed | tr -d '\r')" == "1" ]]; do
  sleep 2
done
adb -s emulator-5554 shell input keyevent 82   # KEYCODE_MENU, dismiss the lock screen

Clean Shutdown

adb -s emulator-5554 emu kill

If the console doesn't respond (auth-token mismatch, hung boot), fall back to killing the host process: pkill -f "qemu.*-avd <avd_name>".

2. Driving It: adb Primitives

Works against any installed app, Flutter or not.

No simulator equivalent: iOS's simctl (§4) has no touch/text input-injection primitive. Use integration_test/XCUITest-level tooling for iOS UI instead (see §4).

Verify Screenshots with a Real Parser, Not Prose

A vision-model "looks correct" read on a screenshot is not verification. Decode the file:

file shot.png   # expect: PNG image data, <W> x <H>, ...

To confirm an action actually changed the UI (not just that a file exists), diff two captures instead of trusting a description of them:

sha256sum before.png after.png   # identical hash = nothing changed on screen

3. Flutter Test Layers

Prefer integration_test over the legacy flutter drive: flutter drive runs a separate driver process against the app process and can't share flutter_test APIs, while integration_test runs in the app's own isolate and compiles the tests into the binary itself.

Screenshots from integration_test

await binding.convertFlutterSurfaceToImage(); // Android ONLY, before the first screenshot
await tester.pumpAndSettle();
await binding.takeScreenshot('screen-1');

Skipping convertFlutterSurfaceToImage() on Android produces blank/black captures. Not needed on iOS or web.

Persistence caveat (verified empirically): under plain flutter test integration_test/, takeScreenshot() only buffers the PNG bytes in the binding; nothing writes them to disk. Persisting needs the flutter drive path with a driver that consumes them (integration_test's flutter_driver extension + a responseDataCallback writing files). Without that wiring, capture independently via adb exec-out screencap -p instead.

Dart & Flutter MCP Server (Dev-Loop Tooling, Not a Test Runner)

For live inspection while iterating against a running flutter run session: hot reload, widget-tree/selected-widget introspection, runtime errors, static-analysis fixes, pub.dev search. It complements integration_test, it doesn't replace it: there's no repeatable CI suite here, just a tight feedback loop for an agent driving development.

Requires Dart SDK 3.9 / Flutter 3.35 or later.

dart mcp-server                                          # runs stdio, start it directly to check it launches
claude mcp add --transport stdio dart -- dart mcp-server # register it for Claude Code

4. iOS Simulator Lane (Your macOS Host over ssh)

No Mac locally? Run everything in this section over ssh on your macOS host; the simulator is still driven from a Linux/CI box's shell, only the xcrun/simctl calls run remotely.

xcrun simctl list devicetypes                     # find a device type id
xcrun simctl list runtimes                          # find an iOS runtime id
xcrun simctl create MyTestPhone "iPhone 15" "iOS-17-5"
xcrun simctl boot MyTestPhone                        # or boot by UDID
xcrun simctl install booted /path/to/App.app
xcrun simctl launch booted com.example.app
xcrun simctl io booted screenshot --type=jpeg out.jpg
xcrun simctl io booted recordVideo out.mp4            # Ctrl-C to stop
xcrun simctl terminate booted com.example.app
xcrun simctl shutdown MyTestPhone

simctl has no touch/text input-injection primitive (no adb input tap/swipe/text equivalent, see §2). Use integration_test/XCUITest-level tooling (or idb) for iOS UI input, not raw simctl calls.

Flutter on the same host: flutter build ios --simulator --debug needs no code signing; flutter test integration_test/ -d <simulator_udid> runs directly against a booted sim. Physical-device builds need a Team ID + provisioning profile. Always target the simulator for agent-driven testing to sidestep signing entirely.

The ssh-Headless Gotcha (Load-Bearing, Verify Before Relying on This)

The iOS Simulator is a GUI app at heart and needs an active macOS GUI session to function, even when every command driving it arrives over ssh:

• someone logged into the graphical console (even locked) → ssh-driven simctl/test-runner commands work fine.
• nobody logged into the GUI → the simulator driver fails to start, surfacing as a driver-startup timeout or a hung simctl/xcodebuild call.
• fix: enable automatic login for a user on your macOS host (System Settings → Users & Groups) so a GUI session always exists after boot/reboot, independent of ssh activity.

First-run gotcha: sudo xcodebuild -license accept is an interactive prompt the first time; accept it once by hand before handing the host to an agent.

Gotchas