This guide describes how to run integration tests with your Flutter app. With it, you'll learn how to do the following:

• Set up integration tests.
• Verify if an app displays specific text.
• Tap specific widgets.
• Run integration tests.

The guide references thecounter_app project that comes with Flutter and the Flutterintegration_test package. Theintegration_test package lets you:

• Use theflutter drive command to run tests on a physical device or emulator.
• Run onFirebase Test Lab, to automate testing on a variety of devices.
• Useflutter_test APIs to write tests in a style similar towidget tests.

Integration testing requires an app to test. This example uses the built-inCounter App example that Flutter produces when you run theflutter create command. The counter app allows a user to tap on a button to increase a counter.

1. To create an instance of the built-in Flutter app, run the following command in your terminal:

   $flutter create counter_app

   content_copy

2. Change into thecounter_app directory.

3. Openlib/main.dart in your preferred IDE.

4. Add akey parameter to thefloatingActionButton() widget with an instance of aKey class with a string value ofincrement.

   dart

   floatingActionButton:FloatingActionButton(key:constValueKey('increment'),onPressed:_incrementCounter,tooltip:'Increment',child:constIcon(Icons.add),),

   content_copy

5. Save yourlib/main.dart file.

After these changes, thelib/main.dart file should resemble the following code.

import'package:flutter/material.dart';​voidmain()=>runApp(constMyApp());​classMyAppextendsStatelessWidget{constMyApp({super.key});​@overrideWidgetbuild(BuildContextcontext){returnconstMaterialApp(title:'Counter App',home:MyHomePage(title:'Counter App Home Page'),);}}​classMyHomePageextendsStatefulWidget{constMyHomePage({super.key,requiredthis.title});​finalStringtitle;​@overrideState<MyHomePage>createState()=>_MyHomePageState();}​class_MyHomePageStateextendsState<MyHomePage>{int_counter=0;​void_incrementCounter(){setState((){_counter++;});}​@overrideWidgetbuild(BuildContextcontext){returnScaffold(appBar:AppBar(title:Text(widget.title)),body:Center(child:Column(mainAxisAlignment:MainAxisAlignment.center,children:<Widget>[constText('You have pushed the button this many times:'),Text('$_counter',style:Theme.of(context).textTheme.headlineMedium,),],),),floatingActionButton:FloatingActionButton(// Provide a Key to this button. This allows finding this// specific button inside the test suite, and tapping it.key:constKey('increment'),onPressed:_incrementCounter,tooltip:'Increment',child:constIcon(Icons.add),),);}}

You need to add the testing packages to your new app.

To addintegration_test andflutter_test packages asdev_dependencies usingsdk: flutter, run following command.

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

Output:

Building flutter tool...Resolving dependencies...Got dependencies.Resolving dependencies...+ file 7.0.0+ flutter_driver 0.0.0 from sdk flutter+ fuchsia_remote_debug_protocol 0.0.0 from sdk flutter+ integration_test 0.0.0 from sdk flutter...  test_api 0.6.1 (0.7.1 available)  vm_service 13.0.0 (14.2.1 available)+ webdriver 3.0.3Changed 8 dependencies!7 packages have newer versions incompatible with dependency constraints.Try `flutter pub outdated` for more information.

Updatedpubspec.yaml file:

# ...dev_dependencies:# ... added dependenciesflutter_test:sdk:flutterflutter_lints:^6.0.0integration_test:sdk:flutter# ...

Integration tests reside in a separate directory inside your Flutter project.

1. Create a new directory namedintegration_test.
2. Add empty file namedapp_test.dart in that directory.

The resulting directory tree should resemble the following:

counter_app/  lib/    main.dart  integration_test/    app_test.dart

The integration test file consists of a Dart code file with dependencies onintegration_test,flutter_test, and your app's Dart file.

1. Open yourintegration_test/app_test.dart file in your preferred IDE.

2. Copy the following code and paste it into yourintegration_test/app_test.dart file. The last import should point to themain.dart file of yourcounter_app. (Thisimport points to the example app calledintroduction.)

   integration_test/counter_test.dart

   dart

   import'package:flutter/material.dart';import'package:flutter_test/flutter_test.dart';import'package:how_to/main.dart';import'package:integration_test/integration_test.dart';​voidmain(){IntegrationTestWidgetsFlutterBinding.ensureInitialized();​group('end-to-end test',(){testWidgets('tap on the floating action button, verify counter',(tester,)async{// Load app widget.awaittester.pumpWidget(constMyApp());​// Verify the counter starts at 0.expect(find.text('0'),findsOneWidget);​// Finds the floating action button to tap on.finalfab=find.byKey(constValueKey('increment'));​// Emulate a tap on the floating action button.awaittester.tap(fab);​// Trigger a frame.awaittester.pumpAndSettle();​// Verify the counter increments by 1.expect(find.text('1'),findsOneWidget);});});}

   content_copy

This example goes through three steps:

1. InitializeIntegrationTestWidgetsFlutterBinding. This singleton service executes tests on a physical device.

2. Interact and test widgets using theWidgetTester class.

3. Test the important scenarios.

The integration tests that run vary depending on the platform on which you test.

• To test a desktop platform, use the command line or a CI system.
• To test a mobile platform, use the command line or Firebase Test Lab.
• To test in a web browser, use the command line.

-name:Run Integration Testsuses:username/xvfb-action@v1.1.2with:run:flutter test integration_test -d linux -r github

Building Linux application...Error waiting for a debug connection: The log reader stopped unexpectedly, or never started.

To test on a macOS, Windows, or Linux platform, complete the following tasks.

1. Run the following command from the root of the project.

   $flutter test integration_test/app_test.dart

   content_copy

2. If offered a choice of platform to test, choose the desktop platform. Type1 to choose the desktop platform.

Based on platform, the command result should resemble the following output.

PS C:\path\to\counter_app> flutter test .\integration_test\app_test.dartResolving dependencies...Downloading packages...  flutter_lints 3.0.2 (4.0.0 available)  leak_tracker 10.0.4 (10.0.5 available)  leak_tracker_flutter_testing 3.0.3 (3.0.5 available)  lints 3.0.0 (4.0.0 available)  material_color_utilities 0.8.0 (0.11.1 available)  meta 1.12.0 (1.15.0 available)  test_api 0.7.0 (0.7.1 available)  vm_service 14.2.1 (14.2.2 available)Got dependencies!8 packages have newer versions incompatible with dependency constraints.Try `flutter pub outdated` for more information.Connected devices:Windows (desktop) • windows • windows-x64    • Microsoft Windows [Version 10.0.22631.3593]Chrome (web)      • chrome  • web-javascript • Google Chrome 124.0.6367.207Edge (web)        • edge    • web-javascript • Microsoft Edge 124.0.2478.97[1]: Windows (windows)[2]: Chrome (chrome)[3]: Edge (edge)Please choose one (or "q" to quit): 100:00 +0: loading C:/path/to/counter_app/integration_test/app_test.dart               B00:29 +0: loading C:/path/to/counter_app/counter_app/integration_test/app_test.dart   29.1s√ Built build\windows\x64\runner\Debug\counter_app.exe00:31 +1: All tests passed!

$flutter test integration_testResolving dependencies...Downloading packages...  flutter_lints 3.0.2 (4.0.0 available)> leak_tracker 10.0.4 (was 10.0.0) (10.0.5 available)> leak_tracker_flutter_testing 3.0.3 (was 2.0.1) (3.0.5 available)> leak_tracker_testing 3.0.1 (was 2.0.1)  lints 3.0.0 (4.0.0 available)  material_color_utilities 0.8.0 (0.11.1 available)> meta 1.12.0 (was 1.11.0) (1.15.0 available)> test_api 0.7.0 (was 0.6.1) (0.7.1 available)> vm_service 14.2.1 (was 13.0.0) (14.2.2 available)Changed 6 dependencies!8 packages have newer versions incompatible with dependency constraints.Try `flutter pub outdated` for more information.Connected devices:macOS (desktop)                 • macos                 • darwin-arm64   • macOS 14.4.1 23E224 darwin-arm64Mac Designed for iPad (desktop) • mac-designed-for-ipad • darwin         • macOS 14.4.1 23E224 darwin-arm64Chrome (web)                    • chrome                • web-javascript • Google Chrome 124.0.6367.208No wireless devices were found.[1]: macOS (macos)[2]: Mac Designed for iPad (mac-designed-for-ipad)[3]: Chrome (chrome)Please choose one (or "q" to quit): 100:01 +0: loading /path/to/counter_app/integration_test/app_test.dart        R00:02 +0: loading /path/to/counter_app/integration_test/app_test.dart    846ms00:03 +0: loading /path/to/counter_app/integration_test/app_test.dart        BBuilding macOS application...✓ Built build/macos/Build/Products/Debug/counter_app.app00:32 +1: All tests passed!

$flutter test integration_test/app_test.dartConnected devices:Linux (desktop) • linux  • linux-x64      • Ubuntu 22.04.4 LTS 6.5.0-35-genericChrome (web)    • chrome • web-javascript • Google Chrome 104.0.5112.101[1]: Linux (linux)[2]: Chrome (chrome)Please choose one (or "q" to quit): 100:00 +0: /path/to/counter_app/integration_test/app_test.dart     B00:16 +0: /path/to/counter_app/integration_test/app_test.dart✓ Built build/linux/x64/debug/bundle/counter_app

To test on a real Android device, complete the following tasks.

1. Connect the Android device.

2. Run the following command from the root of the project.

   $flutter test integration_test/app_test.dart

   content_copy

   The result should resemble the following output.

   $flutter test integration_test/app_test.dart00:04 +0: loading /path/to/counter_app/integration_test/app_test.dart00:15 +0: loading /path/to/counter_app/integration_test/app_test.dart00:18 +0: loading /path/to/counter_app/integration_test/app_test.dart   2,387msInstalling build/app/outputs/flutter-apk/app.apk...  612ms00:21 +1: All tests passed!

   content_copy

3. Verify that the test removed the Counter App when it finished. If not, subsequent tests fail. If needed, press on the app and chooseRemove App from the context menu.

To test on a real iOS device, complete the following tasks.

1. Connect the iOS device.

2. Run the following command from the root of the project.

   $flutter test integration_test/app_test.dart

   content_copy

   The result should resemble the following output.

   $flutter test integration_test/app_test.dart00:04 +0: loading /path/to/counter_app/integration_test/app_test.dart00:15 +0: loading /path/to/counter_app/integration_test/app_test.dart00:18 +0: loading /path/to/counter_app/integration_test/app_test.dart   2,387msXcode build done.                                           13.5s00:21 +1: All tests passed!

   content_copy

3. Verify that the test removed the Counter App when it finished. If not, subsequent tests fail. If needed, press on the app and chooseRemove App from the context menu.

To test in a web browser, perform the following steps.

1. InstallChromeDriver into the directory of your choice.

   $npx @puppeteer/browsers install chromedriver@stable

   content_copy

   To simplify the install, this command uses the@puppeteer/browsers Node library.

2. Add the path to ChromeDriver to your$PATH environment variable.

3. Verify the ChromeDriver install succeeded.

   $chromedriver --versionChromeDriver 124.0.6367.60 (8771130bd84f76d855ae42fbe02752b03e352f17-refs/branch-heads/6367@{#798})

   content_copy

4. In yourcounter_app project directory, create a new directory namedtest_driver.

   $mkdir test_driver

   content_copy

5. In this directory, create a new file namedintegration_test.dart.

6. Copy the following code and paste it into yourintegration_test.dart file.

   test_driver/integration_test.dart

   dart

   import'package:integration_test/integration_test_driver.dart';​Future<void>main()=>integrationDriver();

   content_copy

7. Launchchromedriver as follows:

   $chromedriver --port=4444

   content_copy

8. From the root of the project, run the following command:

   $flutter drive \  --driver=test_driver/integration_test.dart \  --target=integration_test/app_test.dart \  -d chrome

   content_copy

   The response should resemble the following output:

   Resolving dependencies...  leak_tracker 10.0.0 (10.0.5 available)  leak_tracker_flutter_testing 2.0.1 (3.0.5 available)  leak_tracker_testing 2.0.1 (3.0.1 available)  material_color_utilities 0.8.0 (0.11.1 available)  meta 1.11.0 (1.14.0 available)  test_api 0.6.1 (0.7.1 available)  vm_service 13.0.0 (14.2.1 available)Got dependencies!7 packages have newer versions incompatible with dependency constraints.Try `flutter pub outdated` for more information.Launching integration_test/app_test.dart on Chrome in debug mode...Waiting for connection from debug service on Chrome...             10.9sThis app is linked to the debug service: ws://127.0.0.1:51523/3lofIjIdmbs=/wsDebug service listening on ws://127.0.0.1:51523/3lofIjIdmbs=/ws00:00 +0: end-to-end test tap on the floating action button, verify counter00:01 +1: (tearDownAll)00:01 +2: All tests passed!All tests passed.Application finished.

   content_copy

   To run this as a headless test, runflutter drive with-d web-server option:

   $flutter drive \  --driver=test_driver/integration_test.dart \  --target=integration_test/app_test.dart \  -d web-server

   content_copy

To learn more, see theRunning Flutter driver tests with web wiki page.

You can use Firebase Test Lab to test Android targets.

Follow the instructions in theAndroid Device Testing section of the README.

1. Launch yourFirebase Console.

2. Create a new Firebase project if necessary.

3. Navigate toQuality > Test Lab.

   

Complete the following steps to upload an Android APK.

1. Create an APK using Gradle.

   // Go to the Android directory which contains the gradlew script$pushd android// Build a debug APK for Flutter with gradlew// Note that a standard --release build will not include package:integration_test$flutter build apk --debug// Build an Android test APK$./gradlew app:assembleAndroidTest// Build a debug APK by passing in an integration test$./gradlew app:assembleDebug -Ptarget=integration_test/<name>_test.dart

   content_copy
   • <name>_test.dart: The file created in theProject Setup section.

2. If needed, pass parameters into the integration test as a comma-separated list. Encode all parameters asbase64.

   $./gradlew project:task -Pdart-defines="{base64 (key=value)}[, ...]"

   content_copy
   • (key=value)}[, ...]: Replace this with a comma-separated list of key value pairs.

3. Return to your previous directory.

   $popd

   content_copy

For additional instructions, see theFirebase Test Lab section of the README.

To use Robo test to run integration tests, complete the following steps.

1. Drag the debug APK from<flutter_project_directory>/build/app/outputs/apk/debug into theAndroid Robo Test target on the web page. For example:

   

2. ClickRun a test.

3. Select theInstrumentation test type.

4. Add the App APK to theApp APK or AAB box.

   <flutter_project_directory>/build/app/outputs/apk/debug/<file>.apk

5. Add the Test APK to theTest APK box.

   <flutter_project_directory>/build/app/outputs/apk/androidTest/debug/<file>.apk

   

6. If a failure occurs, click the red icon to view the output:

   

You can use Firebase Test Lab to test iOS targets.

Follow theiOS Device Testing instructions.

1. Launch yourFirebase Console.

2. Create a new Firebase project if necessary.

3. Navigate toQuality > Test Lab.

   

To learn how to upload tests from a ZIP file, using the Firebase Test Lab Console, consult theFirebase Test Lab iOS instructions.

To learn how to upload tests from a ZIP file from the command line to the Firebase Test Lab Console, consult theiOS Device Testing instructions.