> Flutter E2E Testing on iOS and Android | Mobilewright
> Canonical: https://mobilewright.dev/guides/flutter-e2e-testing/

Guide

# End-to-end testing for Flutter apps

A passing test on an iPhone simulator and an Android emulator, written once in TypeScript and found by the widget keys you already have.

Last updated: November 15, 2026

## What you will have at the end

One test file that signs in to a Flutter app, passing on iOS and on Android, plus a GitHub Actions workflow that runs it. The test drives the built app from the outside, the way a user does, so it also sees permission prompts and other screens that Flutter does not draw.

Flutter already has a good tool for this, integration\_test, and for many apps it is all you need. This page says when, further down.

We ran steps 1 to 6 on Flutter 3.41, an iPhone 17 simulator and a Pixel 6 emulator. You need the Flutter SDK, Node.js 22.12 or newer, Xcode for iOS and the Android SDK for Android.

## From zero to a passing test

### 1\. Give your widgets keys

If your widgets have keys for widget tests, you are done: in a debug build, getByTestId('email') finds Key('email').

Semantics(identifier:) also works as a test ID, and unlike a key it is still there in a release build. Use it for anything you want to test on a release build too.

```
TextField(
  key: const Key('email'),
  decoration: const InputDecoration(labelText: 'Email'),
),
TextField(
  key: const Key('password'),
  obscureText: true,
  decoration: const InputDecoration(labelText: 'Password'),
),
Semantics(
  identifier: 'sign-in-button',
  child: ElevatedButton(
    key: const Key('sign-in'),
    onPressed: signIn,
    child: const Text('Sign in'),
  ),
),
```

lib/main.dart, the sign-in form

### 2\. Build the app

Build a debug APK and a debug simulator app. Debug matters: Flutter draws its own pixels, and in a debug build Mobilewright reads the widget tree straight from the Dart VM, with keys, labels and widget types.

Zip the simulator app. Mobilewright installs an .apk, an .ipa or a zipped .app.

```
$ flutter build apk --debug
$ flutter build ios --simulator --debug

# Mobilewright installs a simulator app from a zip
$ cd build/ios/iphonesimulator && zip -qr Runner.zip Runner.app
```

Output: build/app/outputs/flutter-apk/app-debug.apk and build/ios/iphonesimulator/Runner.zip

### 3\. Add Mobilewright

Put the tests in an e2e folder inside the Flutter project. The scaffolder asks four questions: TypeScript or JavaScript, iOS or Android, the bundle ID and the tests directory. It finds the bundle ID in your Xcode project.

doctor checks Xcode, the Android SDK and your devices, and prints the fix for anything missing. Boot a simulator and an emulator before you go on; Mobilewright does not start them.

```
$ mkdir e2e && cd e2e
$ npm init mobilewright@latest
$ npx mobilewright doctor
```

### 4\. Point it at both builds

One project per platform. Each has its own bundle ID, because flutter create names them differently: signinDemo on iOS and signin\_demo on Android.

Paths in installApps are relative to the config file.

```
import { defineConfig } from 'mobilewright';

export default defineConfig({
  testDir: './tests',
  timeout: 60_000,
  projects: [
    {
      name: 'ios',
      use: {
        platform: 'ios',
        bundleId: 'com.example.signinDemo',
        installApps: '../build/ios/iphonesimulator/Runner.zip',
      },
    },
    {
      name: 'android',
      use: {
        platform: 'android',
        bundleId: 'com.example.signin_demo',
        installApps: '../build/app/outputs/flutter-apk/app-debug.apk',
      },
    },
  ],
});
```

e2e/mobilewright.config.ts

### 5\. Write the test

The fields are found by their keys and the button by its role and caption. fill works on the obscured password field too.

There are no waits. Every action waits for its element to be visible, enabled and still, and expect retries until it passes or times out.

```
import { test, expect } from '@mobilewright/test';

test('signs in with email and password', async ({ screen }) => {
  await screen.getByTestId('email').fill('ford@milliways.space');
  await screen.getByTestId('password').fill('dont-panic-42');
  await screen.getByRole('button', { name: 'Sign in' }).tap();

  await expect(screen.getByText('Welcome back')).toBeVisible();
});
```

e2e/tests/sign-in.spec.ts

### 6\. Run it

Run one platform at a time with --project. Mobilewright installs the build, launches the app fresh and runs the test.

To run both platforms in one command, pass --workers=2 so each platform gets its own worker.

```
$ npx mobilewright test --project=ios

Running 1 test using 1 worker

  ✓  1 [ios] › tests/sign-in.spec.ts:3:5 › signs in with email and password (9.8s)

  1 passed (16.1s)

$ npx mobilewright test --project=android

Running 1 test using 1 worker

  ✓  1 [android] › tests/sign-in.spec.ts:3:5 › signs in with email and password (10.3s)

  1 passed (16.9s)
```

Real output from our run.

### 7\. Run it in CI

iOS simulators need a macOS runner. Android emulators run faster on Linux runners, which have hardware acceleration.

Each job builds the app, starts a device and runs one project. On a bigger suite, build once and hand the artifact to the test jobs, as our CI guide shows.

```
jobs:
  ios:
    runs-on: macos-latest
    steps:
      - uses: actions/checkout@v4
      - uses: subosito/flutter-action@v2
        with: { channel: stable }
      - run: flutter build ios --simulator --debug
      - run: cd build/ios/iphonesimulator && zip -qr Runner.zip Runner.app
      - run: xcrun simctl boot "iPhone 17"
      - uses: actions/setup-node@v4
        with: { node-version: 24 }
      - run: npm ci
        working-directory: e2e
      - run: npx mobilewright test --project=ios --reporter list,html
        working-directory: e2e
      - uses: actions/upload-artifact@v4
        if: ${{ !cancelled() }}
        with: { name: report-ios, path: e2e/mobilewright-report/ }

  android:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: subosito/flutter-action@v2
        with: { channel: stable }
      - run: flutter build apk --debug
      - uses: actions/setup-node@v4
        with: { node-version: 24 }
      - name: Enable KVM
        run: |
          echo 'KERNEL=="kvm", GROUP="kvm", MODE="0666", OPTIONS+="static_node=kvm"' | sudo tee /etc/udev/rules.d/99-kvm4all.rules
          sudo udevadm control --reload-rules
          sudo udevadm trigger --name-match=kvm
      - uses: reactivecircus/android-emulator-runner@v2
        with:
          api-level: 35
          arch: x86_64
          working-directory: e2e
          script: npm ci && npx mobilewright test --project=android
```

.github/workflows/e2e.yml

## What finds what, in debug and release builds

A debug build exposes the whole widget tree. A release build has no Dart VM service, so Mobilewright falls back to what Flutter publishes to the accessibility tree, and some locators stop matching. We checked the release column on Android.

| In your Flutter code | Mobilewright | Release build (Android) |
| --- | --- | --- |
| Key('email') | getByTestId('email') | Not found (Keys are not part of the accessibility tree) |
| Semantics(identifier: 'sign-in-button') | getByTestId('sign-in-button') | Found |
| InputDecoration(labelText: 'Email') | getByLabel('Email'), getByRole('textfield', { name: 'Email' }) | Not found (Flutter publishes it as a placeholder: getByPlaceholder('Email') finds it) |
| ElevatedButton with Text('Sign in') | getByRole('button', { name: 'Sign in' }) | Found |
| Text('Welcome back') | getByText('Welcome back') | Found |

If the same tests have to pass on debug and release builds, use Semantics identifiers, button roles and visible text, which match in both.

## When integration\_test is enough

integration\_test ships with the Flutter SDK. Tests are Dart, they use the finders you know from widget tests, and they run inside the app, so they need no keys in the accessibility tree and no second toolchain. If your team writes Dart and your app is all Flutter, start there.

Its limit is stated in the Flutter docs: it can't interact with native platform UI, such as permission dialogs, notifications, or platform views. The docs point to the patrol package for that, which stays in Dart.

*   Stay with integration\_test if every screen in the flow is drawn by Flutter, and Dart is the language your team wants tests in.
*   Look at patrol if you hit native dialogs and want to keep writing Dart.
*   Use Mobilewright if the flow leaves Flutter: permission prompts, web views, a native screen or SDK. Or if you also test apps that are not Flutter and want one framework, one runner and one report for all of them.
*   Use Mobilewright if a coding agent explores the app through Mobile MCP and writes the tests. It writes the same locators it used.

## Things that tripped us up

*   The simulator .app has to be zipped. Pointing installApps at Runner.app fails with an EISDIR error.
*   The bundle ID differs per platform. Set bundleId in each project, not once at the top.
*   A system dialog over the app blocks typing, and the Flutter tree does not show it. On a freshly booted emulator, dismiss any "isn't responding" dialog first.
*   To pin an Android emulator, deviceId is the name that npx mobilewright devices prints, which is the AVD name.
*   A release build is fine for buttons and text, but keys and labelText do not come through. See the table above.

## Frequently asked questions

### Can Mobilewright test Flutter apps?

Yes, on iOS and Android. In a debug build Mobilewright reads the widget tree from the Dart VM service, so getByTestId matches widget keys, and getByRole, getByLabel and getByText work as they do for native apps. Release builds work through the accessibility tree, with fewer locators.

### Do I need to change my Flutter app?

No. A debug build needs no changes and no extra packages. If you want test IDs that also work in a release build, add Semantics(identifier: ...) to the widgets you target.

### What is the difference between integration\_test and Mobilewright?

integration\_test runs inside the app, in Dart, and drives the widget tree. It cannot interact with native platform UI such as permission dialogs, notifications or platform views. Mobilewright runs outside the app, in TypeScript, and drives whatever is on screen, including native dialogs and web views.

### Does Mobilewright work with Flutter release builds?

Partly. Release builds have no Dart VM service, so Mobilewright uses the accessibility tree. In our run on Android, buttons, visible text and Semantics identifiers were found; widget keys and a text field's labelText were not.

### Can I use my existing widget keys as test IDs?

Yes, in debug builds. getByTestId('email') matches Key('email'). In release builds use Semantics(identifier: ...) instead, which Flutter exposes to the platform as the resource-id on Android and the accessibilityIdentifier on iOS.

### Can I run Flutter e2e tests on real devices?

Yes. Mobilewright runs on real iOS and Android devices, connected over USB or in a device cloud. On a real iPhone, a debug build asks for Local Network access before its Dart VM service can be reached.

## Keep going

*   [**Setting up CI** — The docs guide: reports, artifacts, sharding and building the app once for all test jobs.](/docs/getting-started/ci)
*   [**Dialogs** — Accept or dismiss permission prompts and alerts with screen.on('dialog').](/docs/guides/dialogs)
*   [**React Native e2e testing** — The same guide for Expo and React Native apps.](/guides/react-native-e2e-testing/)
*   [**Mobile UI testing with coding agents** — Let Claude Code, Codex or Cursor explore the app, then keep the flow as a test.](/guides/mobile-ui-testing-with-claude-code/)
