Flutter validation

Flutter Validation

Prerequisites

Requirement	How to verify
Flutter SDK installed	flutter --version
Dart SDK available	dart --version
Flutter doctor passes	flutter doctor
Connected device or emulator	flutter devices
Android emulator running (if targeting Android)	flutter emulators --launch EMULATOR_ID
iOS Simulator booted (if targeting iOS)	xcrun simctl list devices booted
Evidence directory exists	mkdir -p e2e-evidence

If no device is available, launch an emulator:

# List available emulators
flutter emulators

# Launch a specific emulator
flutter emulators --launch EMULATOR_ID

# Or boot an iOS Simulator directly
xcrun simctl boot "iPhone 16"
open -a Simulator

Confirm a device is now connected:

flutter devices

Which Build Variant When?

Pick the variant that matches the journey you're validating before you start.

• debug + simulator/emulator — fastest; use for most functional journeys (UI, routing, state)
• debug + physical device — required for camera, biometrics, Bluetooth, sensors, real network conditions
• release + simulator/emulator — validates release-mode assertions are stripped, asset bundling, tree-shaking
• release + physical device — final pre-ship check; closest to production
• appbundle (Android) — Play Store submission artifact; validate via internal track only

If unsure, start with debug + simulator/emulator and escalate to device or release only when a journey demands it.

Step 1: Install Dependencies

flutter pub get 2>&1 | tee e2e-evidence/flutter-pub-get.txt

Check result:

if grep -q "Got dependencies" e2e-evidence/flutter-pub-get.txt; then
  echo "PASS: Dependencies resolved"
else
  echo "FAIL: pub get failed — check pubspec.yaml and network access"
  cat e2e-evidence/flutter-pub-get.txt
  exit 1
fi

Step 2: Build

Pick the target platform and mode, then run the matching command.

For the full command matrix (Android APK debug/release, Android AAB, iOS debug-simulator/release-device, Web) with the "Build complete" / "Built build/" grep assertion, see references/build-variants.md — load it before Step 2 if you're building anything other than Android debug APK; the matrix covers every flag combination.

# Example: Android debug APK
flutter build apk --debug 2>&1 | tee e2e-evidence/flutter-build.txt

Check result:

if grep -q "Build complete" e2e-evidence/flutter-build.txt || \
   grep -q "Built build/" e2e-evidence/flutter-build.txt; then
  echo "PASS: Build succeeded"
else
  echo "FAIL: Build failed — read full output above"
  exit 1
fi

Step 3: Run on Device

Launch the app on the connected device or emulator:

flutter run 2>&1 | tee e2e-evidence/flutter-run.txt &
FLUTTER_PID=$!
sleep 10   # Wait for app to fully launch

To target a specific device, use flutter devices to list IDs, then flutter run -d DEVICE_ID.

For device-selection guidance (iOS simulator vs Android emulator vs physical device) and the release-mode (--release) launch pattern, see references/device-and-run.md — load it during Step 3 if you need to target a specific device or validate in release mode; skip if running on the default debug simulator.

Verify the app launched:

if grep -q "Flutter run key commands" e2e-evidence/flutter-run.txt || \
   grep -q "Syncing files to device" e2e-evidence/flutter-run.txt; then
  echo "PASS: App launched on device"
else
  echo "FAIL: App did not launch — check flutter-run.txt for errors"
fi

Step 4: Screenshot Capture

Capture screenshots using flutter screenshot while the app is running:

flutter screenshot --out e2e-evidence/flutter-01-launch-screen.png -d DEVICE_ID

Capture sequential screenshots at each validation point:

flutter screenshot --out e2e-evidence/flutter-01-launch-screen.png -d DEVICE_ID
flutter screenshot --out e2e-evidence/flutter-02-main-view.png -d DEVICE_ID
flutter screenshot --out e2e-evidence/flutter-03-interaction-result.png -d DEVICE_ID

For platform-specific screenshot alternatives when flutter screenshot fails — xcrun simctl io booted screenshot for iOS, adb shell screencap -p + adb pull for Android — see references/flutter-logs-crashes.md — load it during Step 4 only if flutter screenshot errors out or the device doesn't respond; the reference also covers Steps 5-7.

Step 5: Log Streaming

Stream Flutter framework and app logs while the app runs:

flutter logs -d DEVICE_ID 2>&1 | tee e2e-evidence/flutter-app-logs.txt &
LOG_PID=$!
sleep 15
kill $LOG_PID
wait $LOG_PID 2>/dev/null

Check for errors in captured logs:

if grep -iE "flutter error|unhandled exception|fatal|crash" e2e-evidence/flutter-app-logs.txt; then
  echo "FAIL: Errors found in app logs"
else
  echo "PASS: No errors detected in app logs"
fi

For platform-specific log alternatives — adb logcat flutter:V *:S (Android), xcrun simctl spawn booted log stream --predicate 'process == "Runner"' (iOS), plus the error-keyword grep — see references/flutter-logs-crashes.md — load this during Step 5 if flutter logs isn't capturing what you need (e.g. filtered to a process or tag).

Step 6: Widget Tree Inspection

Capture the widget tree for structural validation (debug mode only). Press w in the flutter run console to dump the widget hierarchy, or use adb shell uiautomator dump for an accessibility-tree equivalent.

For the flutter run --debug widget-tree dump flow plus the adb shell uiautomator dump /sdcard/ui-dump.xml + adb pull sequence, see references/flutter-logs-crashes.md — load it during Step 6 if structural UI validation is part of this journey; skip for pure visual validation.

Step 7: Crash Detection

flutter run only surfaces Dart-side exceptions. For release-build crashes you almost always need the native-layer path too.

Dart-side check

if grep -iE "unhandled exception|FlutterError|RenderFlex overflowed|null check operator" \
   e2e-evidence/flutter-run.txt; then
  echo "FAIL: Crash or render error detected in flutter run output"
else
  echo "PASS: No crashes detected in flutter run output"
fi

Native-layer checks (iOS + Android)

# iOS — crash reports land in DiagnosticReports as .ips
find ~/Library/Logs/DiagnosticReports -name "Runner*" -newer e2e-evidence/.flutter-run-start 2>/dev/null \
  | tee e2e-evidence/flutter-ios-crash-reports.txt

# Android — FATAL EXCEPTION lines from the most recent logcat dump
adb logcat -d -s AndroidRuntime:E | tee e2e-evidence/flutter-android-crash.log

If either file is non-empty the app crashed natively even when the Dart run looked clean. For the full variant matrix (multiple devices, filtered logcat tags, symbolicated stack traces) see references/flutter-logs-crashes.md — load it during triage if you need to correlate a stack trace to a Flutter plugin.

Step 8: Stop the App

# Stop flutter run
kill $FLUTTER_PID
wait $FLUTTER_PID 2>/dev/null

# Or terminate from adb (Android)
adb shell am force-stop PACKAGE_NAME

Evidence Quality

GOOD evidence description:

Screenshot shows the home feed screen with a blue AppBar titled "My App", three ListTile rows each with an icon and text label, and a FloatingActionButton in the bottom-right corner.

BAD evidence description:

Screenshot captured.

Every screenshot MUST be accompanied by a description of what is VISIBLE, not what you expect to see.

Common Failures

Symptom	Likely Cause	Fix
flutter pub get fails	Missing dependency, bad pubspec.yaml, or no network	Check pubspec.yaml for typos; verify network access; run flutter pub cache repair
flutter doctor reports issues	Missing SDK, toolchain, or license	Follow flutter doctor --android-licenses and SDK installation instructions
No devices found	No emulator running, device not connected	Run flutter emulators --launch ID or connect physical device with USB debugging
Build fails with Gradle error	Android SDK or build tools version mismatch	Update compileSdkVersion in android/app/build.gradle; run flutter clean
Build fails with Xcode error	Missing provisioning profile or certificate	Run open ios/Runner.xcworkspace and fix signing in Xcode
App crashes on launch	Missing asset, bad route, or uninitialized dependency	Check e2e-evidence/flutter-run.txt for the stack trace
flutter screenshot fails	No device connected or app not running	Verify flutter devices shows the target device and app is active
Black/blank screenshot	App still loading or permission dialog blocking	Add additional sleep before screenshot; dismiss system dialogs
RenderFlex overflow errors	Widget layout exceeds screen bounds	Check for missing Expanded, Flexible, or SingleChildScrollView wrappers
Hot reload instead of fresh launch	flutter run reusing a prior session	Kill prior flutter run process; run flutter clean then rebuild

PASS Criteria Template

• flutter pub get resolves all dependencies without errors
• App builds successfully for target platform (exit code 0, "Build complete" in output)
• App launches on device or emulator without crash
• Launch screen renders with expected content (cite screenshot evidence)
• No unhandled exceptions or FlutterErrors in flutter-run.txt or flutter-app-logs.txt
• No crash logs detected in platform diagnostic reports
• User flow completes end-to-end (cite sequential screenshots)
• No error dialogs visible in any screenshot
• Log streaming captures expected output with no fatal errors
• Widget tree or accessibility dump shows expected UI structure (if applicable)