feat(ui_firestore): add includeMetadataChanges parameter to FirestoreQueryBuilder

[cpunion]

Description

Currently FirestoreListView can't get metadata changes, the FirestoreQueryBuilder component calls Query<Document>.snapshots() without includeMetadataChanges parameter.

Related Issues

Checklist

Before you create this PR confirm that it meets all requirements listed below by checking the relevant checkboxes ([x]).
This will ensure a smooth and quick review process. Updating the pubspec.yaml and changelogs is not required.

• I read the Contributor Guide and followed the process outlined there for submitting PRs.
• My PR includes unit or integration tests for all changed/updated/fixed behaviors (See Contributor Guide).
• All existing and new tests are passing.
• I updated/added relevant documentation (doc comments with ///).
• The analyzer (melos run analyze) does not report any problems on my PR.
• All unit tests pass (melos run test:unit:all doesn't fail).
• I read and followed the Flutter Style Guide.
• I signed the CLA.
• I am willing to follow-up on review comments in a timely manner.

Breaking Change

Does your PR require plugin users to manually update their apps to accommodate your change?

• Yes, this is a breaking change.
• No, this is not a breaking change.

[cpunion]

I am not sure if there is a way to directly specify includeMetadataChanges when constructing the query. If there is such a method, then this PR is unnecessary.

[russellwheatley]

@cpunion - This seems good to me. I think we should also update here: https://github.com/firebase/FirebaseUI-Flutter/blob/main/packages/firebase_ui_firestore/lib/src/table_builder.dart#L267

Probably should be able to pass it into FirestoreDataTable if you could update, please?

[cpunion]

@cpunion - This seems good to me. I think we should also update here: https://github.com/firebase/FirebaseUI-Flutter/blob/main/packages/firebase_ui_firestore/lib/src/table_builder.dart#L267

Probably should be able to pass it into FirestoreDataTable if you could update, please?

There isn't any listen call, so I think it need a big change if add includeMetadataChanges?

[russellwheatley]

@cpunion - We can leave that for another time. Do you mind adding a simple test that passes in includeMetadataChanges and checks that metadata is passed in with snapshot here: https://github.com/firebase/FirebaseUI-Flutter/blob/main/tests/integration_test/firebase_ui_firestore/firestore_list_view_test.dart

Thanks 😄

[cpunion]

@cpunion - We can leave that for another time. Do you mind adding a simple test that passes in includeMetadataChanges and checks that metadata is passed in with snapshot here: https://github.com/firebase/FirebaseUI-Flutter/blob/main/tests/integration_test/firebase_ui_firestore/firestore_list_view_test.dart

I will try to add a test.

[cpunion]

@russellwheatley It seems that metadata changes too quickly to be captured by tester.pump*. For example, when creating and updating a document, collection.snapshots().listen(includeMetadataChanges: true) will receive a series of events in a short period of time, like this:

// These are the events from collection.add({value: 1})
received event, hasPendingWrites: true, isFromCache: true, data: ({value: 1})
received event, hasPendingWrites: true, isFromCache: false, data: ()
received event, hasPendingWrites: false, isFromCache: false, data: ()

// These are the events from collection.doc('docId').update({value: 2})
received event, hasPendingWrites: true, isFromCache: false, data: ({value: 2})
received event, hasPendingWrites: false, isFromCache: false, data: ()

When the FirestoreQueryBuilder listens to the collection, multiple setState calls occur in a very short time. tester.pump* only catches the last one, and can't catches changes of hasPendingWrites and isFromCache. I'm not sure how to properly test this case. Could you please help me? Thanks.