Firestore offers the ability to perform atomic operations — "series of database operations such that either all occurs, or nothing occurs") — in form of Transactions and Batched Writes.

Transactions: a transaction is a set of read and write operations on one or more documents.

Batched Writes: a batched write is a set of write operations on one or more documents.

Source: Firebase Documentation for Transactions and Batched Writes

This article examines how to write unit tests for Firestore Transactions and Batched Writes in Flutter.

We continue from the last article: Mocking and Testing Firestore Operations in Flutter Unit Tests | Part 1 (Documents and Collections) where we looked at how to implement unit tests for Firestore operations involving Documents and Collections.

The article was created using Flutter Channel stable, 2.8.1.

Prerequisites

The prerequisites are the same as in the previous article.

Add the following packages to your pubspec.yaml file and run flutter pub get.

dependencies:
  ...
  cloud_firestore: ^3.1.4
  fake_cloud_firestore: ^1.2.0

dev_dependencies:
  ...
  test:

This adds cloud_firestore which is the Cloud Firestore package, fake_cloud_firestore which is the mock Firestore package and test which is the package used for unit tests.

Problem Statement

We extend our FirestoreService class from the previous article — which performed read and write operations to Firestore using Documents and Collections — to perform read and write operations to Firestore using Transactions and Batched Writes and we want to write a set of unit tests for this class.

The class is shown below (with the Document and Collection part removed for readability):

import 'package:cloud_firestore/cloud_firestore.dart';

class FirestoreService {
  const FirestoreService({required this.firestore});

  final FirebaseFirestore firestore;

  // Document and Collection operations removed for readability

  Future<void> runTransaction({
    required Map<String, dynamic> dataToUpdate,
    required Map<String, dynamic> dataToSet,
    required String collectionPath,
    required String documentPathToUpdate,
    required String documentPathToSetTo,
    required String documentPathToDelete,
  }) async {
    return firestore.runTransaction<void>((transaction) async {
      final DocumentReference documentReferenceToUpdate =
          firestore.collection(collectionPath).doc(documentPathToUpdate);
      final DocumentReference documentReferenceToSetTo =
          firestore.collection(collectionPath).doc(documentPathToSetTo);
      final DocumentReference documentReferenceToDelete =
          firestore.collection(collectionPath).doc(documentPathToDelete);

      final DocumentSnapshot documentSnapshotForUpdate =
          await transaction.get(documentReferenceToUpdate);

      final Map<String, dynamic> dataInDocumentPathToUpdate =
          documentSnapshotForUpdate.data() as Map<String, dynamic>;

      final Map<String, dynamic> updatedData = {
        ...dataInDocumentPathToUpdate,
        ...dataToUpdate
      };

      transaction.update(documentReferenceToUpdate, updatedData);

      transaction.set(documentReferenceToSetTo, dataToSet);

      transaction.delete(documentReferenceToDelete);
    });
  }

  Future<void> runBatchedWrite({
    required Map<String, dynamic> dataToSet,
    required Map<String, dynamic> dataToUpdate,
    required String collectionPath,
    required String documentPathToSetTo,
    required String documentPathToUpdate,
    required String documentPathToDelete,
  }) async {
    final WriteBatch writeBatch = firestore.batch();

    final CollectionReference collectionReference =
        firestore.collection(collectionPath);

    final DocumentReference documentReferenceToSetTo =
        collectionReference.doc(documentPathToSetTo);
    final DocumentReference documentReferenceToUpdate =
        collectionReference.doc(documentPathToUpdate);
    final DocumentReference documentReferenceToDelete =
        collectionReference.doc(documentPathToDelete);

    writeBatch.set(documentReferenceToSetTo, dataToSet);

    writeBatch.update(documentReferenceToUpdate, dataToUpdate);

    writeBatch.delete(documentReferenceToDelete);

    await writeBatch.commit();
  }
}

Understanding The Methods

This section helps understand the runTransaction and the runBatchedWrite methods with regards to what is expected for unit testing them.

runTransaction

 Future<void> runTransaction({
    required Map<String, dynamic> dataToUpdate,
    required Map<String, dynamic> dataToSet,
    required String collectionPath,
    required String documentPathToUpdate,
    required String documentPathToSetTo,
    required String documentPathToDelete,
  }) async {
    return firestore.runTransaction<void>((transaction) async {
      final DocumentReference documentReferenceToUpdate =
          firestore.collection(collectionPath).doc(documentPathToUpdate);
      final DocumentReference documentReferenceToSetTo =
          firestore.collection(collectionPath).doc(documentPathToSetTo);
      final DocumentReference documentReferenceToDelete =
          firestore.collection(collectionPath).doc(documentPathToDelete);

      final DocumentSnapshot documentSnapshotForUpdate =
          await transaction.get(documentReferenceToUpdate);

      final Map<String, dynamic> dataInDocumentPathToUpdate =
          documentSnapshotForUpdate.data() as Map<String, dynamic>;

      final Map<String, dynamic> updatedData = {
        ...dataInDocumentPathToUpdate,
        ...dataToUpdate
      };

      transaction.update(documentReferenceToUpdate, updatedData);

      transaction.set(documentReferenceToSetTo, dataToSet);

      transaction.delete(documentReferenceToDelete);
    });
  }

The runTransaction method demonstrates how to do transactions in Firestore. Since transactions allow you to perform read operations and writes operations, the runTransaction method has both read and write operations in it.

The major operations in this method are below:

• The transaction reads the data at documentPathToUpdate and merges it with dataToUpdate and updates the document there.
• The transaction sets dataToSet to the document at the documentPathToSetTo.
• The transaction deletes the document at documentPathToDelete.

runBatchedWrite

  Future<void> runBatchedWrite({
    required Map<String, dynamic> dataToSet,
    required Map<String, dynamic> dataToUpdate,
    required String collectionPath,
    required String documentPathToSetTo,
    required String documentPathToUpdate,
    required String documentPathToDelete,
  }) async {
    final WriteBatch writeBatch = firestore.batch();

    final CollectionReference collectionReference =
        firestore.collection(collectionPath);

    final DocumentReference documentReferenceToSetTo =
        collectionReference.doc(documentPathToSetTo);
    final DocumentReference documentReferenceToUpdate =
        collectionReference.doc(documentPathToUpdate);
    final DocumentReference documentReferenceToDelete =
        collectionReference.doc(documentPathToDelete);

    writeBatch.set(documentReferenceToSetTo, dataToSet);

    writeBatch.update(documentReferenceToUpdate, dataToUpdate);

    writeBatch.delete(documentReferenceToDelete);

    await writeBatch.commit();
  }

The runBatchedWrite method demonstrates how to perform batched writes in Firestore. Since batched writes allow you to perform only write operations, the runBatchedWrite method contains only write operations.

The major operations in this method are below:

• The batched write updates the document at documentPathToUpdate with dataToUpdate.
• The batched write sets dataToSet to the document at the documentPathToSetTo.
• The batched write deletes the document at documentPathToDelete.

Testing Approach

Just as it was outlined in the previous article, we do the following to test the methods:

• Construction Injection:

  The FakeFirebaseFirestore object is passed into the FirestoreService instance to mock the FirebaseFirestore object.

• Mocking Strategy & Database State Set Up:

  Data is added to specific document/collection paths in the FakeFirebaseFirestore object before carrying out the operation in the FirestoreService class.

  Data is then retrieved from the FakeFirebaseFirestore object at specific paths to compare them with the expected values by asserting that they are the same.

The two methods above, individually, contain different read and/or write operations and those are the operations that will be tested.

The tests will be written in the same test file from the previous article

Testing the Transactions and Batched Writes class

Test For Running A Transaction

runTransaction's Test

The runTransaction method can be tested by:

• Injecting the mock Firestore object, fakeFirebaseFirestore, to the service.
• Prepopulating the document at documentPathToUpdate via the fakeFirebaseFirestore object with the data object.
• Prepopulating the document at documentPathToDelete via the fakeFirebaseFirestore object with the data object.
• Running the runTransaction method and passing dataToUpdateWith and dataToSet which will be used by the method to write to documentPathToUpdate and documentPathToSetTo.
• Retrieving the actual data contained in the documentPathToUpdate, documentPathToSetTo and documentPathToDelete document paths.
• Asserting that the data in documentPathToUpdate is equal to the expected updated data, expectedUpdatedData i.e dataToUpdateWith merged with data.
• Asserting that the data in documentPathToSetTo is equal to the expected set data i.e dataToSet.
• Asserting that the data in documentPathToDelete is null.

This is shown below:

 test('runTransaction runs the correct transaction operation', () async {
  final FirestoreService firestoreService =
      FirestoreService(firestore: fakeFirebaseFirestore!);

  const String collectionPath = 'collectionPath';
  const String documentPathToUpdate = 'documentPathToUpdate';
  const String documentPathToSetTo = 'documentPathToSetTo';
  const String documentPathToDelete = 'documentPathToDelete';

  final CollectionReference collectionReference =
      fakeFirebaseFirestore!.collection(collectionPath);

  final DocumentReference documentReferenceToUpdate =
      collectionReference.doc(documentPathToUpdate);
  final DocumentReference documentReferenceToSetTo =
      collectionReference.doc(documentPathToSetTo);
  final DocumentReference documentReferenceToDelete =
      collectionReference.doc(documentPathToDelete);

  documentReferenceToUpdate.set(data);
  documentReferenceToDelete.set(data);

  const Map<String, dynamic> dataToUpdateWith = {'updated_data': '43'};
  const Map<String, dynamic> dataToSet = {'data': 44};

  const Map<String, dynamic> expectedUpdatedData = {
    ...data,
    ...dataToUpdateWith
  };

  await firestoreService.runTransaction(
      dataToUpdate: dataToUpdateWith,
      dataToSet: dataToSet,
      collectionPath: collectionPath,
      documentPathToUpdate: documentPathToUpdate,
      documentPathToSetTo: documentPathToSetTo,
      documentPathToDelete: documentPathToDelete);

  final DocumentSnapshot documentSnapshotForUpdate =
      await documentReferenceToUpdate.get();
  final DocumentSnapshot documentSnapshotForSet =
      await documentReferenceToSetTo.get();
  final DocumentSnapshot documentSnapshotForDelete =
      await documentReferenceToDelete.get();

  final actualDataFromUpdate = documentSnapshotForUpdate.data();
  final actualDataFromSet = documentSnapshotForSet.data();
  final actualDataFromDelete = documentSnapshotForDelete.data();

  expect(actualDataFromUpdate, expectedUpdatedData);
  expect(actualDataFromSet, dataToSet);
  expect(actualDataFromDelete, null);
});

Test For Running A Batched Write

runBatchedWrite's Test

The runBatchedWrite method can be tested by:

• Injecting the mock Firestore object, fakeFirebaseFirestore, to the service.
• Prepopulating the document at documentPathToUpdate via the fakeFirebaseFirestore object with the data object.
• Prepopulating the document at documentPathToDelete via the fakeFirebaseFirestore object with the data object.
• Running the runBatchedWrite method and passing dataToUpdateWith and dataToSet which will be used by the method to write to documentPathToUpdate and documentPathToSetTo.
• Retrieving the actual data contained in the documentPathToUpdate, documentPathToSetTo and documentPathToDelete document paths.
• Asserting that the data in documentPathToUpdate is equal to the expected updated data, expectedUpdatedData i.e dataToUpdateWith merged with data.
• Asserting that the data in documentPathToSetTo is equal to the expected set data i.e dataToSet.
• Asserting that the data in documentPathToDelete is null.

This is shown below:

 test('runBatchedWrite runs the correct batched write operation',
    () async {
  final FirestoreService firestoreService =
      FirestoreService(firestore: fakeFirebaseFirestore!);
  const String collectionPath = 'collectionPath';
  const String documentPathToUpdate = 'documentPathToUpdate';
  const String documentPathToSetTo = 'documentPathToSetTo';
  const String documentPathToDelete = 'documentPathToDelete';

  final CollectionReference collectionReference =
      fakeFirebaseFirestore!.collection(collectionPath);

  final DocumentReference documentReferenceToUpdate =
      collectionReference.doc(documentPathToUpdate);
  final DocumentReference documentReferenceToSetTo =
      collectionReference.doc(documentPathToSetTo);
  final DocumentReference documentReferenceToDelete =
      collectionReference.doc(documentPathToDelete);

  documentReferenceToUpdate.set(data);
  documentReferenceToDelete.set(data);

  const Map<String, dynamic> dataToUpdateWith = {'updated_data': '43'};
  const Map<String, dynamic> dataToSet = {'data': 44};

  const Map<String, dynamic> expectedUpdatedData = {
    ...data,
    ...dataToUpdateWith
  };

  await firestoreService.runBatchedWrite(
      dataToUpdate: dataToUpdateWith,
      dataToSet: dataToSet,
      collectionPath: collectionPath,
      documentPathToUpdate: documentPathToUpdate,
      documentPathToSetTo: documentPathToSetTo,
      documentPathToDelete: documentPathToDelete);

  final DocumentSnapshot documentSnapshotForUpdate =
      await documentReferenceToUpdate.get();
  final DocumentSnapshot documentSnapshotForSet =
      await documentReferenceToSetTo.get();
  final DocumentSnapshot documentSnapshotForDelete =
      await documentReferenceToDelete.get();

  final actualDataFromUpdate = documentSnapshotForUpdate.data();
  final actualDataFromSet = documentSnapshotForSet.data();
  final actualDataFromDelete = documentSnapshotForDelete.data();

  expect(actualDataFromUpdate, expectedUpdatedData);
  expect(actualDataFromSet, dataToSet);
  expect(actualDataFromDelete, null);
});

Complete Test File

The content of the entire test file is shown below:

import 'package:cloud_firestore/cloud_firestore.dart';
import 'package:fake_cloud_firestore/fake_cloud_firestore.dart';
import 'package:firestore_unit_test_flutter/firestore_service.dart';
import 'package:flutter/foundation.dart';
import 'package:test/test.dart';

void main() {
  group('FirestoreService', () {
    FakeFirebaseFirestore? fakeFirebaseFirestore;
    const Map<String, dynamic> data = {'data': '42'};

    setUp(() {
      fakeFirebaseFirestore = FakeFirebaseFirestore();
    });

    // Document operations and Collection operations tests removed for readability

    group('Transaction Operation', () {
      test('runTransaction runs the correct transaction operation', () async {
        final FirestoreService firestoreService =
            FirestoreService(firestore: fakeFirebaseFirestore!);

        const String collectionPath = 'collectionPath';
        const String documentPathToUpdate = 'documentPathToUpdate';
        const String documentPathToSetTo = 'documentPathToSetTo';
        const String documentPathToDelete = 'documentPathToDelete';

        final CollectionReference collectionReference =
            fakeFirebaseFirestore!.collection(collectionPath);

        final DocumentReference documentReferenceToUpdate =
            collectionReference.doc(documentPathToUpdate);
        final DocumentReference documentReferenceToSetTo =
            collectionReference.doc(documentPathToSetTo);
        final DocumentReference documentReferenceToDelete =
            collectionReference.doc(documentPathToDelete);

        documentReferenceToUpdate.set(data);
        documentReferenceToDelete.set(data);

        const Map<String, dynamic> dataToUpdateWith = {'updated_data': '43'};
        const Map<String, dynamic> dataToSet = {'data': 44};

        const Map<String, dynamic> expectedUpdatedData = {
          ...data,
          ...dataToUpdateWith
        };

        await firestoreService.runTransaction(
            dataToUpdate: dataToUpdateWith,
            dataToSet: dataToSet,
            collectionPath: collectionPath,
            documentPathToUpdate: documentPathToUpdate,
            documentPathToSetTo: documentPathToSetTo,
            documentPathToDelete: documentPathToDelete);

        final DocumentSnapshot documentSnapshotForUpdate =
            await documentReferenceToUpdate.get();
        final DocumentSnapshot documentSnapshotForSet =
            await documentReferenceToSetTo.get();
        final DocumentSnapshot documentSnapshotForDelete =
            await documentReferenceToDelete.get();

        final actualDataFromUpdate = documentSnapshotForUpdate.data();
        final actualDataFromSet = documentSnapshotForSet.data();
        final actualDataFromDelete = documentSnapshotForDelete.data();

        expect(actualDataFromUpdate, expectedUpdatedData);
        expect(actualDataFromSet, dataToSet);
        expect(actualDataFromDelete, null);
      });
    });

    group('Batched Write Operation', () {
      test('runBatchedWrite runs the correct batched write operation',
          () async {
        final FirestoreService firestoreService =
            FirestoreService(firestore: fakeFirebaseFirestore!);
        const String collectionPath = 'collectionPath';
        const String documentPathToUpdate = 'documentPathToUpdate';
        const String documentPathToSetTo = 'documentPathToSetTo';
        const String documentPathToDelete = 'documentPathToDelete';

        final CollectionReference collectionReference =
            fakeFirebaseFirestore!.collection(collectionPath);

        final DocumentReference documentReferenceToUpdate =
            collectionReference.doc(documentPathToUpdate);
        final DocumentReference documentReferenceToSetTo =
            collectionReference.doc(documentPathToSetTo);
        final DocumentReference documentReferenceToDelete =
            collectionReference.doc(documentPathToDelete);

        documentReferenceToUpdate.set(data);
        documentReferenceToDelete.set(data);

        const Map<String, dynamic> dataToUpdateWith = {'updated_data': '43'};
        const Map<String, dynamic> dataToSet = {'data': 44};

        const Map<String, dynamic> expectedUpdatedData = {
          ...data,
          ...dataToUpdateWith
        };

        await firestoreService.runBatchedWrite(
            dataToUpdate: dataToUpdateWith,
            dataToSet: dataToSet,
            collectionPath: collectionPath,
            documentPathToUpdate: documentPathToUpdate,
            documentPathToSetTo: documentPathToSetTo,
            documentPathToDelete: documentPathToDelete);

        final DocumentSnapshot documentSnapshotForUpdate =
            await documentReferenceToUpdate.get();
        final DocumentSnapshot documentSnapshotForSet =
            await documentReferenceToSetTo.get();
        final DocumentSnapshot documentSnapshotForDelete =
            await documentReferenceToDelete.get();

        final actualDataFromUpdate = documentSnapshotForUpdate.data();
        final actualDataFromSet = documentSnapshotForSet.data();
        final actualDataFromDelete = documentSnapshotForDelete.data();

        expect(actualDataFromUpdate, expectedUpdatedData);
        expect(actualDataFromSet, dataToSet);
        expect(actualDataFromDelete, null);
      });
    });
  });
}

// MapListContains Matcher code removed for readability

Conclusion

This article demonstrates how to write unit tests for Firebase Firestore's atomic operations, that is, Transactions and Batched Writes.

The complete code can be found on GitHub.

This article examines Firestore operations with respect to Documents and Collections and demonstrates how to mock and test them.

The article was created using Flutter Channel stable, 2.8.1.

Prerequisites

Add the following packages to your pubspec.yaml file and run flutter pub get.

dependencies:
  ...
  cloud_firestore: ^3.1.4

dev_dependencies:
  ...
  test:
  fake_cloud_firestore: ^1.2.0

This adds cloud_firestore which is the Cloud Firestore package, test which is the package used for unit tests and fake_cloud_firestore which is the mock Firestore package.

Problem Statement

We have a class FirestoreService which performs read and write operations to Firestore and we want to write a set of unit tests for this class.

The class is shown below:

import 'package:cloud_firestore/cloud_firestore.dart';

class FirestoreService {
  const FirestoreService({required this.firestore});

  final FirebaseFirestore firestore;

  /// Collection Operations

  Future<DocumentReference<Map<String, dynamic>>> addToCollection(
      {required Map<String, dynamic> data,
      required String collectionPath}) async {
    return firestore.collection(collectionPath).add(data);
  }

  Future<QuerySnapshot<Map<String, dynamic>>> getFromCollection(
      {required String collectionPath}) {
    return firestore.collection(collectionPath).get();
  }

  Stream<QuerySnapshot<Map<String, dynamic>>> getSnapshotStreamFromCollection(
      {required String collectionPath}) {
    return firestore.collection(collectionPath).snapshots();
  }

  /// Document Operations

  Future<void> deleteDocumentFromCollection(
      {required String collectionPath, required String documentPath}) async {
    return firestore.collection(collectionPath).doc(documentPath).delete();
  }

  Future<DocumentSnapshot<Map<String, dynamic>>> getFromDocument(
      {required String collectionPath, required String documentPath}) {
    return firestore.collection(collectionPath).doc(documentPath).get();
  }

  Future<void> setDataOnDocument(
      {required Map<String, dynamic> data,
      required String collectionPath,
      required String documentPath}) {
    return firestore.collection(collectionPath).doc(documentPath).set(data);
  }

  Stream<DocumentSnapshot<Map<String, dynamic>>> getSnapshotStreamFromDocument(
      {required String collectionPath, required String documentPath}) {
    return firestore.collection(collectionPath).doc(documentPath).snapshots();
  }

  Future<void> updateDataOnDocument(
      {required Map<String, dynamic> data,
      required String collectionPath,
      required String documentPath}) {
    return firestore.collection(collectionPath).doc(documentPath).update(data);
  }
}

Testing Approach

Construction Injection

Since the class FirestoreService injects the Firestore object through its constructor, we can pass the FakeFirebaseFirestore object from the fake_cloud_firestore package and use that to test the methods in the class.

Mocking Strategy

The FakeFirebaseFirestore object works like the Firestore object and the read and write operations that can be used to retrieve and add data to the Firestore object can also be used to retrieve and add data to the FakeFirebaseFirestore object.

This helps us prepopulate the mock object right before we call our methods and helps confirm the expected state of the Firestore database.

Database State Set Up

• Initial State

  The initial state of the FakeFirebaseFirestore object can be set up by calling the regular write operations on the CollectionReference and DocumentReference.

  For instance, we want the initial state of the database to have an object {answer: 42} written to a document lifeTheUniverseAndEverything in collection answers, we write the code below to set it up:

  final FakeFirebaseFirestore fakeFirebaseFirestore = FakeFirebaseFirestore();
  
  const String collectionPath = 'answers';
  const String documentPath = 'lifeTheUniverseAndEverything';
  
  const Map<String, dynamic> data = {'answer': 42};
  
  await fakeFirebaseFirestore
      .collection(collectionPath)
      .doc(documentPath)
      .set(data);
  

• Final State

  The final state of the FakeFirebaseFirestore object can be gotten by calling the regular read operations on the CollectionReference and DocumentReference.

  Now, to get the final state of the FakeFirebaseFirestore object from above, we write the code below:

  final DocumentSnapshot<Map<String, dynamic>> documentSnapshot =
      await fakeFirebaseFirestore
          .collection(collectionPath)
          .doc(documentPath)
          .get();
  final Map<String, dynamic> actualData = documentSnapshot.data()!;
  
  print(actualData); // {'answer': 42}
  

• Assertion

  Once we have our data, our database's initial state set up and the final state retrieved, we can assert that the data in the database matches the expected data.

  Going by what we have above, we can write the assertion using the test package's expect method like below:

  expect(actualData, data);  /// Passes ✅
  

Testing The FirestoreService Class

We will test the FirestoreService class by following the approach described in the Testing Approach section above.

This section will be divided into three:

• Set-up (where the objects needed for the tests are created)
• Collection Operations Testing (where operations involving Collections are tested)
• Document Operations Testing (where operations involving Documents are tested)

Set-up

Create a test file firestore_service_test.dart and add the following code to it:

import 'package:fake_cloud_firestore/fake_cloud_firestore.dart';
import 'package:test/test.dart';

void main() {
  group('FirestoreService', () {
    FakeFirebaseFirestore? fakeFirebaseFirestore;
    const Map<String, dynamic> data = {'data': '42'};

    setUp(() {
      fakeFirebaseFirestore = FakeFirebaseFirestore();
    });
  });
}

This creates the FakeFirebaseFirestore object and the data needed for every test we'll write for the FirestoreService class. All of the tests are put inside the "FirestoreService" group.

Collection Operations Testing

• Map Equality

  This section will be testing Collection operations and this means we will be asserting that the collection contains the data. Typically, that is done by using the contains matcher.

  Returns a matcher that matches if the match argument contains the expected value.

  This is how an assertion using the contains matcher would be written:

  final List<int> intList = [1, 2];
  final int intData = 2;
  
  expect(intList, contains(intData));  /// Passes ✅
  

  This passes but when it comes to Lists of Maps, it's a different case.

  The assertion below fails:

  final List<Map<String, dynamic>> mapList = [
      {'data': 42}
  ];
  final mapData = {'data': 42};
  expect(mapList, contains(mapData)); /// Fails ❌
  

  This is because the contains matcher for Lists is implemented this way:

  return item.contains(_expected);
  

  which in turn uses the contains method on List which is implemented like below:

  bool contains(Object? element) {
   for (E e in this) {
     if (e == element) return true;
   }
   return false;
  }
  

  The code above checks that the e object is the same object as the element object. And the mapData object won't be the same as the one contained in the List. That explains why the test fails.

• mapEquals

  In order to get around this, we can make use of the mapEquals function that does the following:

  Compares two maps for element-by-element equality.

  Returns true if the maps are both null, or if they are both non-null, they have the same lengths and they contain the same keys associated with the same values. Returns false otherwise.

  We can check if any of the element in the list is equal to the mapData object by using the mapEquals function like this:

   final List<Map<String, dynamic>> mapList = [
           {'data': 42}
   ];
   final mapData = {'data': 42};
   expect(mapList.any((element) => mapEquals(element, mapData)), true); /// Passes ✅
  

  This test passes because the equality check using mapEquals compares the two Map objects by confirming that the keys and values are the same.

• Custom Matcher

  While using the check above would work for our tests, it's cleaner and more readable to follow the Flutter convention of using a Matcher to assert our test.

  We move the logic mapList.any((element) => mapEquals(element, mapData)) into the Matcher like this below:

   class MapListContains extends Matcher {
     final Map<dynamic, dynamic> _expected;
  
     const MapListContains(this._expected);
  
     @override
     Description describe(Description description) {
       return description.add('contains ').addDescriptionOf(_expected);
     }
  
     @override
     bool matches(dynamic item, Map matchState) {
       if (item is List<Map>) {
         return item.any((element) => mapEquals(element, _expected));
       }
       return false;
     }
   }
  

  The MapListContains class extends the Matcher abstract class and overrides the describe method and the matches method. The assertion logic is implemented in the matches method in the MapListContains class.

  So we can update the test to this below:

   final List<Map<String, dynamic>> mapList = [
           {'data': 42}
   ];
   final mapData = {'data': 42};
   expect(mapList, MapListContains(mapData));  /// Passes ✅
  

  And this test passes.

• Set-up

  Now, we move to the actual test set-up.

  We first create a group "Collection Operations" to hold tests for collection operations.

  import 'package:fake_cloud_firestore/fake_cloud_firestore.dart';
  import 'package:test/test.dart';
  
  void main() {
    group('FirestoreService', () {
      FakeFirebaseFirestore? fakeFirebaseFirestore;
      const Map<String, dynamic> data = {'data': '42'};
  
      setUp(() {
         fakeFirebaseFirestore = FakeFirebaseFirestore();
      });
  
      group('Collection Operations', () {
  
      });
    });
   }
  

  We, can add each test inside of the group.

• Test For Adding To A Collection.

   Future<DocumentReference<Map<String, dynamic>>> addToCollection(
      {required Map<String, dynamic> data,
       required String collectionPath}) async {
     return firestore.collection(collectionPath).add(data);
   }
  

  The addToCollection method above can be tested by:

  • Injecting the mock Firestore object, fakeFirebaseFirestore, to the service.
  • Adding the data to the collection via the service's addToCollection method.
  • Retrieving the actual data list in the collection via fakeFirebaseFirestore.
  • Asserting that the actual data list contains the added data using the MapListContains matcher.

  This is shown below:

   test('addToCollection adds data to given collection', () async {
       final FirestoreService firestoreService =
              FirestoreService(firestore: fakeFirebaseFirestore!);
       const String collectionPath = 'collectionPath';
  
       await firestoreService.addToCollection(
              data: data, collectionPath: collectionPath);
  
       final List<Map<String, dynamic>> actualDataList =
              (await fakeFirebaseFirestore!.collection('collectionPath').get())
                  .docs
                  .map((e) => e.data())
                  .toList();
  
       expect(actualDataList, const MapListContains(data));  /// Passes ✅
   });
  

• Test For Getting Data From A Collection.

  Future<QuerySnapshot<Map<String, dynamic>>> getFromCollection() {
    return firestore.collection('collectionPath').get();
  }
  

  The getFromCollection method above can be tested by:

  • Injecting the mock Firestore object, fakeFirebaseFirestore, to the service.
  • Adding the data to the collection via the fakeFirebaseFirestore object.
  • Retrieving the actual data list in the collection via the service's getFromCollection method.
  • Asserting that the data list contains the added data using the MapListContains matcher.

  This is shown below:

   test('getFromCollection gets data from a given collection', () async {
      final FirestoreService firestoreService =
              FirestoreService(firestore: fakeFirebaseFirestore!);
      const String collectionPath = 'collectionPath';
  
      await fakeFirebaseFirestore!.collection(collectionPath).add(data);
  
      final List<Map<String, dynamic>> dataList = (await firestoreService
                  .getFromCollection(collectionPath: collectionPath))
              .docs
              .map((e) => e.data())
              .toList();
  
      expect(dataList, const MapListContains(data)); /// Passes ✅
   });
  

• Test For Getting A Snapshot Stream From A Collection.

  Stream<QuerySnapshot<Map<String, dynamic>>> getSnapshotStreamFromCollection(
      {required String collectionPath}) {
    return firestore.collection(collectionPath).snapshots();
  }
  

  The getSnapshotStreamFromCollection method above can be tested by:

  • Injecting the mock Firestore object, fakeFirebaseFirestore, to the service
  • Adding the data to the collection via the fakeFirebaseFirestore object.
  • Retrieving the expected snapshot stream from the fakeFirebaseFirestore object and the actual snapshot stream from the service's getSnapshotStreamFromCollection method.
  • Getting the data from the two snapshot streams and putting them into individual lists (the actual data list and the expected data list).
  • Asserting that the actual data list is equal to the expected data list.

  This is shown below:

   test( 'getSnapshotStreamFromCollection returns a stream of QuerySnaphot containing the data added', () async {
       final FirestoreService firestoreService =
              FirestoreService(firestore: fakeFirebaseFirestore!);
       const String collectionPath = 'collectionPath';
  
       final CollectionReference<Map<String, dynamic>> collectionReference =
              fakeFirebaseFirestore!.collection(collectionPath);
       await collectionReference.add(data);
  
       final Stream<QuerySnapshot<Map<String, dynamic>>>
              expectedSnapshotStream = collectionReference.snapshots();
  
       final actualSnapshotStream = firestoreService
              .getSnapshotStreamFromCollection(collectionPath: collectionPath);
  
       final QuerySnapshot<Map<String, dynamic>> expectedQuerySnapshot =
              await expectedSnapshotStream.first;
       final QuerySnapshot<Map<String, dynamic>> actualQuerySnapshot =
              await actualSnapshotStream.first;
  
       final List<Map<String, dynamic>> expectedDataList =
              expectedQuerySnapshot.docs.map((e) => e.data()).toList();
       final List<Map<String, dynamic>> actualDataList =
              actualQuerySnapshot.docs.map((e) => e.data()).toList();
  
       expect(actualDataList, expectedDataList); /// Passes ✅
   });
  

Document Operations Testing

• Test For Deleting A Document From A Collection.

  Future<void> deleteDocumentFromCollection(
      {required String collectionPath, required String documentPath}) async {
    return firestore.collection(collectionPath).doc(documentPath).delete();
  }
  

  The deleteDocumentFromCollection method above can be tested by:

  • Injecting the mock Firestore object, fakeFirebaseFirestore, to the service.
  • Adding the data to the collection via the fakeFirebaseFirestore object.
  • Deleting the document at the collection via the service's deleteDocumentFromCollection method.
  • Getting the data at the document's path from the fakeFirebaseFirestore.
  • Asserting that the document does not exist.

  This is shown below:

  test('deleteDocumentFromCollection deletes a document from a given collection', () async {
        final FirestoreService firestoreService =
            FirestoreService(firestore: fakeFirebaseFirestore!);
        const String collectionPath = 'collectionPath';
  
        final CollectionReference<Map<String, dynamic>> collectionReference =
            fakeFirebaseFirestore!.collection(collectionPath);
  
        final DocumentReference<Map<String, dynamic>> documentReference =
            await collectionReference.add(data);
  
        final String documentPath = documentReference.path;
  
        await firestoreService.deleteDocumentFromCollection(
            collectionPath: collectionPath, documentPath: documentPath);
  
        final DocumentSnapshot<Map<String, dynamic>> documentSnapshot =
            await collectionReference.doc(documentPath).get();
  
        expect(documentSnapshot.exists, false); /// Passes ✅
      });
  

• Test For Getting A Document's Data.

  Future<DocumentSnapshot<Map<String, dynamic>>> getFromDocument(
      {required String collectionPath, required String documentPath}) {
    return firestore.collection(collectionPath).doc(documentPath).get();
  }
  

  The getFromDocument method above can be tested by:

  • Injecting the mock Firestore object, fakeFirebaseFirestore, to the service.
  • Setting data to the document via the fakeFirebaseFirestore object.
  • Retrieving the actual data in the document via the service's getFromDocument method.
  • Asserting that the data retrieved via the service is equal to the data set via fakeFirebaseFirestore.

  This is shown below:

  test('getFromDocument gets data from a given document', () async {
        final FirestoreService firestoreService =
            FirestoreService(firestore: fakeFirebaseFirestore!);
  
        const String collectionPath = 'collectionPath';
        const String documentPath = 'documentPath';
  
        final DocumentReference<Map<String, dynamic>> documentReference =
            fakeFirebaseFirestore!.collection(collectionPath).doc(documentPath);
  
        await documentReference.set(data);
  
        final DocumentSnapshot<Map<String, dynamic>> expectedDocumentSnapshot =
            await documentReference.get();
  
        final DocumentSnapshot<Map<String, dynamic>> actualDocumentSnapshot =
            await firestoreService.getFromDocument(
                collectionPath: collectionPath, documentPath: documentPath);
  
        final Map<String, dynamic>? expectedData =
            expectedDocumentSnapshot.data();
        final Map<String, dynamic>? actualData = actualDocumentSnapshot.data();
  
        expect(actualData, expectedData); /// Passes ✅
      });
  

• Test For Setting Documents's Data.

  Future<void> setDataOnDocument(
      {required Map<String, dynamic> data,
      required String collectionPath,
      required String documentPath}) {
    return firestore.collection(collectionPath).doc(documentPath).set(data);
  }
  

  The setDataOnDocument method above can be tested by:

  • Injecting the mock Firestore object, fakeFirebaseFirestore, to the service.
  • Setting data to the document via the service's setDataOnDocument method.
  • Retrieving the actual data in the document via the fakeFirebaseFirestore object.
  • Asserting that the data set via the service is equal to the data retrieved via fakeFirebaseFirestore.

  This is shown below:

  test('setDataOnDocument sets data on a given document', () async {
        final FirestoreService firestoreService =
            FirestoreService(firestore: fakeFirebaseFirestore!);
  
        const String collectionPath = 'collectionPath';
        const String documentPath = 'documentPath';
  
        await firestoreService.setDataOnDocument(
            data: data,
            collectionPath: collectionPath,
            documentPath: documentPath);
  
        final DocumentReference<Map<String, dynamic>> documentReference =
            fakeFirebaseFirestore!.collection(collectionPath).doc(documentPath);
  
        final DocumentSnapshot<Map<String, dynamic>> actualDocumentSnapshot =
            await documentReference.get();
        final Map<String, dynamic>? actualData = actualDocumentSnapshot.data();
  
        const Map<String, dynamic> expectedData = data;
  
        expect(actualData, expectedData); /// Passes ✅
      });
  

• Test For Getting A Snapshot Stream From A Document.

  Stream<DocumentSnapshot<Map<String, dynamic>>> getSnapshotStreamFromDocument(
      {required String collectionPath, required String documentPath}) {
    return firestore.collection(collectionPath).doc(documentPath).snapshots();
  }
  

  The getSnapshotStreamFromDocument method above can be tested by:

  • Injecting the mock Firestore object, fakeFirebaseFirestore, to the service.
  • Setting the data to the document via the fakeFirebaseFirestore object.
  • Retrieving the expected snapshot stream from the fakeFirebaseFirestore object and the actual snapshot stream from the service's getSnapshotStreamFromDocument method.
  • Getting the data from the two snapshot streams.
  • Asserting that the actual data via the service is equal to the expected data via fakeFirebaseFirestore.

  This is shown below:

  test(
          'getSnapshotStreamFromDocument returns a stream of DocumentSnapshot containing the data set',
          () async {
        final FirestoreService firestoreService =
            FirestoreService(firestore: fakeFirebaseFirestore!);
  
        const String collectionPath = 'collectionPath';
        const String documentPath = 'documentPath';
  
        final DocumentReference<Map<String, dynamic>> documentReference =
            fakeFirebaseFirestore!.collection(collectionPath).doc(documentPath);
  
        await documentReference.set(data);
  
        final Stream<DocumentSnapshot<Map<String, dynamic>>>
            expectedSnapshotStream = documentReference.snapshots();
  
        final Stream<DocumentSnapshot<Map<String, dynamic>>>
            actualSnapshotStream =
            firestoreService.getSnapshotStreamFromDocument(
                collectionPath: collectionPath, documentPath: documentPath);
  
        final DocumentSnapshot<Map<String, dynamic>> expectedDocumentSnapshot =
            await expectedSnapshotStream.first;
        final DocumentSnapshot<Map<String, dynamic>> actualDocumentSnapshot =
            await actualSnapshotStream.first;
  
        final Map<String, dynamic>? expectedData =
            expectedDocumentSnapshot.data();
        final Map<String, dynamic>? actualData = actualDocumentSnapshot.data();
  
        expect(actualData, expectedData); /// Passes ✅
      });
  

• Test For Updating A Document's Data.

  Future<void> updateDataOnDocument(
      {required Map<String, dynamic> data,
      required String collectionPath,
      required String documentPath}) {
    return firestore.collection(collectionPath).doc(documentPath).update(data);
  }
  

  The updateDataOnDocument method above can be tested by:

  • Injecting the mock Firestore object, fakeFirebaseFirestore, to the service.
  • Setting data to the document via the fakeFirebaseFirestore object.
  • Updating the data set to the document via the service's updateDataOnDocument method.
  • Retrieving the data in the document via fakeFirebaseStore.
  • Asserting that the updated data set via the service is equal to the expected data retrieved via fakeFirebaseFirestore.

  This is shown below:

   test('updateDataOnDocument updates a given document\'s data', () async {
     final FirestoreService firestoreService =
            FirestoreService(firestore: fakeFirebaseFirestore!);
  
     const String collectionPath = 'collectionPath';
     const String documentPath = 'documentPath';
  
     final DocumentReference<Map<String, dynamic>> documentReference =
            fakeFirebaseFirestore!.collection(collectionPath).doc(documentPath);
  
     await documentReference.set(data);
  
     final Map<String, dynamic> dataUpdate = {'data': '43'};
  
     await firestoreService.updateDataOnDocument(
            data: dataUpdate,
            collectionPath: collectionPath,
            documentPath: documentPath);
  
     final DocumentSnapshot<Map<String, dynamic>> actualDocumentSnapshot =
            await documentReference.get();
  
     final Map<String, dynamic>? actualData = actualDocumentSnapshot.data();
  
     final Map<String, dynamic> expectedData = dataUpdate;
  
     expect(actualData, expectedData); /// Passes ✅
   });
  

Complete Test File

The content of the entire test file is shown below:

import 'package:cloud_firestore/cloud_firestore.dart';
import 'package:fake_cloud_firestore/fake_cloud_firestore.dart';
import 'package:firestore_unit_test_flutter/firestore_service.dart';
import 'package:flutter/foundation.dart';
import 'package:test/test.dart';

void main() {
  group('FirestoreService', () {
    FakeFirebaseFirestore? fakeFirebaseFirestore;
    const Map<String, dynamic> data = {'data': '42'};

    setUp(() {
      fakeFirebaseFirestore = FakeFirebaseFirestore();
    });

    group(
      'Collection Operations',
      () {
        test('addToCollection adds data to given collection', () async {
          final FirestoreService firestoreService =
              FirestoreService(firestore: fakeFirebaseFirestore!);
          const String collectionPath = 'collectionPath';

          await firestoreService.addToCollection(
              data: data, collectionPath: collectionPath);

          final List<Map<String, dynamic>> actualDataList =
              (await fakeFirebaseFirestore!.collection('collectionPath').get())
                  .docs
                  .map((e) => e.data())
                  .toList();

          expect(actualDataList, const MapListContains(data));
        });

        test('getFromCollection gets data from a given collection', () async {
          final FirestoreService firestoreService =
              FirestoreService(firestore: fakeFirebaseFirestore!);
          const String collectionPath = 'collectionPath';

          await fakeFirebaseFirestore!.collection(collectionPath).add(data);

          final List<Map<String, dynamic>> dataList = (await firestoreService
                  .getFromCollection(collectionPath: collectionPath))
              .docs
              .map((e) => e.data())
              .toList();

          expect(dataList, const MapListContains(data));
        });

        test(
            'getSnapshotStreamFromCollection returns a stream of QuerySnaphot containing the data added',
            () async {
          final FirestoreService firestoreService =
              FirestoreService(firestore: fakeFirebaseFirestore!);
          const String collectionPath = 'collectionPath';

          final CollectionReference<Map<String, dynamic>> collectionReference =
              fakeFirebaseFirestore!.collection(collectionPath);
          await collectionReference.add(data);

          final Stream<QuerySnapshot<Map<String, dynamic>>>
              expectedSnapshotStream = collectionReference.snapshots();

          final actualSnapshotStream = firestoreService
              .getSnapshotStreamFromCollection(collectionPath: collectionPath);

          final QuerySnapshot<Map<String, dynamic>> expectedQuerySnapshot =
              await expectedSnapshotStream.first;
          final QuerySnapshot<Map<String, dynamic>> actualQuerySnapshot =
              await actualSnapshotStream.first;

          final List<Map<String, dynamic>> expectedDataList =
              expectedQuerySnapshot.docs.map((e) => e.data()).toList();
          final List<Map<String, dynamic>> actualDataList =
              actualQuerySnapshot.docs.map((e) => e.data()).toList();

          expect(actualDataList, expectedDataList);
        });
      },
    );

    group('Document Operations', () {
      test(
          'deleteDocumentFromCollection deletes a document from a given collection',
          () async {
        final FirestoreService firestoreService =
            FirestoreService(firestore: fakeFirebaseFirestore!);
        const String collectionPath = 'collectionPath';

        final CollectionReference<Map<String, dynamic>> collectionReference =
            fakeFirebaseFirestore!.collection(collectionPath);

        final DocumentReference<Map<String, dynamic>> documentReference =
            await collectionReference.add(data);

        final String documentPath = documentReference.path;

        await firestoreService.deleteDocumentFromCollection(
            collectionPath: collectionPath, documentPath: documentPath);

        final DocumentSnapshot<Map<String, dynamic>> documentSnapshot =
            await collectionReference.doc(documentPath).get();

        expect(documentSnapshot.exists, false);
      });

      test('getFromDocument gets data from a given document', () async {
        final FirestoreService firestoreService =
            FirestoreService(firestore: fakeFirebaseFirestore!);

        const String collectionPath = 'collectionPath';
        const String documentPath = 'documentPath';

        final DocumentReference<Map<String, dynamic>> documentReference =
            fakeFirebaseFirestore!.collection(collectionPath).doc(documentPath);

        await documentReference.set(data);

        final DocumentSnapshot<Map<String, dynamic>> expectedDocumentSnapshot =
            await documentReference.get();

        final DocumentSnapshot<Map<String, dynamic>> actualDocumentSnapshot =
            await firestoreService.getFromDocument(
                collectionPath: collectionPath, documentPath: documentPath);

        final Map<String, dynamic>? expectedData =
            expectedDocumentSnapshot.data();
        final Map<String, dynamic>? actualData = actualDocumentSnapshot.data();

        expect(actualData, expectedData);
      });

      test('setDataOnDocument sets data on a given document', () async {
        final FirestoreService firestoreService =
            FirestoreService(firestore: fakeFirebaseFirestore!);

        const String collectionPath = 'collectionPath';
        const String documentPath = 'documentPath';

        await firestoreService.setDataOnDocument(
            data: data,
            collectionPath: collectionPath,
            documentPath: documentPath);

        final DocumentReference<Map<String, dynamic>> documentReference =
            fakeFirebaseFirestore!.collection(collectionPath).doc(documentPath);

        final DocumentSnapshot<Map<String, dynamic>> actualDocumentSnapshot =
            await documentReference.get();
        final Map<String, dynamic>? actualData = actualDocumentSnapshot.data();

        const Map<String, dynamic> expectedData = data;

        expect(actualData, expectedData);
      });

      test(
          'getSnapshotStreamFromDocument returns a stream of DocumentSnapshot containing the data set',
          () async {
        final FirestoreService firestoreService =
            FirestoreService(firestore: fakeFirebaseFirestore!);

        const String collectionPath = 'collectionPath';
        const String documentPath = 'documentPath';

        final DocumentReference<Map<String, dynamic>> documentReference =
            fakeFirebaseFirestore!.collection(collectionPath).doc(documentPath);

        await documentReference.set(data);

        final Stream<DocumentSnapshot<Map<String, dynamic>>>
            expectedSnapshotStream = documentReference.snapshots();

        final Stream<DocumentSnapshot<Map<String, dynamic>>>
            actualSnapshotStream =
            firestoreService.getSnapshotStreamFromDocument(
                collectionPath: collectionPath, documentPath: documentPath);

        final DocumentSnapshot<Map<String, dynamic>> expectedDocumentSnapshot =
            await expectedSnapshotStream.first;
        final DocumentSnapshot<Map<String, dynamic>> actualDocumentSnapshot =
            await actualSnapshotStream.first;

        final Map<String, dynamic>? expectedData =
            expectedDocumentSnapshot.data();
        final Map<String, dynamic>? actualData = actualDocumentSnapshot.data();

        expect(actualData, expectedData);
      });

      test('updateDataOnDocument updates a given document\'s data', () async {
        final FirestoreService firestoreService =
            FirestoreService(firestore: fakeFirebaseFirestore!);

        const String collectionPath = 'collectionPath';
        const String documentPath = 'documentPath';

        final DocumentReference<Map<String, dynamic>> documentReference =
            fakeFirebaseFirestore!.collection(collectionPath).doc(documentPath);

        await documentReference.set(data);

        final Map<String, dynamic> dataUpdate = {'data': '43'};

        await firestoreService.updateDataOnDocument(
            data: dataUpdate,
            collectionPath: collectionPath,
            documentPath: documentPath);

        final DocumentSnapshot<Map<String, dynamic>> actualDocumentSnapshot =
            await documentReference.get();

        final Map<String, dynamic>? actualData = actualDocumentSnapshot.data();

        final Map<String, dynamic> expectedData = dataUpdate;

        expect(actualData, expectedData);
      });
    });
  });
}

class MapListContains extends Matcher {
  final Map<dynamic, dynamic> _expected;

  const MapListContains(this._expected);

  @override
  Description describe(Description description) {
    return description.add('contains ').addDescriptionOf(_expected);
  }

  @override
  bool matches(dynamic item, Map matchState) {
    if (item is List<Map>) {
      return item.any((element) => mapEquals(element, _expected));
    }
    return false;
  }
}

Conclusion

This article demonstrates how to unit test Firebase Firestore operations involving Collections and Documents. It also shows how to use a custom Matcher in test assertions.

The complete code can be found on GitHub.

This article demonstrates how to unit-test Shared Preferences in Flutter projects.

This article assumes that the reader is familiar with Flutter development and the Dart language.

The code in the demo was created using Flutter Channel stable, 2.5.3.

Problem Statement

We have a SharedPreferencesUtil class that makes use of the SharedPreferences object to store and retrieve an integer count. Our task is to unit-test the methods of this class.

The class is shown below:

import 'package:flutter/foundation.dart';
import 'package:shared_preferences/shared_preferences.dart';

class SharedPreferencesUtil {
  SharedPreferencesUtil({required this.sharedPreferences});

  final SharedPreferences sharedPreferences;

  @visibleForTesting
  static const String countKey = 'counter';

  int getCount() {
    return sharedPreferences.getInt(countKey) ?? 0;
  }

  Future<bool> setCount(int count) async {
    return sharedPreferences.setInt(countKey, count);
  }
}

Testing the methods

In the SharedPreferencesUtil class above, the SharedPreferences object is passed through the constructor and it is used in the following methods:

• getCount(): To return the value of the count integer stored in SharedPreferences with the countKey key and return 0 if the value in SharedPreferences is null
• setCount(): To set the value of count int with the countKey key in SharedPreferences

In order to write a test, we need to mock the SharedPreferences object that we pass into the SharedPreferencesUtil class.

This is done using the SharedPreferences.setMockInitialValues() static method.

setMockInitialValues()

Initializes the shared preferences with mock values for testing.

Source

This method is used to mock the initial state of the SharedPreferences object used in tests. It takes a parameter of type Map<String, Object> for which the key is used to identify the stored SharedPreferences object and the value is the actual object stored in SharedPreferences.

For instance:

If we want our SharedPreferences object in our test to store the number 42 with the key counter, we do it this way:

SharedPreferences.setMockInitialValues({'counter': 42});

Testing the getCounter() method

• Test that the getCount() method returns 0 if there is no value stored in SharedPreferences.

  We first call the SharedPreferences.setMockInitialValues() and pass it {} (empty Map object) method to make sure nothing is stored in SharedPreferences. We, then, pass it into the SharedPreferencesUtil class.

  We, then, can call the getCount() method and compare it with the expected value of 0 using the expect() method from the test library.

import 'package:shared_preferences/shared_preferences.dart';
import 'package:shared_preferences_unit_tests_flutter/shared_preferences_util.dart';
import 'package:test/test.dart';

main() {
  group(SharedPreferencesUtil, () {
    group('getCounter', () {
      test('returns 0 if no value is stored in SharedPreferences', () async {
        SharedPreferences.setMockInitialValues({});

        final SharedPreferences sharedPreferences =
            await SharedPreferences.getInstance();

        final SharedPreferencesUtil sharedPreferencesUtil =
            SharedPreferencesUtil(sharedPreferences: sharedPreferences);

        const expectedCounter = 0;
        final actualCounter = sharedPreferencesUtil.getCount();

        expect(expectedCounter, actualCounter);
      });
    });
  });
}

• Test that the getCount() method returns the correct value stored in SharedPreferences.

  We first call SharedPreferences.setMockInitialValues() and pass it {SharedPreferencesUtil.countKey: counterValue} where SharedPreferencesUtil.counterKey is the key and counterValue contains the value we want to store. We, then, pass it into the SharedPreferencesUtil class.

  We, then, can call the getCount() method and compare it with the expected value of 0 using the expect() method.

import 'package:shared_preferences/shared_preferences.dart';
import 'package:shared_preferences_unit_tests_flutter/shared_preferences_util.dart';
import 'package:test/test.dart';

main() {
  group(SharedPreferencesUtil, () {
    group('getCounter', () {
      test('returns 0 if no value is stored in SharedPreferences', () async {
       ...
      });

      test('returns the correct value stored in SharedPreferences', () async {
        const counterValue = 42;
        SharedPreferences.setMockInitialValues(
            {SharedPreferencesUtil.countKey: counterValue});
        final SharedPreferences sharedPreferences =
            await SharedPreferences.getInstance();

        final SharedPreferencesUtil sharedPreferencesUtil =
            SharedPreferencesUtil(sharedPreferences: sharedPreferences);

        const expectedCount = counterValue;
        final actualCounter = sharedPreferencesUtil.getCount();
        expect(expectedCount, actualCounter);
      });
    });
  });
}

Testing the setCounter() method

• Test that the setCount() method stores the correct value in SharedPreferences.

  We first call the SharedPreferences.setMockInitialValues() and pass it {} (empty Map object) method to make sure nothing is stored in SharedPreferences. We, then, pass it into the SharedPreferencesUtil class.

  We, then, can call the SharedPreferences.getInt() method, pass the SharedPreferencesUtil.countKey key to it to get the value in SharedPreferences compare it with the expected value in the countValue variable.

import 'package:shared_preferences/shared_preferences.dart';
import 'package:shared_preferences_unit_tests_flutter/shared_preferences_util.dart';
import 'package:test/test.dart';

main() {
  group(SharedPreferencesUtil, () {
    group('getCounter', () {
      test('returns 0 if no value is stored in SharedPreferences', () async {
        ...
      });

      test('returns the correct value stored in SharedPreferences', () async {
        ...
      });
    });

    group('setCounter', () {
      test('stores the correct count value in SharedPreferences', () async {
        SharedPreferences.setMockInitialValues({});
        final SharedPreferences sharedPreferences =
            await SharedPreferences.getInstance();

        final SharedPreferencesUtil sharedPreferencesUtil =
            SharedPreferencesUtil(sharedPreferences: sharedPreferences);
        const countValue = 42;

        sharedPreferencesUtil.setCount(countValue);
        const expectedCounter = countValue;
        final actualCounter =
            sharedPreferences.getInt(SharedPreferencesUtil.countKey);

        expect(expectedCounter, actualCounter);
      });
    });
  });
}

Complete Test File

The content of the entire test file is shown below:

import 'package:shared_preferences/shared_preferences.dart';
import 'package:shared_preferences_unit_tests_flutter/shared_preferences_util.dart';
import 'package:test/test.dart';

main() {
  group(SharedPreferencesUtil, () {
    group('getCounter', () {
      test('returns 0 if no value is stored in SharedPreferences', () async {
        SharedPreferences.setMockInitialValues({});

        final SharedPreferences sharedPreferences =
            await SharedPreferences.getInstance();

        final SharedPreferencesUtil sharedPreferencesUtil =
            SharedPreferencesUtil(sharedPreferences: sharedPreferences);

        const expectedCounter = 0;
        final actualCounter = sharedPreferencesUtil.getCount();

        expect(expectedCounter, actualCounter);
      });

      test('returns the correct value stored in SharedPreferences', () async {
        const counterValue = 42;
        SharedPreferences.setMockInitialValues(
            {SharedPreferencesUtil.countKey: counterValue});
        final SharedPreferences sharedPreferences =
            await SharedPreferences.getInstance();

        final SharedPreferencesUtil sharedPreferencesUtil =
            SharedPreferencesUtil(sharedPreferences: sharedPreferences);

        const expectedCount = counterValue;
        final actualCounter = sharedPreferencesUtil.getCount();
        expect(expectedCount, actualCounter);
      });
    });

    group('setCounter', () {
      test('stores the correct count value in SharedPreferences', () async {
        SharedPreferences.setMockInitialValues({});
        final SharedPreferences sharedPreferences =
            await SharedPreferences.getInstance();

        final SharedPreferencesUtil sharedPreferencesUtil =
            SharedPreferencesUtil(sharedPreferences: sharedPreferences);
        const countValue = 42;

        sharedPreferencesUtil.setCount(countValue);
        const expectedCounter = countValue;
        final actualCounter =
            sharedPreferences.getInt(SharedPreferencesUtil.countKey);

        expect(expectedCounter, actualCounter);
      });
    });
  });
}

Conclusion

Mocking the SharedPreferences object in tests makes use of the setMockInitialValues method to initialize the state.

The complete code can be found on GitHub.

This article assumes that the reader is familiar with Flutter development and the Dart language.

The article is divided into:

1. Introduction
2. Using the dart:io library
3. Using the file library
4. Conclusion

1. Introduction

We want to create a function createHelloWorldFile that creates a file hello_world.dart at a location generated/hello_world.dart.

We also want to unit test this function to ensure that the file is created at the specific location when the function runs.

We'll look at two different ways of doing this:

• Using the dart:io library
• Using the file library

2. Using the dart:io library

Writing the Function

This implementation is to make use of the dart:io library and its File object to create the file.

We first create the File object with the desired location passed as a parameter and call .createSync to create the file.

recursive:true is needed to ensure that any non-existing path is created first before creating the file.

Here is the code for the function:

import 'dart:io';

void createHelloWorldFile() {
  final file = File('generated/hello_world.dart');
  file.createSync(recursive: true);
}

Calling the Function

We can call the function like this:

import 'dart:io';

void main(List<String> arguments) {
  createHelloWorldFile();
}

Testing the Function

The first step is to add the test library to dev_dependencies in the pubspec.yaml file like this:

dev_dependencies:
  test:

The next step is to write the test for the function like this:

import 'dart:io';
import 'package:test/test.dart';

void main() {
  test('createHelloWorldFile creates a file at generated/hello_world.dart', () {
    createHelloWorldFile();
    final file = File('generated/hello_world.dart');
    expect(file.existsSync(), true);
  });
}

The test code above uses the .existsSync property on the created File object to confirm if it does exist.

The test passes when it is run.

The Problem with the Test

Running this test passes but the problem with this test is that it actually creates the generated/hello_world.dart file.

This generated file is not needed for the actual test so it would be better to use a mock file system so we can write/run as many tests as we want without worrying about side effects.

3. Using the file library

Writing the Function

To solve the problem with the extra file generated, we will use the file library which gives the ability to create custom file systems and in-memory file systems for easy unit testing of code that works with file systems.

The first step is to add the file library to dependecies in our pubspec.yaml file like this:

dependencies:
  file:

The next step is to update our createHelloWorldFile function to this:

import 'package:test/test.dart';
import 'package:file/file.dart';

void createHelloWorldFile(FileSystem fileSystem) {
  final file = fileSystem.file('generated/hello_world.dart');
  file.createSync(recursive: true);
}

In the code above, we inject the fileSystem into the function createHelloWorldFile and use that to create the file.

Calling the Function

To call the function, we pass a LocalFileSystem object into the createHelloWorldFile function.

LocalFileSystem class

A wrapper implementation around dart:io's implementation.

Since this implementation of the FileSystem interface delegates to dart:io, [it] is not suitable for use in the browser.

import 'package:file/local.dart';

void main(List<String> arguments) {
  final localFileSystem = LocalFileSystem();
  createHelloWorldFile(localFileSystem);
}

Testing the Function

In order to test the function, we can pass a MemoryFileSystem object into the createHelloWorldFile.

MemoryFileSystem class

An implementation of FileSystem that exists entirely in memory with an internal representation loosely based on the Filesystem Hierarchy Standard.

MemoryFileSystem is suitable for mocking and tests, as well as for caching or staging before writing or reading to a live system.

import 'package:file/memory.dart';
import 'package:test/test.dart';

void main() {
  test('createHelloWorldFile creates a file at generated/hello_world.dart', () {
    final memoryFileSystem = MemoryFileSystem();
    createHelloWorldFile(memoryFileSystem);

    final file = memoryFileSystem.file('generated/hello_world.dart');

    expect(file.existsSync(), true);
  });
}

Running this test passes and it does not create any extra files.

4. Conclusion

The file library provides an easy way to test operations involving files with the use of the MemoryFileSystem which is an in-memory file system that does not write to the actual file system.

The complete project can be found on Github.

The article is divided into:

1. Introduction
2. Mocking The Callback
3. Testing The Callback

1. Introduction

Let's say we have a function readDate with the definition below:

void readData(void Function() onDataReadComplete) {
    print('Reading data');
    onDataReadComplete();
}

The function takes a callback onDataReadComplete as a lone positional parameter and it calls onDataReadComplete after it prints ('Reading data').

Our task here is to write a unit test to confirm that onDataReadComplete is run whenever readData runs.

In order to do this we need to mock onDataReadComplete and confirm that it is actually called.

2. Mocking The Callback

In other to mock the callback, we will use the mock library mockito.

The first step is to add the mockito dependecy to our project by including it in the pubspec.yaml file. We will also add the test library to the pubspec.yaml file.

dev_dependencies:
  mockito:
  test:

Mockito has two ways to generate mock objects:

1. Code Generation
2. Manual Mock Implementation

For this article, we will use the manual mock implementation for simplicity.

A class can be mocked manually by creating a class that extends Mock and implements the class to be mocked.

Below is a sample from the documentation:

class MockHttpServer extends Mock implements HttpServer {}

This means we need a class to represent our function so our mock class can implement it.

We will make use of Dart's Callable Classes.

To allow an instance of your Dart class to be called like a function, implement the call() method.

- Callable Classes

This means we can represent our void Function() onDataReadComplete function as this below:

abstract class OnDataReadComplete {
    void call();
}

The class is an abstract class since we won't be providing an implementation of the call method .

The call method must have the same definition as the function to be mocked. This is why it is a void method.

Now, we can create our mock class like this below:

class MockOnDataReadComplete extends Mock implements OnDataReadComplete {}

We can now, use MockOnDataReadComplete in our test.

3. Testing The Callback

We will follow the following steps in testing the callback function:

1. Create the mock object mockOnDataReadComplete using MockOnDataReadComplete.
2. Run the readData function with mockOnDataReadComplete passed as a parameter.
3. Use the verify function to confirm that mockOnDataReadComplete() is called once. Note that you need to call the function like this mockOnDataReadComplete() and not just pass the variable mockOnDataReadComplete to the verify function

test('onDataReadComplete gets called whenever readData runs', () {
    //Creates the mock object
    final mockOnDataReadComplete = MockOnDataReadComplete();

    //Runs the function
    readData(mockOnDataReadComplete);

    //Confirm that the mock object is called
    verify(mockOnDataReadComplete()).called(1);
  });

Here is the full test file:

import 'package:mockito/mockito.dart';
import 'package:test/test.dart';

void readData(void Function() onDataReadComplete) {
  print('Reading data');
  onDataReadComplete();
}

abstract class OnDataReadComplete {
  void call();
}

class MockOnDataReadComplete extends Mock implements OnDataReadComplete {}

void main() {
  test('onDataReadComplete gets called whenever readData runs', () {
    //Creates the mock object
    final mockOnDataReadComplete = MockOnDataReadComplete();

    //Runs the function
    readData(mockOnDataReadComplete);

    //Confirm that the mock object is called
    verify(mockOnDataReadComplete()).called(1);
  });
}

And now we run our tests and it passes!

The complete project can be found on Github.

The article is divided into two sections:

1. UI, where the app's user interface will be built.

2. State, where the state of the app's counter will be implemented.

Below is a screenshot of the default Flutter counter app:

This is what we'll rebuild with Jetpack Compose.

The first step is to download a Jetpack Compose supported Android Studio version (at this time of writing, that is the Arctic Fox version).

The next step is to create an empty compose activity by clicking on File > New Project and selecting Empty Compose Activity from the templates shown.

Click on Next.

Then we enter our application name. For this article, we'll use "ComposeCounterApp".

Click on Finish and it should open the ComposeCounterApp project.

1. UI

Open the MainActivity.kt file. It should contain the default Compose Activity code.

We'll remove the code and update the content of MainActivity.kt to this below:

package com.example.composecounterapp

import android.os.Bundle
import androidx.activity.ComponentActivity
import androidx.activity.compose.setContent
import androidx.compose.material.Scaffold
import androidx.compose.runtime.Composable
import com.example.composecounterapp.ui.theme.ComposeCounterAppTheme

class MainActivity : ComponentActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContent {
            ComposeCounterAppTheme {
                ComposeCounter()
            }
        }
    }
}

@Composable
fun ComposeCounter() {
    Scaffold(
        content = {}
    )
}

On running the project on a device, an empty screen is displayed. This is because ComposeCounter only contains a Scaffold composable with empty content.

Next, we'll add the code for the app bar. We'll use the TopAppBar composable and specify the title, the background colour, and the content colour.

Update the ComposeCounter function to this.

@Composable
fun ComposeCounter() {
    val primaryColor = Color(0xFF2196F3)

    Scaffold(
        topBar = {
            TopAppBar(
                title = { Text(text = "Compose Home Demo Page") },
                backgroundColor = primaryColor,
                contentColor = Color.White
            )
        },
        content = {}
    )
}

This will show the following screen:

Next, we'll add the content of the screen. And for this, we'll pass a Column with two Texts to the Scaffold as content. The column items will be aligned in the center and we'll pass modifiers to ensure the Column fills the screen horizontally and vertically.

@Composable
fun ComposeCounter() {
    val primaryColor = Color(0xFF2196F3)

    Scaffold(
        topBar = {
            TopAppBar(
                title = { Text(text = "Compose Home Demo Page") },
                backgroundColor = primaryColor,
                contentColor = Color.White
            )
        },
        content = {
            Column(
                verticalArrangement = Arrangement.Center,
                horizontalAlignment = Alignment.CenterHorizontally,
                modifier = Modifier
                    .fillMaxHeight()
                    .fillMaxWidth()
            ) {
                Text(
                    text = "You have pushed this button this many times",
                )
                Text(
                    text = "0",
                    style = MaterialTheme.typography.h4,
                )
            }
        },
    )
}

And now we'll have this showing on our device.

The last thing to add for the UI is the floating action button, which we can specify on the Scaffold by passing a FloatingActionButton composable to the Scaffold as floatingActionButton.

We do that by updating the ComposeCounter composable to the code below:

@Composable
fun ComposeCounter() {
    val primaryColor = Color(0xFF2196F3)

    Scaffold(
        topBar = {
            TopAppBar(
                title = { Text(text = "Compose Home Demo Page") },
                backgroundColor = primaryColor,
                contentColor = Color.White
            )
        },
        content = {
            Column(
                verticalArrangement = Arrangement.Center,
                horizontalAlignment = Alignment.CenterHorizontally,
                modifier = Modifier
                    .fillMaxHeight()
                    .fillMaxWidth()
            ) {
                Text(
                    text = "You have pushed this button this many times",
                )
                Text(
                    text = "0",
                    style = MaterialTheme.typography.h4,
                )
            }
        },
        floatingActionButton = {
            FloatingActionButton(
                onClick = {},
                backgroundColor = primaryColor,
                contentColor = Color.White
            ) {
                Icon(Icons.Filled.Add, contentDescription = "Add button")
            }
        },
    )
}

And now, we'll have our complete UI! 🎉

2. State

Currently, the app displays "0" as the counter state and we need to make sure that clicking the floating action button increments that state.

We need a variable to hold the state of the counter.

From State and Jetpack Compose,

There are three ways to declare a MutableState object in a composable:

• val mutableState = remember { mutableStateOf(default) }

• var value by remember { mutableStateOf(default) }

• val (value, setValue) = remember { mutableStateOf(default) }

We'll be using the second one.

At the top of the ComposeCounter composable, we'll add a variable counter to hold the state of the counter and set its default value to zero.

We'll also use this counter variable in the Text composable instead of "0".

And now the ComposeCounter will have the following code:

@Composable
fun ComposeCounter() {
    val primaryColor = Color(0xFF2196F3)
    var counter: Int by remember { mutableStateOf(0) }

    Scaffold(
        topBar = {
            TopAppBar(
                title = { Text(text = "Compose Home Demo Page") },
                backgroundColor = primaryColor,
                contentColor = Color.White
            )
        },
        content = {
            Column(
                verticalArrangement = Arrangement.Center,
                horizontalAlignment = Alignment.CenterHorizontally,
                modifier = Modifier
                    .fillMaxHeight()
                    .fillMaxWidth()
            ) {
                Text(
                    text = "You have pushed this button this many times",
                )
                Text(
                    text = counter.toString(),
                    style = MaterialTheme.typography.h4,
                )
            }
        },
        floatingActionButton = {
            FloatingActionButton(
                onClick = {
                },
                backgroundColor = primaryColor,
                contentColor = Color.White
            ) {
                Icon(Icons.Filled.Add, contentDescription = "Add button")
            }
        },
    )
}

There will be no visible change on the screen for now.

The next thing to do is to increment the counter when the floating action button is clicked.

We can do that in the onClick callback of the FloatingActionButton.

The code will be updated to this:

@Composable
fun ComposeCounter() {
    val primaryColor = Color(0xFF2196F3)
    var counter: Int by remember { mutableStateOf(0) }


    Scaffold(
        topBar = {
            TopAppBar(
                title = { Text(text = "Compose Home Demo Page") },
                backgroundColor = primaryColor,
                contentColor = Color.White
            )
        },
        content = {
            Column(
                verticalArrangement = Arrangement.Center,
                horizontalAlignment = Alignment.CenterHorizontally,
                modifier = Modifier
                    .fillMaxHeight()
                    .fillMaxWidth()
            ) {
                Text(
                    text = "You have pushed this button this many times",
                )
                Text(
                    text = counter.toString(),
                    style = MaterialTheme.typography.h4,
                )
            }
        },
        floatingActionButton = {
            FloatingActionButton(
                onClick = {
                    counter += 1
                },
                backgroundColor = primaryColor,
                contentColor = Color.White
            ) {
                Icon(Icons.Filled.Add, contentDescription = "Add button")
            }
        },
    )
}

Now the app increments the counter when the floating action button is tapped as seen in the gif below:

And now the app is complete.

The complete code for the MainActivity.kt is this below:

package com.example.composecounterapp

import android.os.Bundle
import androidx.activity.ComponentActivity
import androidx.activity.compose.setContent
import androidx.compose.foundation.layout.Arrangement
import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.fillMaxHeight
import androidx.compose.foundation.layout.fillMaxWidth
import androidx.compose.material.*
import androidx.compose.material.icons.Icons
import androidx.compose.material.icons.filled.Add
import androidx.compose.runtime.*
import androidx.compose.ui.Alignment
import androidx.compose.ui.Modifier
import androidx.compose.ui.graphics.Color
import com.example.composecounterapp.ui.theme.ComposeCounterAppTheme

class MainActivity : ComponentActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContent {
            ComposeCounterAppTheme {
                ComposeCounter()
            }
        }
    }
}

@Composable
fun ComposeCounter() {
    val primaryColor = Color(0xFF2196F3)
    var counter: Int by remember { mutableStateOf(0) }


    Scaffold(
        topBar = {
            TopAppBar(
                title = { Text(text = "Compose Home Demo Page") },
                backgroundColor = primaryColor,
                contentColor = Color.White
            )
        },
        content = {
            Column(
                verticalArrangement = Arrangement.Center,
                horizontalAlignment = Alignment.CenterHorizontally,
                modifier = Modifier
                    .fillMaxHeight()
                    .fillMaxWidth()
            ) {
                Text(
                    text = "You have pushed this button this many times",
                )
                Text(
                    text = counter.toString(),
                    style = MaterialTheme.typography.h4,
                )
            }
        },
        floatingActionButton = {
            FloatingActionButton(
                onClick = {
                    counter += 1
                },
                backgroundColor = primaryColor,
                contentColor = Color.White
            ) {
                Icon(Icons.Filled.Add, contentDescription = "Add button")
            }
        },
    )
}

The complete project can be found on Github.