(DOCSP-34476) Add cancellationToken parameter to Session.wait methods [Dart/Flutter]

examples/dart/test/manage_sync_session_test.dart

@@ -34,19 +34,25 @@ main() {
     await realm.subscriptions.waitForSynchronization();
   });
   tearDown(() async {
-    cleanUpRealm(realm, app);
+    await cleanUpRealm(realm, app);
   });
   group("Manage sync session - ", () {
     test("Wait for changes to upload and download", () async {
+      // Ensure there aren't any car objects in the on-device database.
+      realm.write(() {
+        realm.deleteAll<Car>();
+      });
+      await realm.syncSession.waitForUpload();
+
       // :snippet-start: wait-upload-download
       // Wait to download all pending changes from Atlas
       await realm.syncSession.waitForDownload();
 
       // :remove-start:
       final syncProgress = realm.syncSession.getProgressStream(
           ProgressDirection.upload, ProgressMode.forCurrentlyOutstandingWork);
-      var called = false;
-      var streamListener;
+      bool called = false;
+      dynamic streamListener;
       streamListener = syncProgress.listen((syncProgressEvent) {
         if (called == false) {
           expect(syncProgressEvent.transferableBytes > 0, isTrue);
@@ -69,6 +75,7 @@ main() {
       // :snippet-end:
       expect(called, isTrue);
     });
+
     test("Pause and resume sync session", () async {
       // :snippet-start: pause-resume-sync
       // Pause the sync session
@@ -163,4 +170,25 @@ main() {
       expect(session.connectionState, ConnectionState.connected);
     });
   });
+
+  // This test should be at the end of the file. It cancels the sync
+  // session, which tests above rely on.
+  test("Cancel waiting for upload or download", () async {
+    // :snippet-start: cancel-waitfor
+    final cancellationToken = CancellationToken();
+
+    final waitForDownloadFuture =
+        realm.syncSession.waitForDownload(cancellationToken);
+    cancellationToken.cancel();
+
+    final waitForUploadFuture =
+        realm.syncSession.waitForUpload(cancellationToken);
+    cancellationToken.cancel();
+    // :snippet-end:
+
+    expect(() async => await waitForDownloadFuture,
+        throwsA(isA<CancelledException>()));
+    expect(() async => await waitForUploadFuture,
+        throwsA(isA<CancelledException>()));
+  });
 }

examples/dart/test/utils.dart

@@ -8,7 +8,7 @@ Future<void> cleanUpRealm(Realm realm, [App? app]) async {
   if (!realm.isClosed) {
     realm.close();
   }
-  sleep(Duration(milliseconds: 250));
+  sleep(Duration(milliseconds: 500));
   Realm.deleteRealm(realm.config.path);
 }
 

source/examples/generated/flutter/manage_sync_session_test.snippet.cancel-waitfor.dart

@@ -0,0 +1,9 @@
+final cancellationToken = CancellationToken();
+
+final waitForDownloadFuture =
+    realm.syncSession.waitForDownload(cancellationToken);
+cancellationToken.cancel();
+
+final waitForUploadFuture =
+    realm.syncSession.waitForUpload(cancellationToken);
+cancellationToken.cancel();

source/sdk/flutter/sync/manage-sync-session.txt

@@ -54,6 +54,13 @@ to download to your synced realm, call :flutter-sdk:`Session.waitForDownload()
 .. literalinclude:: /examples/generated/flutter/manage_sync_session_test.snippet.wait-upload-download.dart
    :language: dart
 
+You can add an optional :flutter-sdk:`CancellationToken 
+<realm/CancellationToken-class.html>` to ``waitForUpload()`` and
+``waitForDownload()``.
+
+.. literalinclude:: /examples/generated/flutter/manage_sync_session_test.snippet.cancel-waitfor.dart
+   :language: dart
+
 .. _flutter-pause-resume-sync:
 
 Pause and Resume a Sync Session