How to test a Flutter app

Flutter is Google's UI toolkit for building beautiful, natively compiled applications for mobile, web, and desktop from a single codebase.

In this codelab, you'll build and test a simple Flutter app. The app will use the Provider package for managing state.

What you'll learn

  • How to create widget tests using the widget testing framework
  • How to create an integration test to test the app's UI and performance using the integration_test library
  • How to test data classes (providers) with the help of unit tests

What you'll build

In this codelab, you'll start by building a simple application with a list of items. We provide the source code for you so you can get right to the testing. The app supports the following operations:

  • Adding the items to favorites
  • Viewing the list of favorites
  • Removing items from the favorites list

Once the app is complete, you will write the following tests:

  • Unit tests to validate the add and remove operations
  • Widgets tests for the home and favorites pages
  • UI and performance tests for the entire app using integration tests

GIF of the app running on Android

What would you like to learn from this codelab?

I'm new to the topic, and I want a good overview. I know something about this topic, but I want a refresher. I'm looking for an example code to use in my project. I'm looking for an explanation of something specific.

You need two pieces of software to complete this lab: the Flutter SDK, and an editor.

You can run this codelab using any of the following devices:

  • A physical device (Android or iOS) connected to your computer and set to developer mode.
  • The iOS simulator. (Requires installing Xcode tools.)
  • The Android emulator. (Requires setup in Android Studio.)

Create a new Flutter app & update dependencies

This codelab focuses on testing a Flutter mobile app. You will quickly create the app to be tested using source files that you copy and paste. The rest of the codelab then focuses on learning different kinds of testing.

b2f84ff91b0e1396.pngCreate a simple templated Flutter app, using the instructions in Getting Started with your first Flutter app. Name the project testing_app (instead of myapp). You'll be modifying this starter app to create the finished app.

b2f84ff91b0e1396.pngThis codelab is written in null safe Dart, so we convert the generated project to Null Safety as follows:

$ cd testing_app
$ dart migrate --apply-changes

If you are using Flutter 2.2 or above, your sample code will already be null safe, so the above dart migrate will not result in any changes to your source code.

b2f84ff91b0e1396.pngIn your IDE or editor, open the pubspec.yaml file. Add the following dependencies marked as new, then save the file. (You can delete the comments to make the file more readable.)

pubspec.yaml

dependencies:
  flutter:
    sdk: flutter
  cupertino_icons: ^1.0.2
  provider: ^5.0.0            # new

dev_dependencies:
  flutter_test:
    sdk: flutter
  integration_test:           # new
    sdk: flutter              # new
  test: ^1.14.4               # new
  1. Click the Pub get button in your IDE or, at the command line, run flutter pub get from the top of the project.

If this results in an error, make sure that the indentation in your dependencies block is exactly the same as shown above, using spaces (not tabs). YAML files are sensitive to white space.

Next, you'll build out the app so that you can test it. The app contains the following files:

  • lib/main.dart - the main file where the app starts
  • lib/screens/home.dart - creates a list of items
  • lib/screens/favorites.dart - creates the layout for the favorites list
  • lib/models/favorites.dart - creates the model class for favorites list

Replace the contents of lib/main.dart

b2f84ff91b0e1396.pngReplace the contents of lib/main.dart with the following code:

lib/main.dart

import 'package:flutter/material.dart';
import 'package:provider/provider.dart';
import 'package:testing_app/models/favorites.dart';
import 'package:testing_app/screens/favorites.dart';
import 'package:testing_app/screens/home.dart';

void main() {
  runApp(TestingApp());
}

class TestingApp extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return ChangeNotifierProvider<Favorites>(
      create: (context) => Favorites(),
      child: MaterialApp(
        title: 'Testing Sample',
        theme: ThemeData(
          primarySwatch: Colors.blue,
          visualDensity: VisualDensity.adaptivePlatformDensity,
        ),
        routes: {
          HomePage.routeName: (context) => HomePage(),
          FavoritesPage.routeName: (context) => FavoritesPage(),
        },
        initialRoute: HomePage.routeName,
      ),
    );
  }
}

Add the Home page in lib/screens/home.dart

b2f84ff91b0e1396.pngCreate a new directory, screens, in the lib directory and, in that newly created directory, create a new file named home.dart. In lib/screens/home.dart add the following code:

lib/screens/home.dart

import 'package:flutter/material.dart';
import 'package:provider/provider.dart';
import 'package:testing_app/models/favorites.dart';
import 'package:testing_app/screens/favorites.dart';

class HomePage extends StatelessWidget {
  static String routeName = '/';

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: Text('Testing Sample'),
        actions: <Widget>[
          TextButton.icon(
            style: TextButton.styleFrom(primary: Colors.white),
            onPressed: () {
              Navigator.pushNamed(context, FavoritesPage.routeName);
            },
            icon: Icon(Icons.favorite_border),
            label: Text('Favorites'),
          ),
        ],
      ),
      body: ListView.builder(
        itemCount: 100,
        cacheExtent: 20.0,
        padding: const EdgeInsets.symmetric(vertical: 16),
        itemBuilder: (context, index) => ItemTile(index),
      ),
    );
  }
}

class ItemTile extends StatelessWidget {
  final int itemNo;

  const ItemTile(
    this.itemNo,
  );

  @override
  Widget build(BuildContext context) {
    var favoritesList = Provider.of<Favorites>(context);

    return Padding(
      padding: const EdgeInsets.all(8.0),
      child: ListTile(
        leading: CircleAvatar(
          backgroundColor: Colors.primaries[itemNo % Colors.primaries.length],
        ),
        title: Text(
          'Item $itemNo',
          key: Key('text_$itemNo'),
        ),
        trailing: IconButton(
          key: Key('icon_$itemNo'),
          icon: favoritesList.items.contains(itemNo)
              ? Icon(Icons.favorite)
              : Icon(Icons.favorite_border),
          onPressed: () {
            !favoritesList.items.contains(itemNo)
                ? favoritesList.add(itemNo)
                : favoritesList.remove(itemNo);
            ScaffoldMessenger.of(context).showSnackBar(
              SnackBar(
                content: Text(favoritesList.items.contains(itemNo)
                    ? 'Added to favorites.'
                    : 'Removed from favorites.'),
                duration: Duration(seconds: 1),
              ),
            );
          },
        ),
      ),
    );
  }
}

Add the Favorites page in lib/screens/favorites.dart

b2f84ff91b0e1396.pngIn the lib/screens directory create another new file named favorites.dart. In that file add the following code:

lib/screens/favorites.dart

import 'package:flutter/material.dart';
import 'package:provider/provider.dart';
import 'package:testing_app/models/favorites.dart';

class FavoritesPage extends StatelessWidget {
  static String routeName = '/favorites_page';

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: Text('Favorites'),
      ),
      body: Consumer<Favorites>(
        builder: (context, value, child) => ListView.builder(
          itemCount: value.items.length,
          padding: const EdgeInsets.symmetric(vertical: 16),
          itemBuilder: (context, index) => FavoriteItemTile(value.items[index]),
        ),
      ),
    );
  }
}

class FavoriteItemTile extends StatelessWidget {
  final int itemNo;

  const FavoriteItemTile(
    this.itemNo,
  );

  @override
  Widget build(BuildContext context) {
    return Padding(
      padding: const EdgeInsets.all(8.0),
      child: ListTile(
        leading: CircleAvatar(
          backgroundColor: Colors.primaries[itemNo % Colors.primaries.length],
        ),
        title: Text(
          'Item $itemNo',
          key: Key('favorites_text_$itemNo'),
        ),
        trailing: IconButton(
          key: Key('remove_icon_$itemNo'),
          icon: Icon(Icons.close),
          onPressed: () {
            Provider.of<Favorites>(context, listen: false).remove(itemNo);
            ScaffoldMessenger.of(context).showSnackBar(
              SnackBar(
                content: Text('Removed from favorites.'),
                duration: Duration(seconds: 1),
              ),
            );
          },
        ),
      ),
    );
  }
}

Lastly, create the Favorites model in lib/models/favorites.dart

b2f84ff91b0e1396.pngCreate a new directory, models and, in that directory, create a new file named favorites.dart. In that file add the following code:

lib/models/favorites.dart

import 'package:flutter/material.dart';

/// The [Favorites] class holds a list of favorite items saved by the user.
class Favorites extends ChangeNotifier {
  final List<int> _favoriteItems = [];

  List<int> get items => _favoriteItems;

  void add(int itemNo) {
    _favoriteItems.add(itemNo);
    notifyListeners();
  }

  void remove(int itemNo) {
    _favoriteItems.remove(itemNo);
    notifyListeners();
  }
}

The app is now complete, but untested.

b2f84ff91b0e1396.pngRun the app by clicking the Run icon 6869d41b089cc745.png in the editor . The first time you run an app, it can take a while. The app is faster in later steps. It should look like the following screenshot:

be938199b599b605.png

The app shows a list of items. Tap the heart-shaped icon on any row to fill in the heart and add the item to the favorites list. The Favorites button on the AppBar takes you to a second screen containing the favorites list.

The app is now ready for testing. You'll start testing it from the next step.

You'll start by unit testing the favorites model. What is a unit test? A unit test verifies that every individual unit of software (often a function) performs its intended task correctly.

All the test files in a Flutter app (except for integration tests) are placed in the test directory.

Remove test/widget_test.dart

b2f84ff91b0e1396.pngBefore you begin testing, delete the widget_test.dart file. You'll be adding your own test files.

Create a new test file

First, you'll test the add() method in the Favorites model to verify that a new item gets added to the list, and that the list reflects the change. By convention, the directory structure in the test directory mimics that in the lib directory and the Dart files have the same name, but appended with _test.

b2f84ff91b0e1396.pngCreate a models directory in the test directory. In this new directory, create a favorites_test.dart file with the following content:

test/models/favorites_test.dart

import 'package:test/test.dart';
import 'package:testing_app/models/favorites.dart';

void main() {
  group('Testing App Provider', () {
    var favorites = Favorites();

    test('A new item should be added', () {
      var number = 35;
      favorites.add(number);
      expect(favorites.items.contains(number), true);
    });    
  });
}

The Flutter testing framework allows you to bind similar tests related to each other in a group. There can be multiple groups in a single test file intended to test different parts of the corresponding file in the /lib directory.

The test() method takes two positional parameters: the description of the test and the callback where you actually write the test.

b2f84ff91b0e1396.pngTest removing an item from the list. Copy and paste the following test in the same test group. Add the following code to the test file:

test/models/favorites_test.dart

test('An item should be removed', () {
  var number = 45;
  favorites.add(number);
  expect(favorites.items.contains(number), true);
  favorites.remove(number);
  expect(favorites.items.contains(number), false);
});

Run the test

b2f84ff91b0e1396.pngIf your app is running in your emulator or device, close it before continuing.

b2f84ff91b0e1396.pngAt the command line, navigate to the project's root directory and enter the following command:

$ flutter test test/models/favorites_test.dart 

If everything works, you should see a message similar to the following:

00:06 +2: All tests passed!                                                    

The complete test file: test/models/favorites_test.dart.

For more information on unit testing, visit An introduction to unit testing.

In this step you'll be performing widget tests. Widget testing is unique to Flutter, where you can test each and every individual widget of your choice. This step tests the screens (HomePage and FavoritesPage) individually.

Widget testing uses the testWidget() function instead of the test() function. It also takes two parameters: the description, and the callback. But here, the callback takes a WidgetTester as an argument.

Widget tests use TestFlutterWidgetsBinding, a class that provides the same resources to your widgets that they would have in a running app (information about screen size, the ability to schedule animations, and so on), but without the actual app. Instead, a virtual environment is used to run the widget, measure it, and so on, then tests the results. Here, pumpWidget kicks off the process by telling the framework to mount and measure a particular widget just as it would in a complete application.

The widget testing framework provides finders to find widgets (for example, text(), byType(), byIcon()) and also matchers to verify the results.

Start by testing the HomePage widget.

Create a new test file

The first test verifies whether scrolling the HomePage works properly.

b2f84ff91b0e1396.pngCreate a new file in the test directory and name it home_test.dart. In the newly created file, add the following code:

test/home_test.dart

import 'package:flutter/material.dart';
import 'package:flutter_test/flutter_test.dart';
import 'package:provider/provider.dart';
import 'package:testing_app/models/favorites.dart';
import 'package:testing_app/screens/home.dart';

Widget createHomeScreen() => ChangeNotifierProvider<Favorites>(
      create: (context) => Favorites(),
      child: MaterialApp(
        home: HomePage(),
      ),
    );

void main() {
  group('Home Page Widget Tests', () {
    testWidgets('Testing Scrolling', (tester) async {
      await tester.pumpWidget(createHomeScreen());
      expect(find.text('Item 0'), findsOneWidget);
      await tester.fling(find.byType(ListView), Offset(0, -200), 3000);
      await tester.pumpAndSettle();
      expect(find.text('Item 0'), findsNothing);
    });
  });
}

The createHomeScreen() function is used to create an app that loads the widget to be tested in a MaterialApp, wrapped into a ChangeNotifierProvider. The HomePage widget needs both of these widgets to be present above it in the widget tree so it can inherit from them and get access to the data they offer. This function is passed as a parameter to the pumpWidget() function.

Next, test whether the framework can find a ListView rendered onto the screen.

b2f84ff91b0e1396.pngAdd the following code snippet to home_test.dart:

test/home_test.dart

group('Home Page Widget Tests', () {

  // BEGINNING OF NEW CONTENT
  testWidgets('Testing if ListView shows up', (tester) async {  
    await tester.pumpWidget(createHomeScreen());
    expect(find.byType(ListView), findsOneWidget);
  });                                                
  // END OF NEW CONTENT

  testWidgets('Testing Scrolling', (tester) async {       
    await tester.pumpWidget(createHomeScreen());
    expect(find.text('Item 0'), findsOneWidget);
    await tester.fling(find.byType(ListView), Offset(0, -200), 3000);
    await tester.pumpAndSettle();
    expect(find.text('Item 0'), findsNothing);
  });
});

Run the test

You can run widget tests in the same way as unit tests, but using a device or an emulator allows you to watch the test running. It also gives you the ability to use hot restart.

b2f84ff91b0e1396.pngPlug-in your device or start your emulator.

b2f84ff91b0e1396.pngFrom the command line, navigate to the project's root directory and enter the following command:

$ flutter run test/home_test.dart 

If everything works you should see an output similar to the following:

Launching test/home_test.dart on Mi A3 in debug mode...
Running Gradle task 'assembleDebug'...                                  
Running Gradle task 'assembleDebug'... Done                        62.7s
✓ Built build/app/outputs/flutter-apk/app-debug.apk.
Installing build/app/outputs/flutter-apk/app.apk...                 5.8s
Waiting for Mi A3 to report its views...                            16ms
I/flutter ( 1616): 00:00 +0: Home Page Widget Tests Testing if ListView shows up
Syncing files to device Mi A3...                                        
I/flutter ( 1616): 00:02 +1: Home Page Widget Tests Testing Scrolling
Syncing files to device Mi A3...                                                 4,008ms (!)                                       

Flutter run key commands.
r Hot reload. 🔥🔥🔥
R Hot restart.
h Repeat this help message.
d Detach (terminate "flutter run" but leave application running).
c Clear the screen
q Quit (terminate the application on the device).
An Observatory debugger and profiler on Mi A3 is available at:
http://127.0.0.1:40433/KOsGesHSxR8=/
I/flutter ( 1616): 00:00 +0: Home Page Widget Tests Testing if ListView shows up
I/flutter ( 1616): 00:02 +1: Home Page Widget Tests Testing Scrolling
I/flutter ( 1616): 00:09 +3: All tests passed!

Next, you'll make changes to the test file and enter Shift + R to hot restart the app and re-run all the tests.

b2f84ff91b0e1396.pngAdd more tests to the group that tests the HomePage widgets. Copy the following test to your file:

test/home_test.dart

testWidgets('Testing IconButtons', (tester) async {
  await tester.pumpWidget(createHomeScreen());
  expect(find.byIcon(Icons.favorite), findsNothing);
  await tester.tap(find.byIcon(Icons.favorite_border).first);
  await tester.pumpAndSettle(Duration(seconds: 1));
  expect(find.text('Added to favorites.'), findsOneWidget);
  expect(find.byIcon(Icons.favorite), findsWidgets);
  await tester.tap(find.byIcon(Icons.favorite).first);
  await tester.pumpAndSettle(Duration(seconds: 1));
  expect(find.text('Removed from favorites.'), findsOneWidget);
  expect(find.byIcon(Icons.favorite), findsNothing);
});

This test verifies that tapping the IconButton changes from Icons.favorite_border (an open heart) to Icons.favorite (a filled-in heart) and then back to Icons.favorite_border when tapped again.

b2f84ff91b0e1396.pngEnter Shift + R. This hot restarts the app and re-runs all the tests.

The complete test file: test/home_test.dart.

b2f84ff91b0e1396.pngUse the same process to test the FavoritesPage with the following code. Follow the same steps and run it.

test/favorites_test.dart

import 'package:flutter/material.dart';
import 'package:flutter_test/flutter_test.dart';
import 'package:provider/provider.dart';
import 'package:testing_app/models/favorites.dart';
import 'package:testing_app/screens/favorites.dart';

late Favorites favoritesList;

Widget createFavoritesScreen() => ChangeNotifierProvider<Favorites>(
      create: (context) {
        favoritesList = Favorites();
        return favoritesList;
      },
      child: MaterialApp(
        home: FavoritesPage(),
      ),
    );

void addItems() {
  for (var i = 0; i < 10; i += 2) {
    favoritesList.add(i);
  }
}

void main() {
  group('Favorites Page Widget Tests', () {
    testWidgets('Test if ListView shows up', (tester) async {
      await tester.pumpWidget(createFavoritesScreen());
      addItems();
      await tester.pumpAndSettle();
      expect(find.byType(ListView), findsOneWidget);
    });

    testWidgets('Testing Remove Button', (tester) async {
      await tester.pumpWidget(createFavoritesScreen());
      addItems();
      await tester.pumpAndSettle();
      var totalItems = tester.widgetList(find.byIcon(Icons.close)).length;
      await tester.tap(find.byIcon(Icons.close).first);
      await tester.pumpAndSettle();
      expect(tester.widgetList(find.byIcon(Icons.close)).length,
          lessThan(totalItems));
      expect(find.text('Removed from favorites.'), findsOneWidget);
    });
  });
}

This test verifies whether an item disappears when the close (remove) button is pressed.

For more information on widget testing, visit:

Integration tests are used to test how individual pieces of an app work together as a whole. The integration_test library is used to perform integration tests in Flutter. This is Flutter's version of Selenium WebDriver (generic web), Protractor (Angular), Espresso (Android), or Earl Gray (iOS). The package internally uses flutter_driver to drive the test on a device.

Instrument the app

In order to write an integration test, you must first instrument the app. Instrumenting the app means configuring the app so that the driver can access its GUI and functions for the purpose of creating and running an automated test. Integration tests are placed in a directory called integration_test. In this step, you'll add the following files for integration testing:

  • integration_test/driver.dart - Instruments the app
  • integration_test/app_test.dart - Runs the actual tests on the app

b2f84ff91b0e1396.pngCreate a directory called integration_test in the project's root directory. In that newly created directory, create an driver.dart file and add the following code:

integration_test/driver.dart

import 'package:integration_test/integration_test_driver.dart';

Future<void> main() => integrationDriver();

This code enables the integration test driver and then waits for the test to run. The response data is stored in a file named integration_response_data.json after the tests are run.

Write the test

b2f84ff91b0e1396.pngCreate a new file and name it app_test.dart.

integration_test/app_test.dart

import 'package:flutter/material.dart';
import 'package:flutter_test/flutter_test.dart';
import 'package:integration_test/integration_test.dart';
import 'package:testing_app/main.dart';


void main() {
  group('Testing App Performance Tests', () {
    final binding = IntegrationTestWidgetsFlutterBinding.ensureInitialized()
        as IntegrationTestWidgetsFlutterBinding;

    binding.framePolicy = LiveTestWidgetsFlutterBindingFramePolicy.fullyLive;
  });
}

The ensureInitialized() function verifies if the integration test driver is initialized or not, and reinitializes it if necessary. The framePolicy when set to fullyLive from the LiveTestWidgetsFlutterBindingFramePolicy enum, is best suitable for testing heavily-animated situations.

Next, test the scrolling performance of the app and record it using the watchPerformance() function.

b2f84ff91b0e1396.pngPaste the following code into the test group you just created:

integration_test/app_test.dart

testWidgets('Scrolling test', (tester) async {
  await tester.pumpWidget(TestingApp());

  final listFinder = find.byType(ListView);

  await binding.watchPerformance(() async {
    await tester.fling(listFinder, Offset(0, -500), 10000);
    await tester.pumpAndSettle();

    await tester.fling(listFinder, Offset(0, 500), 10000);
    await tester.pumpAndSettle();
  }, reportKey: 'scrolling_summary');
});

This test scrolls through the list of items really fast and then scrolls all the way up. The watchPerformance() function records the actions and generates a timeline summary which is then sent back as response data to the test driver in the driver.dart file.

Next, test the add and remove operations.

b2f84ff91b0e1396.pngPaste the following test into the same group:

integration_test/app_test.dart

testWidgets('Favorites operations test', (tester) async {
  await tester.pumpWidget(TestingApp());

  final iconKeys = [
    'icon_0',
    'icon_1',
    'icon_2',
  ];

  for (var icon in iconKeys) {
    await tester.tap(find.byKey(ValueKey(icon)));
    await tester.pumpAndSettle(Duration(seconds: 1));

    expect(find.text('Added to favorites.'), findsOneWidget);
  }

  await tester.tap(find.text('Favorites'));
  await tester.pumpAndSettle();

  final removeIconKeys = [
    'remove_icon_0',
    'remove_icon_1',
    'remove_icon_2',
  ];

  for (final iconKey in removeIconKeys) {
    await tester.tap(find.byKey(ValueKey(iconKey)));
    await tester.pumpAndSettle(Duration(seconds: 1));

    expect(find.text('Removed from favorites.'), findsOneWidget);
  }
});

Run the test

b2f84ff91b0e1396.pngPlug-in your device or start your emulator.

b2f84ff91b0e1396.pngAt the command line, navigate to the project's root directory and enter the following command:

$ flutter drive --driver integration_test/driver.dart --target integration_test/app_test.dart --profile

If everything works, you should see an output similar to the following:

Running "flutter pub get" in step_07...                            930ms
Running Gradle task 'assembleProfile'...                                
Running Gradle task 'assembleProfile'... Done                      31.3s
✓ Built build/app/outputs/flutter-apk/app-profile.apk (11.3MB).
Installing build/app/outputs/flutter-apk/app.apk...                277ms
VMServiceFlutterDriver: Connecting to Flutter application at http://127.0.0.1:62862/K6QKjUNab8c=/
VMServiceFlutterDriver: Isolate found with number: 1935648057883071
VMServiceFlutterDriver: Isolate is paused at start.
VMServiceFlutterDriver: Attempting to resume isolate
I/flutter (24385): 00:00 +0: Testing App Performance Tests Scrolling test
VMServiceFlutterDriver: Connected to Flutter application.
I/flutter (24385): 00:08 +1: Testing App Performance Tests Favorites operations
test
I/flutter (24385): 00:17 +2: Testing App Performance Tests (tearDownAll)
I/flutter (24385): 00:17 +3: All tests passed!
All tests passed.

After the test completes successfully, the build directory at the root of the project should contain one file named integration_response_data.json. It contains the response data sent back from the test while running, in this case, the scrolling_summary. Open the file with any text editor to view the information. With a more advanced setup, you could save a summary every time the test runs and create a graph of the results.

The complete test file: integration_test/app_test.dart.

For more details on Flutter Driver (Integration) testing, visit:

You've completed the codelab and have learned different ways to test a Flutter app.

What you've learned

  • How to test widgets using the widget testing framework
  • How to test the app's UI using integration tests
  • How to test the app's performance using integration tests
  • How to test providers with the help of unit tests

To learn more about testing in Flutter, visit