Flutter - Momentic
Documentation Index
Fetch the complete documentation index at: /docs/llms.txt
Use this file to discover all available pages before exploring further.
Momentic tests the native build of a Flutter app. The pipeline is: produce an APK (Android) or simulator .app (iOS), upload it to a channel/tag, and run momentic-mobile. Momentic drives the compiled app through the platform driver rather than Flutter-specific test APIs.
Produce a testable build
- Android (APK)
- iOS (simulator .app)
flutter build apk --release
# APK in build/app/outputs/flutter-apk/app-release.apk
flutter build apk --debug also works for local iteration.
flutter build ios --simulator
# .app in build/ios/iphonesimulator/
Builds must target the simulator. A device .ipa cannot run on a simulator and Momentic does not support physical devices.
Upload and run
Add the CLI as a dev dependency so the lockfile pins the version in CI:
npm install --save-dev momentic-mobile
Then upload and run:
npx momentic-mobile assets upload ./build/app/outputs/flutter-apk/app-release.apk \
--channel dev --tag 1.0.0
smoke.test.yaml
fileType: momentic/mobile-test/v2
id: flutter-smoke
description: Open the app and verify the home screen
platform: android
labels: [smoke]
defaultChannel: dev
defaultTag: "1.0.0"
steps:
- openApp: com.example.myapp
- assert: The home screen is visible
npx momentic-mobile run smoke.test.yaml
Flutter pitfalls
- Semantics help identify controls. Momentic uses screenshots and the native accessibility tree. Flutter semantics expose named controls to that tree. Most Material and Cupertino widgets provide semantics; custom
CustomPaintercontent may needSemanticswrappers. If a visible control cannot be resolved, inspect its semantics along with the screenshot. Keyvalues do not reach the accessibility tree.ValueKey('login-button')is invisible to Momentic; keys exist for Flutter’s own finder APIs. For a stable hook, wrap the widget inSemantics(label:)or give it atooltip. Prefer natural-language targets that describe the control and its purpose.- Splash and async init. A Flutter app often shows a splash while
main()awaits. Rather than a fixedwait, assert on the first application screen:assert: The home screen is visiblewith atimeout. - Build-time configuration. Pass test configuration through
--dart-definewhen building. Changes made only in a running DevTools session do not update the uploaded artifact. - Impeller vs. Skia rendering does not change what the accessibility tree exposes; either engine works.
- WebView content on Android needs
WebView.setWebContentsDebuggingEnabled(true).
In CI
.github/workflows/mobile.yml
name: Mobile tests
on: [pull_request]
jobs:
test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: 22.12.0
- uses: actions/setup-java@v4
with:
distribution: temurin
java-version: "17"
- name: Set up Flutter
uses: subosito/flutter-action@v2
with:
channel: stable
- name: Build APK
run: flutter build apk --release
- name: Upload APK to Momentic
run: |
npm install
npx momentic-mobile assets upload ./build/app/outputs/flutter-apk/app-release.apk \
--channel dev --tag ${{ github.sha }}-${{ github.run_id }}-${{ github.run_attempt }}
env:
MOMENTIC_API_KEY: ${{ secrets.MOMENTIC_API_KEY }}
- name: Run mobile tests
run: |
npx momentic-mobile run --labels smoke \
--channel dev --tag ${{ github.sha }}-${{ github.run_id }}-${{ github.run_attempt }} -y
env:
MOMENTIC_API_KEY: ${{ secrets.MOMENTIC_API_KEY }}
--channel/--tag on run select the asset this job just uploaded. iOS builds need runs-on: macos-latest with flutter build ios --simulator before the upload step.