fix: error handling for awaitMapReady calls (#353)

jokerttu · aednlaxer · web-flow · commit 867f500c3387 · 2025-05-14T14:22:41.000+03:00
* fix: fixed error handling for awaitMapReady calls
* docs: update documentation for onViewCreated
* tests: add ControllerCompleter

---------

Co-authored-by: Alexander Troshkov &lt;20989940+aednlaxer@users.noreply.github.com&gt;
diff --git a/android/src/main/kotlin/com/google/maps/flutter/navigation/GoogleMapsViewMessageHandler.kt b/android/src/main/kotlin/com/google/maps/flutter/navigation/GoogleMapsViewMessageHandler.kt
@@ -40,7 +40,11 @@ class GoogleMapsViewMessageHandler(private val viewRegistry: GoogleMapsViewRegis
   }
 
   override fun awaitMapReady(viewId: Long, callback: (Result<Unit>) -> Unit) {
-    return getView(viewId.toInt()).awaitMapReady(callback)
+    try {
+      getView(viewId.toInt()).awaitMapReady(callback)
+    } catch (e: Throwable) {
+      callback(Result.failure(e))
+    }
   }
 
   override fun isMyLocationEnabled(viewId: Long): Boolean {
diff --git a/example/integration_test/shared.dart b/example/integration_test/shared.dart
@@ -61,6 +61,10 @@ const double startLocationLng = 23.510763;
 /// Timeout for tests in seconds.
 const int testTimeoutSeconds = 240; // 4 minutes
 
+/// Timeout for controller completer in seconds. This timeout is set to be
+/// long as on CI emulator the controller creation can take a while.
+const int controllerCompleterTimeoutSeconds = 30;
+
 const NativeAutomatorConfig _nativeAutomatorConfig = NativeAutomatorConfig(
   findTimeout: Duration(seconds: 20),
 );
@@ -190,8 +194,8 @@ Future<GoogleNavigationViewController> startNavigation(
     void Function(CameraPosition)? onCameraIdle,
     void Function(CameraPosition)? onCameraStartedFollowingLocation,
     void Function(CameraPosition)? onCameraStoppedFollowingLocation}) async {
-  final Completer<GoogleNavigationViewController> controllerCompleter =
-      Completer<GoogleNavigationViewController>();
+  final ControllerCompleter<GoogleNavigationViewController>
+      controllerCompleter = ControllerCompleter();
 
   await checkLocationDialogAndTosAcceptance($);
 
@@ -433,8 +437,8 @@ Future<GoogleMapViewController> startMapView(
       onRecenterButtonClicked,
   void Function(CameraPosition)? onCameraIdle,
 }) async {
-  final Completer<GoogleMapViewController> controllerCompleter =
-      Completer<GoogleMapViewController>();
+  final ControllerCompleter<GoogleMapViewController> controllerCompleter =
+      ControllerCompleter();
 
   //await checkLocationDialogAndTosAcceptance($);
 
@@ -507,3 +511,35 @@ int? colorToInt(Color? color) {
 /// Helper function to build a reason for the test.
 String buildReasonForToggle(String toggle, bool result) =>
     'set$toggle($result) should update the internal state so that a subsequent call to is$toggle returns $result.';
+
+/// A wrapper for `Completer<T>` to handle timeouts. T must be either
+/// [GoogleNavigationViewController] or [GoogleMapViewController].
+class ControllerCompleter<T> {
+  ControllerCompleter()
+      : assert(
+          T == GoogleNavigationViewController || T == GoogleMapViewController,
+          'T must be either GoogleNavigationViewController or GoogleMapViewController',
+        );
+
+  final Completer<T> _completer = Completer<T>();
+
+  /// Completes the completer with the provided [value].
+  void complete(T value) {
+    _completer.complete(value);
+  }
+
+  /// Returns the future of the completer. This future will complete
+  /// with the controller value or throw a [TestFailure] if timeout is reached.
+  Future<T> get future {
+    return _completer.future.timeout(
+      const Duration(seconds: controllerCompleterTimeoutSeconds),
+      onTimeout: () {
+        fail(
+          'Controller not created in time, '
+          'this could happen if view is disposed before onViewCreated '
+          'is called',
+        );
+      },
+    );
+  }
+}
diff --git a/example/integration_test/t01_initialization_test.dart b/example/integration_test/t01_initialization_test.dart
@@ -20,7 +20,6 @@
 // For more information about Flutter integration tests, please see
 // https://docs.flutter.dev/cookbook/testing/integration/introduction
 
-import 'dart:async';
 import 'dart:io';
 
 import 'package:flutter/material.dart';
@@ -183,8 +182,8 @@ void main() {
   });
 
   patrol(prefix('Test Maps initialization'), (PatrolIntegrationTester $) async {
-    final Completer<GoogleNavigationViewController> viewControllerCompleter =
-        Completer<GoogleNavigationViewController>();
+    final ControllerCompleter<GoogleNavigationViewController>
+        viewControllerCompleter = ControllerCompleter();
 
     await checkTermsAndConditionsAcceptance($);
     await checkLocationDialogAcceptance($);
@@ -220,7 +219,6 @@ void main() {
       GoogleMapsNavigationView(
         key: key,
         onViewCreated: (GoogleNavigationViewController controller) {
-          controller.setMyLocationEnabled(true);
           viewControllerCompleter.complete(controller);
         },
         initialCameraPosition: cameraPosition,
@@ -243,6 +241,9 @@ void main() {
 
     final GoogleNavigationViewController controller =
         await viewControllerCompleter.future;
+
+    await controller.setMyLocationEnabled(true);
+
     final CameraPosition cameraOut = await controller.getCameraPosition();
 
     expect(cameraOut.target.latitude,
@@ -276,8 +277,8 @@ void main() {
 
   patrol(prefix('Test Maps initialization without navigation'),
       (PatrolIntegrationTester $) async {
-    final Completer<GoogleMapViewController> viewControllerCompleter =
-        Completer<GoogleMapViewController>();
+    final ControllerCompleter<GoogleMapViewController> viewControllerCompleter =
+        ControllerCompleter<GoogleMapViewController>();
 
     const CameraPosition cameraPosition =
         CameraPosition(target: LatLng(latitude: 65, longitude: 25.5), zoom: 12);
@@ -300,7 +301,6 @@ void main() {
       GoogleMapsMapView(
         key: key,
         onViewCreated: (GoogleMapViewController controller) {
-          controller.setMyLocationEnabled(true);
           viewControllerCompleter.complete(controller);
         },
         initialCameraPosition: cameraPosition,
@@ -321,6 +321,9 @@ void main() {
 
     final GoogleMapViewController controller =
         await viewControllerCompleter.future;
+
+    await controller.setMyLocationEnabled(true);
+
     final CameraPosition cameraOut = await controller.getCameraPosition();
 
     expect(cameraOut.target.latitude,
diff --git a/example/integration_test/t04_navigation_ui_test.dart b/example/integration_test/t04_navigation_ui_test.dart
@@ -20,16 +20,14 @@
 // For more information about Flutter integration tests, please see
 // https://docs.flutter.dev/cookbook/testing/integration/introduction
 
-import 'dart:async';
-
 import 'package:flutter/material.dart';
 
 import 'shared.dart';
 
 void main() {
   patrol('Test enabling navigation UI', (PatrolIntegrationTester $) async {
-    final Completer<GoogleNavigationViewController> viewControllerCompleter =
-        Completer<GoogleNavigationViewController>();
+    final ControllerCompleter<GoogleNavigationViewController>
+        viewControllerCompleter = ControllerCompleter();
 
     /// For testing NavigationUIEnabledChanged
     bool navigationUIisEnabled = false;
@@ -49,7 +47,6 @@ void main() {
       GoogleMapsNavigationView(
         key: key,
         onViewCreated: (GoogleNavigationViewController controller) {
-          controller.setMyLocationEnabled(true);
           viewControllerCompleter.complete(controller);
         },
         onNavigationUIEnabledChanged: (bool isEnabled) {
@@ -62,6 +59,8 @@ void main() {
     final GoogleNavigationViewController viewController =
         await viewControllerCompleter.future;
 
+    await viewController.setMyLocationEnabled(true);
+
     expect(await viewController.isNavigationUIEnabled(), false,
         reason:
             'isNavigationUIEnabled should return false when navigation is not yet initialized.');
diff --git a/example/integration_test/t06_map_test.dart b/example/integration_test/t06_map_test.dart
@@ -20,9 +20,10 @@
 // For more information about Flutter integration tests, please see
 // https://docs.flutter.dev/cookbook/testing/integration/introduction
 
-import 'dart:async';
 import 'dart:io';
+
 import 'package:flutter/material.dart';
+
 import 'shared.dart';
 
 void main() {
@@ -56,8 +57,8 @@ void main() {
   patrol(
     'Test platform view creation params',
     (PatrolIntegrationTester $) async {
-      final Completer<GoogleMapViewController> controllerCompleter =
-          Completer<GoogleMapViewController>();
+      final ControllerCompleter<GoogleMapViewController> controllerCompleter =
+          ControllerCompleter<GoogleMapViewController>();
 
       switch (mapTypeVariants.currentValue!) {
         case TestMapType.mapView:
@@ -298,8 +299,9 @@ void main() {
     (PatrolIntegrationTester $) async {
       /// For some reason the functionality works on Android example app, but it doesn't work
       /// during the testing. Will skip Android testing for now.
-      final Completer<GoogleMapViewController> viewControllerCompleter =
-          Completer<GoogleMapViewController>();
+      final ControllerCompleter<GoogleMapViewController>
+          viewControllerCompleter =
+          ControllerCompleter<GoogleMapViewController>();
 
       await checkLocationDialogAcceptance($);
 
@@ -391,8 +393,9 @@ void main() {
     (PatrolIntegrationTester $) async {
       /// For some reason the functionality works on Android example app, but it doesn't work
       /// during the testing. Will skip Android testing for now.
-      final Completer<GoogleMapViewController> viewControllerCompleter =
-          Completer<GoogleMapViewController>();
+      final ControllerCompleter<GoogleMapViewController>
+          viewControllerCompleter =
+          ControllerCompleter<GoogleMapViewController>();
 
       await checkLocationDialogAcceptance($);
 
diff --git a/lib/src/google_maps_map_view.dart b/lib/src/google_maps_map_view.dart
@@ -283,7 +283,35 @@ class GoogleMapsMapView extends GoogleMapsBaseMapView {
       super.onCameraStartedFollowingLocation,
       super.onCameraStoppedFollowingLocation});
 
-  /// On view created callback.
+  /// Callback triggered when the map view is created.
+  ///
+  /// Provides a [OnMapViewCreatedCallback] for interacting with and
+  /// controlling the map after initialization.
+  ///
+  /// To ensure safe usage, wrap controller calls inside a `try-catch` block
+  /// as native method calls are asynchronous. This prevents exceptions if the
+  /// view is unmounted before the native message is handled on the platform
+  /// side.
+  ///
+  /// Example:
+  /// ```dart
+  /// onViewCreated: (controller) async {
+  ///   try {
+  ///     final CameraUpdate cameraUpdate = CameraUpdate.newLatLng(
+  ///       const LatLng(latitude: 12.3456, longitude: 12.3456),
+  ///     );
+  ///     await controller.setCameraPosition(CameraPosition(
+  ///       target: LatLng(37.7749, -122.4194),
+  ///       zoom: 12,
+  ///     ));
+  ///   } on PlatformException catch (exception, stack) {
+  ///     if (exception.code == 'viewNotFound') {
+  ///       // Handle the case when the view is disposed before the call is
+  ///       // handled on the platform side.
+  ///     }
+  ///   }
+  /// },
+  /// ```
   final OnMapViewCreatedCallback onViewCreated;
 
   /// Creates a [State] for this [GoogleMapsMapView].
diff --git a/lib/src/google_maps_navigation_view.dart b/lib/src/google_maps_navigation_view.dart
@@ -88,7 +88,35 @@ class GoogleMapsNavigationView extends GoogleMapsBaseMapView {
       super.onCameraStartedFollowingLocation,
       super.onCameraStoppedFollowingLocation});
 
-  /// On view created callback.
+  /// Callback triggered when the navigation view is created.
+  ///
+  /// Provides a [GoogleMapsNavigationViewController] for interacting with and
+  /// controlling the map after initialization.
+  ///
+  /// To ensure safe usage, wrap controller calls inside a `try-catch` block
+  /// as native method calls are asynchronous. This prevents exceptions if the
+  /// view is unmounted before the native message is handled on the platform
+  /// side.
+  ///
+  /// Example:
+  /// ```dart
+  /// onViewCreated: (controller) async {
+  ///   try {
+  ///     final CameraUpdate cameraUpdate = CameraUpdate.newLatLng(
+  ///       const LatLng(latitude: 12.3456, longitude: 12.3456),
+  ///     );
+  ///     await controller.setCameraPosition(CameraPosition(
+  ///       target: LatLng(37.7749, -122.4194),
+  ///       zoom: 12,
+  ///     ));
+  ///   } on PlatformException catch (exception, stack) {
+  ///     if (exception.code == 'viewNotFound') {
+  ///       // Handle the case when the view is disposed before the call is
+  ///       // handled on the platform side.
+  ///     }
+  ///   }
+  /// },
+  /// ```
   final OnNavigationViewCreatedCallback onViewCreated;
 
   /// Determines the initial visibility of the navigation UI on map initialization.
diff --git a/lib/src/google_navigation_flutter_android.dart b/lib/src/google_navigation_flutter_android.dart
@@ -92,12 +92,29 @@ class GoogleMapsNavigationAndroid extends GoogleMapsNavigationPlatform {
     return AndroidView(
       viewType: viewType,
       onPlatformViewCreated: (int viewId) async {
-        onPlatformViewCreated(viewId);
+        try {
+          onPlatformViewCreated(viewId);
 
-        // On Android the map is initialized asyncronously.
-        // Wait map to be ready before calling [onMapReady] callback
-        await viewAPI.awaitMapReady(viewId: viewId);
-        onMapReady(viewId);
+          // On Android the map is initialized asyncronously.
+          // Wait map to be ready before calling [onMapReady] callback
+          await viewAPI.awaitMapReady(viewId: viewId);
+          onMapReady(viewId);
+        } on PlatformException catch (exception, stack) {
+          if (exception.code == 'viewNotFound') {
+            // This exeption can happen if the view is disposed before the calls
+            // are made to the platform side. We can ignore this exception as
+            // the view is already disposed.
+            return;
+          } else {
+            // Pass other exceptions to the Flutter error handler.
+            FlutterError.reportError(FlutterErrorDetails(
+              exception: exception,
+              stack: stack,
+              library: 'google_navigation_flutter',
+              context: ErrorDescription(exception.message ?? ''),
+            ));
+          }
+        }
       },
       gestureRecognizers: initializationOptions.gestureRecognizers,
       layoutDirection: initializationOptions.layoutDirection,
diff --git a/lib/src/google_navigation_flutter_ios.dart b/lib/src/google_navigation_flutter_ios.dart
@@ -94,11 +94,28 @@ class GoogleMapsNavigationIOS extends GoogleMapsNavigationPlatform {
       creationParams: creationParams.encode(),
       creationParamsCodec: const StandardMessageCodec(),
       onPlatformViewCreated: (int viewId) async {
-        onPlatformViewCreated(viewId);
+        try {
+          onPlatformViewCreated(viewId);
 
-        // Wait map to be ready before calling [onMapReady] callback
-        await viewAPI.awaitMapReady(viewId: viewId);
-        onMapReady(viewId);
+          // Wait map to be ready before calling [onMapReady] callback
+          await viewAPI.awaitMapReady(viewId: viewId);
+          onMapReady(viewId);
+        } on PlatformException catch (exception, stack) {
+          if (exception.code == 'viewNotFound') {
+            // This exeption can happen if the view is disposed before the calls
+            // are made to the platform side. We can ignore this exception as
+            // the view is already disposed.
+            return;
+          } else {
+            // Pass other exceptions to the Flutter error handler.
+            FlutterError.reportError(FlutterErrorDetails(
+              exception: exception,
+              stack: stack,
+              library: 'google_navigation_flutter',
+              context: ErrorDescription(exception.message ?? ''),
+            ));
+          }
+        }
       },
       gestureRecognizers: initializationOptions.gestureRecognizers,
       layoutDirection: initializationOptions.layoutDirection,

Original file line number	Diff line number	Diff line change
`@@ -40,7 +40,11 @@ class GoogleMapsViewMessageHandler(private val viewRegistry: GoogleMapsViewRegis`
`40`	`40`	`}`
`41`	`41`
`42`	`42`	`override fun awaitMapReady(viewId: Long, callback: (Result<Unit>) -> Unit) {`
`43`		`- return getView(viewId.toInt()).awaitMapReady(callback)`
	`43`	`+ try {`
	`44`	`+ getView(viewId.toInt()).awaitMapReady(callback)`
	`45`	`+ } catch (e: Throwable) {`
	`46`	`+ callback(Result.failure(e))`
	`47`	`+ }`
`44`	`48`	`}`
`45`	`49`
`46`	`50`	`override fun isMyLocationEnabled(viewId: Long): Boolean {`