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

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

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.