feat: Introduce a robust Google Maps initializer (#758)

* feat: Introduce a robust Google Maps initializer

This commit refactors the map initialization logic to be more robust and
test-friendly.

Previously, the map initialization was coupled with the attribution ID
logic, which made it difficult to handle initialization failures,
especially in test environments where the Maps SDK might be mocked.

This change introduces a new `GoogleMapsInitializer` object that manages
the initialization process with a state machine. This provides more
control over the initialization process and allows for better error
handling.

The key changes are:

- A new `GoogleMapsInitializer` object that manages the initialization
  of the Google Maps SDK.
- An `InitializationState` enum that represents the different states of
  the initialization process.
- An `initialize` function that starts the initialization process on a
  background thread.
- A `reset` function that allows for re-initialization in test
  environments.
- The `GoogleMap` composable now uses the `GoogleMapsInitializer` to
  ensure that the map is only displayed after the SDK has been
  successfully initialized.

* chore: address copyright header issues

* refactor: Make GoogleMapsInitializer suspendable

This change refactors the `GoogleMapsInitializer` to use suspend functions for initialization and reset operations, improving its testability and adherence to structured concurrency.

Key changes:
- Converted `GoogleMapsInitializer.initialize()` and `GoogleMapsInitializer.reset()` to `suspend` functions.
- Removed the internal `CoroutineScope` and job management from `GoogleMapsInitializer`.
- Updated unit and instrumentation tests to use `runTest` from `kotlinx-coroutines-test`, removing the need for `Thread.sleep()`.
- Added the `kotlinx-coroutines-test` dependency to the `maps-app` module.

* refactor(maps-compose): Make GoogleMapsInitializer fully suspending

The `initialize` function has been refactored to be a fully suspending operation.

Key changes:
- Replaced `launch(Dispatchers.IO)` with `withContext(Dispatchers.IO)`. This ensures the `initialize` function suspends until the blocking initialization call is complete, rather than returning immediately.
- Added explicit handling for non-SUCCESS results from `MapsInitializer.initialize()` to set the state to `FAILURE`.
- Restructured the `try-catch` block to correctly handle exceptions from the `withContext` block.

* chore: Update Material, Robolectric, and Truth dependencies

* test: Add StrictMode check to GoogleMapsInitializerTest

Wraps the `GoogleMapsInitializer.initialize()` call with strict
StrictMode policies. This ensures the initialization process does not
perform any violations, such as disk reads, which would cause the
test to fail.

* test: Refactor GoogleMapViewTests to use Truth assertions

Key changes:
- Introduced a custom `LatLngSubject` for the Truth assertion library to allow for `LatLng` comparisons with a tolerance.
- Migrated assertions in `GoogleMapViewTests` from JUnit to Truth for improved readability and more expressive tests.
- Added explicit Google Maps SDK initialization within the test setup.

* chore: add license headers to test files

Author: dkhawk

gradle/libs.versions.toml

@@ -1,6 +1,6 @@
 [versions]
 activitycompose = "1.10.1"
-agp = "8.12.1"
+agp = "8.13.0"
 androidCore = "1.7.0"
 androidx-core = "1.17.0"
 androidxtest = "1.7.0"
@@ -19,7 +19,9 @@ mapsktx = "5.2.0"
 org-jacoco-core = "0.8.13"
 screenshot = "0.0.1-alpha11"
 constraintlayout = "2.2.1"
-material = "1.12.0"
+material = "1.13.0"
+robolectric = "4.16"
+truth = "1.4.4"
 
 [libraries]
 android-gradle-plugin = { module = "com.android.tools.build:gradle", version.ref = "agp" }
@@ -53,6 +55,8 @@ test-junit = { module = "junit:junit", version.ref = "junit" }
 androidx-constraintlayout = { group = "androidx.constraintlayout", name = "constraintlayout", version.ref = "constraintlayout" }
 material = { group = "com.google.android.material", name = "material", version.ref = "material" }
 screenshot-validation-api = { group = "com.android.tools.screenshot", name = "screenshot-validation-api", version.ref = "screenshot" }
+robolectric = { module = "org.robolectric:robolectric", version.ref = "robolectric" }
+truth = { module = "com.google.truth:truth", version.ref = "truth" }
 
 [plugins]
 android-application = { id = "com.android.application", version.ref = "agp" }

maps-app/build.gradle.kts

@@ -81,6 +81,13 @@ dependencies {
     androidTestImplementation(libs.test.junit)
     androidTestImplementation(libs.androidx.test.compose.ui)
     androidTestImplementation(libs.kotlinx.coroutines.test)
+    androidTestImplementation(libs.truth)
+
+    testImplementation(libs.test.junit)
+    testImplementation(libs.robolectric)
+    testImplementation(libs.androidx.test.core)
+    testImplementation(libs.truth)
+    testImplementation(libs.kotlinx.coroutines.test)
 
     screenshotTestImplementation(libs.androidx.compose.ui.tooling)
 

maps-app/src/androidTest/java/com/google/maps/android/compose/GoogleMapViewTests.kt

@@ -14,6 +14,7 @@
 
 package com.google.maps.android.compose
 
+import android.content.Context
 import androidx.compose.foundation.layout.Box
 import androidx.compose.foundation.layout.fillMaxSize
 import androidx.compose.material.Text
@@ -25,9 +26,14 @@ import androidx.compose.ui.test.junit4.createComposeRule
 import androidx.compose.ui.test.onNodeWithTag
 import androidx.compose.ui.test.onNodeWithText
 import androidx.compose.ui.test.performClick
+import androidx.test.platform.app.InstrumentationRegistry
 import com.google.android.gms.maps.model.CameraPosition
 import com.google.android.gms.maps.model.LatLng
-import org.junit.Assert.*
+import com.google.common.truth.Truth.assertThat
+import com.google.maps.android.compose.LatLngSubject.Companion.assertThat
+import com.google.maps.android.compose.internal.GoogleMapsInitializer
+import com.google.maps.android.compose.internal.InitializationState
+import kotlinx.coroutines.runBlocking
 import org.junit.Before
 import org.junit.Rule
 import org.junit.Test
@@ -46,6 +52,15 @@ class GoogleMapViewTests {
     private fun initMap(content: @Composable () -> Unit = {}) {
         check(hasValidApiKey) { "Maps API key not specified" }
         val countDownLatch = CountDownLatch(1)
+
+        val appContext: Context = InstrumentationRegistry.getInstrumentation().targetContext
+
+        runBlocking {
+            GoogleMapsInitializer.initialize(appContext)
+        }
+
+        assertThat(GoogleMapsInitializer.state.value).isEqualTo(InitializationState.SUCCESS)
+
         composeTestRule.setContent {
             GoogleMapView(
                 modifier = Modifier.fillMaxSize(),
@@ -59,7 +74,7 @@ class GoogleMapViewTests {
             }
         }
         val mapLoaded = countDownLatch.await(30, TimeUnit.SECONDS)
-        assertTrue("Map loaded", mapLoaded)
+        assertThat(mapLoaded).isTrue()
     }
 
     @Before
@@ -75,32 +90,32 @@ class GoogleMapViewTests {
     @Test
     fun testStartingCameraPosition() {
         initMap()
-        startingPosition.assertEquals(cameraPositionState.position.target)
+        assertThat(cameraPositionState.position.target).isEqualTo(startingPosition)
     }
 
     @Test
     fun testRightInitialColorScheme() {
         initMap()
-        mapColorScheme.assertEquals(ComposeMapColorScheme.FOLLOW_SYSTEM)
+        assertThat(mapColorScheme).isEqualTo(ComposeMapColorScheme.FOLLOW_SYSTEM)
     }
 
     @Test
-    fun testRighColorSchemeAfterChangingIt() {
+    fun testRightColorSchemeAfterChangingIt() {
         mapColorScheme = ComposeMapColorScheme.DARK
         initMap()
-        mapColorScheme.assertEquals(ComposeMapColorScheme.DARK)
+        assertThat(mapColorScheme).isEqualTo(ComposeMapColorScheme.DARK)
     }
 
     @Test
     fun testCameraReportsMoving() {
         initMap()
-        assertEquals(CameraMoveStartedReason.NO_MOVEMENT_YET, cameraPositionState.cameraMoveStartedReason)
+        assertThat(cameraPositionState.cameraMoveStartedReason).isEqualTo(CameraMoveStartedReason.NO_MOVEMENT_YET)
         zoom(shouldAnimate = true, zoomIn = true) {
             composeTestRule.waitUntil(timeout2) {
                 cameraPositionState.isMoving
             }
-            assertTrue(cameraPositionState.isMoving)
-            assertEquals(CameraMoveStartedReason.DEVELOPER_ANIMATION, cameraPositionState.cameraMoveStartedReason)
+            assertThat(cameraPositionState.isMoving).isTrue()
+            assertThat(cameraPositionState.cameraMoveStartedReason).isEqualTo(CameraMoveStartedReason.DEVELOPER_ANIMATION)
         }
     }
 
@@ -114,7 +129,7 @@ class GoogleMapViewTests {
             composeTestRule.waitUntil(timeout5) {
                 !cameraPositionState.isMoving
             }
-            assertFalse(cameraPositionState.isMoving)
+            assertThat(cameraPositionState.isMoving).isFalse()
         }
     }
 
@@ -128,11 +143,7 @@ class GoogleMapViewTests {
             composeTestRule.waitUntil(timeout3) {
                 !cameraPositionState.isMoving
             }
-            assertEquals(
-                startingZoom + 1f,
-                cameraPositionState.position.zoom,
-                assertRoundingError.toFloat()
-            )
+            assertThat(cameraPositionState.position.zoom).isWithin(assertRoundingError.toFloat()).of(startingZoom + 1f)
         }
     }
 
@@ -146,11 +157,7 @@ class GoogleMapViewTests {
             composeTestRule.waitUntil(timeout3) {
                 !cameraPositionState.isMoving
             }
-            assertEquals(
-                startingZoom + 1f,
-                cameraPositionState.position.zoom,
-                assertRoundingError.toFloat()
-            )
+            assertThat(cameraPositionState.position.zoom).isWithin(assertRoundingError.toFloat()).of(startingZoom + 1f)
         }
     }
 
@@ -164,11 +171,7 @@ class GoogleMapViewTests {
             composeTestRule.waitUntil(timeout3) {
                 !cameraPositionState.isMoving
             }
-            assertEquals(
-                startingZoom - 1f,
-                cameraPositionState.position.zoom,
-                assertRoundingError.toFloat()
-            )
+            assertThat(cameraPositionState.position.zoom).isWithin(assertRoundingError.toFloat()).of(startingZoom - 1f)
         }
     }
 
@@ -182,11 +185,7 @@ class GoogleMapViewTests {
             composeTestRule.waitUntil(timeout3) {
                 !cameraPositionState.isMoving
             }
-            assertEquals(
-                startingZoom - 1f,
-                cameraPositionState.position.zoom,
-                assertRoundingError.toFloat()
-            )
+            assertThat(cameraPositionState.position.zoom).isWithin(assertRoundingError.toFloat()).of(startingZoom - 1f)
         }
     }
 
@@ -195,10 +194,10 @@ class GoogleMapViewTests {
         initMap()
         composeTestRule.runOnUiThread {
             val projection = cameraPositionState.projection
-            assertNotNull(projection)
-            assertTrue(
+            assertThat(projection).isNotNull()
+            assertThat(
                 projection!!.visibleRegion.latLngBounds.contains(startingPosition)
-            )
+            ).isTrue()
         }
     }
 
@@ -207,11 +206,11 @@ class GoogleMapViewTests {
         initMap()
         composeTestRule.runOnUiThread {
             val projection = cameraPositionState.projection
-            assertNotNull(projection)
+            assertThat(projection).isNotNull()
             val latLng = LatLng(23.4, 25.6)
-            assertFalse(
+            assertThat(
                 projection!!.visibleRegion.latLngBounds.contains(latLng)
-            )
+            ).isFalse()
         }
     }
 
@@ -295,15 +294,15 @@ class GoogleMapViewTests {
             markerState = rememberUpdatedMarkerState(position = positionState.value)
         }
 
-        assertEquals(testPoint0, markerState.position)
+        assertThat(markerState.position).isEqualTo(testPoint0)
 
         positionState.value = testPoint1
         composeTestRule.waitForIdle()
-        assertEquals(testPoint1, markerState.position)
+        assertThat(markerState.position).isEqualTo(testPoint1)
 
         positionState.value = testPoint2
         composeTestRule.waitForIdle()
-        assertEquals(testPoint2, markerState.position)
+        assertThat(markerState.position).isEqualTo(testPoint2)
     }
 
     private fun zoom(
@@ -322,4 +321,4 @@ class GoogleMapViewTests {
 
         assertionBlock()
     }
-}
+}

maps-app/src/androidTest/java/com/google/maps/android/compose/GoogleMapsInitializerTest.kt

@@ -0,0 +1,74 @@
+// Copyright 2025 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+package com.google.maps.android.compose
+
+import android.content.Context
+import android.os.StrictMode
+import androidx.test.ext.junit.runners.AndroidJUnit4
+import androidx.test.platform.app.InstrumentationRegistry
+import com.google.common.truth.Truth.assertThat
+import com.google.maps.android.compose.internal.GoogleMapsInitializer
+import com.google.maps.android.compose.internal.InitializationState
+import kotlinx.coroutines.ExperimentalCoroutinesApi
+import kotlinx.coroutines.test.runTest
+import org.junit.After
+import org.junit.Test
+import org.junit.runner.RunWith
+
+@OptIn(ExperimentalCoroutinesApi::class)
+@RunWith(AndroidJUnit4::class)
+class GoogleMapsInitializerTest {
+
+    @After
+    fun tearDown() = runTest {
+        GoogleMapsInitializer.reset()
+    }
+
+    @Test
+    fun testInitializationSuccess() = runTest {
+        // In an instrumentation test environment, Google Play services are available.
+        // Therefore, we expect the initialization to succeed.
+
+        val context: Context = InstrumentationRegistry.getInstrumentation().targetContext
+
+        // Note: we need to establish the Strict Mode settings here as there are violations outside
+        // of our control if we try to set them in setUp
+        val threadPolicy = StrictMode.getThreadPolicy()
+        val vmPolicy = StrictMode.getVmPolicy()
+
+        StrictMode.setThreadPolicy(
+            StrictMode.ThreadPolicy.Builder()
+                .detectDiskReads()
+                .detectAll()
+                .penaltyLog()
+                .penaltyDeath()
+                .build()
+        )
+        StrictMode.setVmPolicy(
+            StrictMode.VmPolicy.Builder()
+                .detectAll()
+                .detectLeakedClosableObjects()
+                .penaltyLog()
+                .penaltyDeath()
+                .build()
+        )
+
+        GoogleMapsInitializer.initialize(context)
+
+        StrictMode.setThreadPolicy(threadPolicy)
+        StrictMode.setVmPolicy(vmPolicy)
+
+        assertThat(GoogleMapsInitializer.state.value).isEqualTo(InitializationState.SUCCESS)
+    }
+}

maps-app/src/androidTest/java/com/google/maps/android/compose/LatLngSubject.kt

@@ -0,0 +1,56 @@
+
+// Copyright 2025 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//      http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package com.google.maps.android.compose
+
+import com.google.android.gms.maps.model.LatLng
+import com.google.common.truth.FailureMetadata
+import com.google.common.truth.Subject
+import com.google.common.truth.Truth.assertAbout
+
+/**
+ * A [Subject] for asserting facts about [LatLng] objects.
+ */
+class LatLngSubject(
+    failureMetadata: FailureMetadata,
+    private val actual: LatLng?
+) : Subject(failureMetadata, actual) {
+
+    /**
+     * Asserts that the subject is equal to the given [expected] value, with a given [tolerance].
+     */
+    fun isEqualTo(expected: LatLng, tolerance: Double = 1e-6) {
+        if (actual == null) {
+            failWithActual("expected", expected)
+            return
+        }
+
+        check("latitude").that(actual.latitude).isWithin(tolerance).of(expected.latitude)
+        check("longitude").that(actual.longitude).isWithin(tolerance).of(expected.longitude)
+    }
+
+    companion object {
+        /**
+         * A factory for creating [LatLngSubject] instances.
+         */
+        fun assertThat(actual: LatLng?): LatLngSubject {
+            return assertAbout(latLngs()).that(actual)
+        }
+
+        private fun latLngs(): (failureMetadata: FailureMetadata, actual: LatLng?) -> LatLngSubject {
+            return ::LatLngSubject
+        }
+    }
+}