feat(api-loader): migrate to @googlemaps/js-api-loader (#885)

Migrates the loading mechanism for the Maps JavaScript API from a custom implementation to the official `@googlemaps/js-api-loader`.

This involves several key steps:
*   Removing the existing custom loader and its associated tests.
*   Updating the `api-provider` to utilize `@googlemaps/js-api-loader`.
*   Refactoring existing tests. These refactorings aim to prevent integration testing and remove direct usage of the `APIProvider` component in unrelated tests

Co-authored-by: Martin Schuhfuss <m.schuhfuss@gmail.com>

Author: pappkartoni

package-lock.json

@@ -56,6 +56,7 @@
     "Maps"
   ],
   "dependencies": {
+    "@googlemaps/js-api-loader": "^2.0.2",
     "@types/google.maps": "^3.54.10",
     "fast-deep-equal": "^3.1.3"
   },

package.json

@@ -1,23 +1,60 @@
 import React, {useContext} from 'react';
-import {act, render, screen} from '@testing-library/react';
-import {initialize} from '@googlemaps/jest-mocks';
+import {act, cleanup, render, screen, waitFor} from '@testing-library/react';
+import {
+  importLibrary as importLibraryMock,
+  initialize
+} from '@googlemaps/jest-mocks';
 import '@testing-library/jest-dom';
 
-// FIXME: this should no longer be needed with the next version of @googlemaps/jest-mocks
-import {importLibraryMock} from '../../libraries/__mocks__/lib/import-library-mock';
-
 import {VERSION} from '../../version';
 import {
+  __resetModuleState as resetAPIProviderState,
   APIProvider,
   APIProviderContext,
   APIProviderContextValue
 } from '../api-provider';
-import {ApiParams} from '../../libraries/google-maps-api-loader';
+
 import {useApiIsLoaded} from '../../hooks/use-api-is-loaded';
 import {APILoadingStatus} from '../../libraries/api-loading-status';
 
-const apiLoadSpy = jest.fn();
-const apiUnloadSpy = jest.fn();
+type ImportLibraryResult = Awaited<
+  ReturnType<typeof google.maps.importLibrary>
+>;
+
+let importLibraryPromise: Promise<ImportLibraryResult>;
+let resolveImportLibrary: (value: ImportLibraryResult) => void;
+let rejectImportLibrary: (reason?: unknown) => void;
+
+const resetImportLibraryPromise = () => {
+  ({
+    promise: importLibraryPromise,
+    resolve: resolveImportLibrary,
+    reject: rejectImportLibrary
+  } = Promise.withResolvers<ImportLibraryResult>());
+};
+
+const triggerMapsApiLoaded = () => {
+  resolveImportLibrary({} as google.maps.CoreLibrary);
+};
+
+const triggerLoadingFailed = () => {
+  rejectImportLibrary(new Error('loading failed'));
+};
+
+const setOptionsSpy = jest.fn();
+
+jest.mock('@googlemaps/js-api-loader', () => {
+  return {
+    setOptions: jest.fn((options: Record<string, unknown>) => {
+      setOptionsSpy(options);
+    }),
+    importLibrary: jest.fn(async (name: string) => {
+      await importLibraryPromise;
+
+      return importLibraryMock(name);
+    })
+  };
+});
 
 const ContextSpyComponent = () => {
   const context = useContext(APIProviderContext);
@@ -27,47 +64,20 @@ const ContextSpyComponent = () => {
 };
 ContextSpyComponent.spy = jest.fn();
 
-let triggerMapsApiLoaded: () => void;
-let triggerLoadingFailed: () => void;
-
-jest.mock('../../libraries/google-maps-api-loader', () => {
-  class GoogleMapsApiLoader {
-    static async load(
-      params: ApiParams,
-      onLoadingStatusChange: (s: APILoadingStatus) => void
-    ): Promise<void> {
-      apiLoadSpy(params);
-      onLoadingStatusChange(APILoadingStatus.LOADING);
-
-      google.maps.importLibrary = importLibraryMock;
-
-      return new Promise((resolve, reject) => {
-        triggerLoadingFailed = () => {
-          reject();
-          onLoadingStatusChange(APILoadingStatus.FAILED);
-        };
-
-        triggerMapsApiLoaded = () => {
-          resolve();
-          onLoadingStatusChange(APILoadingStatus.LOADED);
-        };
-      });
-    }
-
-    static unload() {
-      apiUnloadSpy();
-    }
-  }
-
-  return {__esModule: true, GoogleMapsApiLoader};
-});
-
 beforeEach(() => {
   initialize();
   jest.clearAllMocks();
+  // @ts-expect-error - accessing mock implementation
+  window.google.maps.importLibrary = undefined;
+  resetAPIProviderState();
+  resetImportLibraryPromise();
 });
 
-test('passes parameters to GoogleMapsAPILoader', () => {
+afterEach(() => {
+  cleanup();
+});
+
+test('passes parameters to GoogleMapsAPILoader', async () => {
   render(
     <APIProvider
       apiKey={'apikey'}
@@ -79,9 +89,11 @@ test('passes parameters to GoogleMapsAPILoader', () => {
       authReferrerPolicy={'origin'}></APIProvider>
   );
 
-  expect(apiLoadSpy.mock.lastCall[0]).toMatchObject({
+  await waitFor(() => expect(setOptionsSpy).toHaveBeenCalled());
+
+  expect(setOptionsSpy.mock.lastCall[0]).toMatchObject({
     key: 'apikey',
-    libraries: 'places,marker',
+    libraries: ['places', 'marker'],
     v: 'beta',
     language: 'en',
     region: 'us',
@@ -90,24 +102,30 @@ test('passes parameters to GoogleMapsAPILoader', () => {
   });
 });
 
-test('passes parameters to GoogleMapsAPILoader', () => {
+test('passes parameters to GoogleMapsAPILoader', async () => {
   render(<APIProvider apiKey={'apikey'} version={'version'}></APIProvider>);
 
-  const actual = apiLoadSpy.mock.lastCall[0];
+  await waitFor(() => expect(setOptionsSpy).toHaveBeenCalled());
+
+  const actual = setOptionsSpy.mock.lastCall[0];
   expect(actual).toMatchObject({key: 'apikey', v: 'version'});
 });
 
-test('uses default solutionChannel', () => {
+test('uses default solutionChannel', async () => {
   render(<APIProvider apiKey={'apikey'}></APIProvider>);
 
-  const actual = apiLoadSpy.mock.lastCall[0];
+  await waitFor(() => expect(setOptionsSpy).toHaveBeenCalled());
+
+  const actual = setOptionsSpy.mock.lastCall[0];
   expect(actual.solutionChannel).toBe('GMP_visgl_rgmlibrary_v1_default');
 });
 
-test("doesn't set solutionChannel when specified as empty string", () => {
+test("doesn't set solutionChannel when specified as empty string", async () => {
   render(<APIProvider apiKey={'apikey'} solutionChannel={''}></APIProvider>);
 
-  const actual = apiLoadSpy.mock.lastCall[0];
+  await waitFor(() => expect(setOptionsSpy).toHaveBeenCalled());
+
+  const actual = setOptionsSpy.mock.lastCall[0];
   expect(actual).not.toHaveProperty('solutionChannel');
 });
 
@@ -125,7 +143,9 @@ test('renders inner components', async () => {
 
   expect(screen.getByText('not loaded')).toBeInTheDocument();
 
-  await act(() => triggerMapsApiLoaded());
+  await act(async () => {
+    triggerMapsApiLoaded();
+  });
 
   expect(screen.getByText('loaded')).toBeInTheDocument();
 });
@@ -145,7 +165,10 @@ test('provides context values', async () => {
   expect(actualContext.mapInstances).toEqual({});
 
   contextSpy.mockReset();
-  await act(() => triggerMapsApiLoaded());
+
+  await act(async () => {
+    triggerMapsApiLoaded();
+  });
 
   expect(contextSpy).toHaveBeenCalled();
 
@@ -192,9 +215,9 @@ test('calls onError when loading the Google Maps JavaScript API fails', async ()
 
   render(<APIProvider apiKey={'apikey'} onError={onErrorMock}></APIProvider>);
 
-  await act(() => triggerLoadingFailed());
+  triggerLoadingFailed();
 
-  expect(onErrorMock).toHaveBeenCalled();
+  await waitFor(() => expect(onErrorMock).toHaveBeenCalled());
 });
 
 describe('internalUsageAttributionIds', () => {

src/components/__tests__/api-provider.test.tsx

@@ -50,7 +50,7 @@ afterEach(() => {
 });
 
 describe('<InfoWindow> basic functionality', () => {
-  test('Infowindow is created once mapsLibrary is ready', async () => {
+  test('Infowindow is created once mapsLibrary is ready', () => {
     useMapsLibraryMock.mockReturnValue(null);
     useMapMock.mockReturnValue(null);
 
@@ -75,7 +75,7 @@ describe('<InfoWindow> basic functionality', () => {
     expect(iw.open).toHaveBeenCalled();
   });
 
-  test('props get forwarded to constructor on initial creation', async () => {
+  test('props get forwarded to constructor on initial creation', () => {
     render(
       <InfoWindow
         ariaLabel={'ariaLabel'}
@@ -105,7 +105,7 @@ describe('<InfoWindow> basic functionality', () => {
     expect(actualOptions.pixelOffset.height).toBe(6);
   });
 
-  test('changing options get passed to setOptions()', async () => {
+  test('changing options get passed to setOptions()', () => {
     const position = {lat: 1, lng: 2};
     const {rerender} = render(<InfoWindow position={position}></InfoWindow>);
 
@@ -131,7 +131,7 @@ describe('<InfoWindow> basic functionality', () => {
     });
   });
 
-  test('props get forwarded to openOptions', async () => {
+  test('props get forwarded to openOptions', () => {
     const marker = new google.maps.marker.AdvancedMarkerElement();
 
     render(<InfoWindow anchor={marker} shouldFocus={false}></InfoWindow>);
@@ -146,7 +146,7 @@ describe('<InfoWindow> basic functionality', () => {
 });
 
 describe('<InfoWindow> content rendering', () => {
-  test('InfoWindow should render content into portal node', async () => {
+  test('InfoWindow should render content into portal node', () => {
     render(
       <InfoWindow
         className={'infowindow-content'}
@@ -178,15 +178,15 @@ describe('<InfoWindow> content rendering', () => {
 });
 
 describe('<InfoWindow> headerContent rendering', () => {
-  test('passes headerContent to options when its a string', async () => {
+  test('passes headerContent to options when its a string', () => {
     render(<InfoWindow headerContent={'Infowindow Header'}></InfoWindow>);
 
     expect(createInfowindowSpy).toHaveBeenCalled();
     const [options] = createInfowindowSpy.mock.lastCall;
     expect(options).toEqual({headerContent: 'Infowindow Header'});
   });
 
-  test('creates a dom-element when passing a ReactNode', async () => {
+  test('creates a dom-element when passing a ReactNode', () => {
     render(<InfoWindow headerContent={<h3>Infowindow Header</h3>} />);
 
     expect(createInfowindowSpy).toHaveBeenCalled();
@@ -195,7 +195,7 @@ describe('<InfoWindow> headerContent rendering', () => {
     expect(options.headerContent).toContainHTML('<h3>Infowindow Header</h3>');
   });
 
-  test('updates html-content when content props changes', async () => {
+  test('updates html-content when content props changes', () => {
     const {rerender} = render(
       <InfoWindow headerContent={<h3>Infowindow Header</h3>}></InfoWindow>
     );
@@ -215,7 +215,7 @@ describe('<InfoWindow> headerContent rendering', () => {
     );
   });
 
-  test('changes from text- to html-content', async () => {
+  test('changes from text- to html-content', () => {
     const {rerender} = render(<InfoWindow headerContent="abcd"></InfoWindow>);
 
     rerender(
@@ -233,7 +233,7 @@ describe('<InfoWindow> headerContent rendering', () => {
     );
   });
 
-  test('changes from html-content to no content', async () => {
+  test('changes from html-content to no content', () => {
     const {rerender} = render(
       <InfoWindow headerContent={<h3>New Infowindow Header</h3>}></InfoWindow>
     );
@@ -270,7 +270,7 @@ describe('<InfoWindow> cleanup', () => {
 });
 
 describe('<InfoWindow> events', () => {
-  test('triggers onClose and onCloseClick handlers on event', async () => {
+  test('triggers onClose and onCloseClick handlers on event', () => {
     const onCloseSpy = jest.fn();
     const onCloseClickSpy = jest.fn();
 
@@ -294,7 +294,7 @@ describe('<InfoWindow> events', () => {
     );
   });
 
-  test('removes handlers on unmount', async () => {
+  test('removes handlers on unmount', () => {
     const listeners = {
       close: {remove: jest.fn()},
       closeclick: {remove: jest.fn()}