Flutter

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 CustomPainter content may need Semantics wrappers. If a visible control cannot be resolved, inspect its semantics along with the screenshot.
Key values 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 in Semantics(label:) or give it a tooltip. 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 fixed wait, assert on the first application screen: assert: The home screen is visible with a timeout.
Build-time configuration. Pass test configuration through --dart-define when 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.

Overview

Migrate to Momentic

Frameworks

Use cases

Triage

AI actions

Authentication

Page interactions

Test data & variants

Visual testing

Reporting

Upgrading

Produce a testable build

Upload and run

Flutter pitfalls

In CI

​Produce a testable build

​Upload and run

​Flutter pitfalls

​In CI

​Related

Produce a testable build

Upload and run

Flutter pitfalls

In CI

Related