Back to Blog
Blog

Flutter Integration Testing: Setup, Examples and Tools

A practical guide to Flutter integration testing: integration_test setup, native dialogs, Patrol vs BugRadar, worked failure examples and CI for iOS and Android.

Written by
Gautam Agarwal
Read time
12 min read
Published
Flutter Integration Testing: Setup, Examples and Tools

Quick answer: Flutter integration testing runs your complete app on a device, emulator or simulator and checks full user journeys, which the Flutter docs also call end to end testing or GUI testing. It proves that your widgets, state, platform code and backend work together in one running app.

Widget tests check each brick. Integration tests check that the finished model stands up when someone picks it up, on a real phone, with real permission prompts and real network calls.

Key Takeaways

  • Flutter has three test layers: unit tests for logic, widget tests for single widgets, and integration tests for the whole app.
  • The official integration_test package runs on the target device and uses flutter_test APIs, yet it stops at native platform UI.
  • Permission dialogs, notifications and platform views need a tool that drives the device, such as Patrol or BugRadar.
  • Start with 3 to 5 vital journeys: sign up, login, the core action and payments.
  • Firebase Test Lab spreads integration_test suites across many devices, and Flutter web and desktop apps run the same tests through ChromeDriver and xvfb.
  • BugRadar runs flows on Flutter builds for iOS and Android: a simulator Runner.app, an .apk, or an .ipa for real iPhones.

What is Flutter integration testing?

Flutter integration testing checks a complete user journey inside a running app. According to the Flutter integration testing docs, unit and widget tests validate individual classes, functions and widgets, while integration tests verify the behavior of the complete app.

Every integration test follows the same three steps:

  1. Build. Compile the app for a simulator, emulator or phone.
  2. Drive. Launch it and perform the user's actions.
  3. Assert. Confirm the expected screen, text or state appears.
__wf_reserved_inherit

Unit, widget and integration tests compared

Test typeWhat it checksRuns onTool
UnitA function, method or classThe Dart VM on your machinetest / flutter_test
WidgetOne widget's rendering and interactionsA test environment on your machineflutter_test
IntegrationThe complete app, end to endA device, emulator or simulatorintegration_test, Patrol, BugRadar

The Flutter testing overview describes all three layers. Unit tests stay fast and cheap, so keep most of your logic there; this guide on emulators vs real devices covers where the rest should run. Integration tests cost more per run, so spend them on journeys that make or lose money; this guide to native mobile app testing shows how teams split the layers.

Where Flutter apps break that widget tests miss

AreaWhat can breakWhy widget tests miss it
Plugins and platform channelsCamera, payments, storage and push behave differently on a deviceWidget tests replace them with fakes
Native platform UIPermission dialogs, notifications and platform viewsThey sit outside the widget tree
Keyboards and safe areasInputs hidden on short screens or under the notchThe test environment lacks a real keyboard and notch
Flavors and configA test build talks to the wrong backendWidget tests skip the build system
PerformanceJank on scroll heavy screensSpeed only shows on a real device

Why integration testing matters for Flutter apps

Flutter draws its own UI, and the OS draws the rest. Permission prompts, notifications, the share sheet and embedded web or map views belong to iOS and Android, outside your widget tree.

Plugins call native code. Camera, payments, push and storage plugins run platform code that widget tests replace with fakes.

Two platforms, two sets of surprises. Keyboards, safe areas and back navigation differ between iOS and Android.

Ways to run Flutter integration tests

Where tests runHowBest for
A connected device or simulatorflutter test integration_testDaily development
Chromeflutter drive --driver=test_driver/integration_test.dart --target=integration_test/app_test.dart -d web-server, with ChromeDriver runningFlutter web apps
Linux desktop in CIflutter test integration_test -d linux, wrapped in xvfb-run so an X server existsDesktop apps
Firebase Test LabYour integration tests across many Android and iOS devicesDevice coverage
BugRadarA written flow against your uploaded build, in the cloud or locallyJourneys that cross native UI and run on every PR

‍

The Flutter docs list Firebase Test Lab as the way to run integration_test suites across many devices, and they cover web and desktop runs in the same guide. Older suites built on flutter_driver should move to integration_test; Flutter publishes a migration guide for that switch.

integration_test vs Patrol vs BugRadar

integration_testPatrolBugRadar
Who makes itThe Flutter team, inside the SDKA third party packageBugRadar
Test formatDart with flutter_test APIsDart, with native automation addedA written flow, in YAML or the dashboard
Finding elementsFinders such as find.byKey and find.textFlutter finders, plus native automationThe agent reads the live screen
Native dialogs and notificationsOutside its reachSupportedPush tested end to end, from permission to tap
Pull request feedbackYour CI job and reporterYour CI job and reporterA PR comment with videos plus a GitHub Check
CostFree, part of the SDKFree packageFree tier, then paid plans

The Flutter docs describe Patrol as a popular third party package that can interact with permission dialogs, notifications and platform views. Pick integration_test for pure Flutter journeys, Patrol when you want Dart tests that reach native UI, and BugRadar when you want flows that adapt to UI changes and report on every pull request.

‍

How to set up Flutter integration testing

Step 1: Add integration_test and write a test

flutter pub add "dev:integration_test:{sdk: flutter}"

```dart

// integration_test/login_test.dart

import 'package:flutter/material.dart';

import 'package:flutter_test/flutter_test.dart';

import 'package:integration_test/integration_test.dart';

import 'package:my_app/main.dart' as app;

void main() {

  IntegrationTestWidgetsFlutterBinding.ensureInitialized();

  testWidgets('login shows home', (tester) async {

    app.main();

    await tester.pumpAndSettle();

    await tester.enterText(find.byKey(const ValueKey('email')), 'test@example.com');

    await tester.enterText(find.byKey(const ValueKey('password')), 'secret123');

    await tester.tap(find.text('Log in'));

    await tester.pumpAndSettle();

    expect(find.text('Home'), findsOneWidget);

  });

}

```

‍

Run it on a connected device or booted simulator with flutter test integration_test/login_test.dart.

Step 2: Write the same journey as a flow

```yaml

# .BugRadar/login.flow.yaml

name: Login

instructions: |

  Log in with test@example.com and password secret123.

  Verify the home screen loads.

```

‍

With BugRadar: a flow describes what the user does and what they should see. The only required keys are name and instructions, and BugRadar flows validate checks the file before you push. Keys like ValueKey('email') stay out of the test entirely.

Step 3: Build for BugRadar

# iOS Simulator: zip build/ios/iphonesimulator/Runner.app

flutter build ios --simulator

‍

# Android: upload build/app/outputs/flutter-apk/app-debug.apk

flutter build apk --debug

Add --flavor to either command if your app uses flavors. For real iPhones, run flutter build ipa --export-method development, since builds with the default app-store export method fail to launch on BugRadar's devices.

With BugRadar: the BugRadar build guide lists every Flutter command. iOS Simulator builds must be arm64, so build on Apple silicon.

Step 4: Run locally, then on every pull request

With BugRadar: boot a simulator or emulator, then run BugRadar up --platform ios and BugRadar run login --local. The CLI detects every booted device, so iOS and Android run the same flow in one pass; this guide to Android emulator setup covers the first step. In CI, the BugRadar GitHub Action uploads each build, and the GitHub bot runs the relevant flows and posts videos plus a GitHub Check on the PR.

Measure performance in the same runs

Integration tests can also verify performance: the Flutter docs include a profiling recipe that records frame timings while a test scrolls through a list.

With BugRadar: every run captures memory, CPU and rendering metrics plus the network requests your app makes, so a slow screen shows up beside the step that triggered it.

__wf_reserved_inherit

The Flutter journey checklist

JourneyWhat to verifyTool that reaches it
Sign up and loginThe user lands on the home screenAny integration test tool
Location, camera or photo permissionsAllow and deny both lead somewhere sensiblePatrol or BugRadar
Push notificationsThe banner opens the right screenBugRadar or physical devices
In-app purchasesPremium unlocks, declines keep it lockedStore sandboxes or BugRadar with RevenueCat Test Store
Small and large screensButtons stay reachable with the keyboard openAny tool, on several simulators
FlavorsThe test flavor talks to the test backendBuilds with --flavor

The guides on push notification testing and in-app purchase testing cover the two hardest rows in depth.

Flutter integration testing examples

Each example starts from a failing run and traces it to a cause and a fix.

Example 1: The test stalls on a location prompt

Scenario: a store finder asks for location access on first launch. The integration_test run stops there.

StepExpectedWhat the run showed
Open the store finderPermission promptPermission prompt
Allow locationMap with nearby storesPrompt still on screen
Tap the nearest storeStore detailsTest timed out

Cause: the prompt is native platform UI, which integration_test leaves outside its reach.

Fix: move permission steps to a tool that drives the device, or grant the permission before the test starts.

With BugRadar: push notification flows on BugRadar cover the permission request, delivery and the tap, as this overview of push notification testing explains.

Example 2: A redesign breaks every login test

Scenario: the design team rebuilds the login screen. The journey stays identical, and 14 tests fail.

StepExpectedWhat the run showed
Find the email fieldField foundValueKey('email') missing
Enter the passwordField filledSkipped
Tap "Log in"Home screenSkipped

Cause: the new widgets dropped the old keys.

Fix: treat keys as a public contract and review them in every UI pull request, or describe the journey instead of the widget tree.

With BugRadar: flows adapt to UI changes as long as the user journey is intact, so the same login flow keeps passing after the redesign.

Example 3: Checkout passes on a large phone and fails on a small one

Scenario: the checkout test passes on an iPhone 16 Pro simulator and fails on an iPhone SE.

StepExpectedWhat the run showed
Enter the card numberField filledField filled
Tap "Pay"Order confirmationKeyboard covers the button
Confirm the orderOrder number shownCheckout screen

Cause: a fixed height column leaves the Pay button under the keyboard on short screens.

Fix: place the form in a scrollable view and test at least one small screen.

With BugRadar: boot an iPhone SE beside an iPhone 16 Pro and an iPad, and one local run covers all three screen sizes.

Example 4: The test run creates real orders

Scenario: an integration suite passes, and the next morning the operations team finds twenty test orders in production.

StepExpectedWhat the run showed
Build the app for testingStaging backendProduction backend
Place a test orderOrder in stagingOrder in production
Check the production order listReal orders onlyTwenty test orders mixed in

Cause: the test build used the default flavor, which points at production.

Fix: build a dedicated test flavor with --flavor staging, and make the flavor visible on a debug screen the tests can assert on.

With BugRadar: the Flutter build commands accept --flavor, so upload the staging flavor's Runner.app and .apk as the test builds.

Common Flutter integration testing problems and fixes

SymptomLikely causeFix
Run stalls on a system promptNative UI outside integration_testUse a device level tool or pre grant the permission
pumpAndSettle times outA looping animation or loaderPump for a fixed duration on that screen
Many tests fail after a redesignRenamed or removed keysKeep keys stable, or describe the journey
iOS build rejected by the cloud simulatorA device build or an x86_64 buildUse flutter build ios --simulator on Apple silicon
Real iPhone build fails to launchDefault app-store export methodExport with --export-method development
Linux CI fails before tests startAn X server is missingWrap the command in xvfb-run
Test data lands in productionThe default flavor points at productionBuild and upload a test flavor

The Flutter integration testing process, summarized

StepWhat you doOutput
1. LayerKeep logic in unit tests, widgets in widget testsA fast base suite
2. WriteCover each vital journey end to endLogin, core action, payment tests
3. BuildCreate simulator, APK and device buildsRunner.app, .apk, .ipa
4. Run locallyRun on several screen sizesA passing first run
5. AutomateRun on every pull requestResults attached to each PR
6. DiagnoseTrace each failure to its causeA fix in the app or the test

Conclusion

Flutter integration testing covers what unit and widget tests leave open: the complete app, on a device, with native UI and platform code in play. Use integration_test for pure Flutter journeys, reach for a device level tool when the OS takes over the screen, and trace every failing run back to its cause.

A good first step this week: build Runner.app and an APK, write your login journey as one BugRadar flow, and run it on a small and a large screen.

__wf_reserved_inherit

FAQs

What is the difference between widget and integration tests in Flutter?

Widget tests check one widget in a test environment; integration tests run the complete app on a device.

Can integration_test tap permission dialogs?

The official package stays inside Flutter's UI; Patrol and BugRadar interact with the whole device screen.

How do you run Flutter integration tests?

Run flutter test integration_test with a device connected or a simulator booted.

Which build does BugRadar need for Flutter?

A zipped simulator Runner.app for iOS, an .apk for Android, or a development .ipa for iPhones.

Can integration tests run on real devices?

Yes. Connect a phone and run them there, or upload a development .ipa to a device cloud.

How many integration tests should a Flutter app have?

Start with 3 to 5 vital journeys: sign up, login, the core action and payment.

‍

‍

Fix bugs, not tests.

Talk to an expert.

Book 30 minutes with our team. We'll show you BugRadar running on your app.

Start building.

Describe a user journey and watch an agent run it on iOS, Android, and web.

Try for free