Testing Components Using @vis.gl/react-google-maps & @googlemaps/jest-mocks

[apeTrackunit]

Hello everyone,

I'm currently facing an issue while testing components that use the @vis.gl/react-google-maps library. I have created a mock to simulate the behavior of the map component, but I'm unable to render children (markers, etc.) within the map.

Here's the mock I've created:

import { initialize } from "@googlemaps/jest-mocks";

initialize();

jest.mock("@vis.gl/react-google-maps", () => {
  const originalModule = jest.requireActual("@vis.gl/react-google-maps");

  const mapOptions = { mapId: "Map 1" };
  const map = new google.maps.Map(document.createElement("div"), mapOptions);

  return {
    ...originalModule,
    useApiLoadingStatus: () => APILoadingStatus.LOADED,
    useApiIsLoaded: () => true,
    useMap: () => map,
  };
});

However, it seems that the mock I created might only be affecting my code and not the library internals. Consequently, I assume the map variable inside the library remains empty, resulting in children not rendering.

The relevant code snippet where the map variable is used is in the Map component:

// Inside Map component from @vis.gl/react-google-maps

const [map, mapRef] = useMapInstance(props, context);

// ...

return (
  <div
    ref={mapRef}
    data-testid={'map'}
    style={className ? undefined : combinedStyle}
    className={className}
    {...(id ? { id } : {})}
  >
    {map ? (
      <GoogleMapsContext.Provider value={{ map }}>
        {children}
      </GoogleMapsContext.Provider>
    ) : null}
  </div>
);

The map variable is created within the useMapInstance hook when apiIsLoaded is true. I'm not sure if my mock value is correctly reflected in this hook.

Any guidance or suggestions on how to properly test components would be greatly appreciated.

Thank you in advance for your help!

[usefulthink]

In general you should try to avoid testing what this library does and focus on what you are doing with the library.
Ideally, the code from this library doesn't even get executed in your tests.

For example – if all you need is the map, you can essentially mock it without any functionality:

const MapMock = jest.fn(() =>
  React.createElement('div', { 'data-testid': 'map-mock' })
);

With this you can inspect the MapMock in your tests using the usual assertions for jest.fn() (like check if correct prop values were passed etc).

The same goes for child-components like Marker and such. The only thing you need to know is that

• the components were created (by creating a mock like the one above and expect(MarkerMock).toHaveBeenCalled()) and
• they were added as children to the map (you can inspect the props parameter of the MapMock for that)

Everything beyond that shouldn't be your concern, and we'll take it from there :)

Now, if your code has to interact with the Google Maps API objects, like the actual google.maps.Map instance, things get a bit more complicated. First, you need to install and setup the @googlemaps/jest-mocks package in your tests:

import { initialize } from '@googlemaps/jest-mocks';

beforeEach(() => {
  initialize();
});

Then you need to create a mock for the useMap function that returns a mocked google.maps.Map object:

const useMapMock = jest.fn(() => {
  // the global google.maps namespace is provided by the @googlemaps/jest-mocks package
  return new google.maps.Map();
});

Now, in your test, you can retrieve the mocked map object and use it:

import {mockInstances} from '@googlemaps/jest-mocks';

test("something", () => {
    // [...run the code that uses the useMap hook]

    // retrieve the mock instance created in useMapMock
    const map = mockInstances.get(google.maps.Map).at(-1)!;
    
    // run assertions
});

Quite often, even that isn't enough, since you sometimes need to control the return value of a map-function or test how your application reacts to events. In those cases you need to extend the mocked google.maps.Map class to do that. I wrote a bit more about how to do that here: https://github.com/googlemaps/js-jest-mocks/#usage

I hope this helps you get started, and let me know if there are more questions.
We should definitely write a documentation page from this conversation :D

[usefulthink]

What do you mean when you say it's 'built on top of AdvancedMarker'? Can you provide a small example of what that looks like in your component? We can probably come up with a testing strategy that doesn't need the library code to actually run...

[apeTrackunit]

This is one of the components I want to create a test for. I can't access the content rendered in the body through dataTestId because the marker is not rendered.

export const CustomMarker = ({
  id,
  onClickLink,
  children,
  onMouseEnter,
  onMouseLeave,
  labelClassName,
  labelVisibility,
  marker,
  position,
  onClick,
  className,
  dataTestId = "custom-map-marker",
}: CustomMarkerProps) => {

 //...

  return (
    <AdvancedMarker
      position={position}
      key={id}
      onClick={e => {
        e.stop();
        onClick?.(e.domEvent);
      }}
    >
      <div
        onClick={e => {
          e.stopPropagation(); // Otherwise will click map underneath
          onClick?.(e);
        }}
        className={cvaMapMarker({ className, onClick: Boolean(onClick), shape })}
        data-type="map-marker"
        onMouseEnter={e => {
          onMouseEnterHoverHook();
          onMouseEnter?.(e);
        }}
        onMouseLeave={e => {
          onMouseLeaveHoverHook();
          onMouseLeave?.(e);
        }}
        data-testid={dataTestId}
      >
        {marker.element === "round" ? <RoundMarkerSVG data-test="marker-round" color={marker.color} /> : null}
        {isCustomMarker ? (
          <div data-test="marker-custom-container" id={customMarkerId}>
            {marker.element}
          </div>
        ) : null}
        {((labelVisibility === "on-hover" && hovering) || labelVisibility === "always") && hasLabelContent ? (
          <Label
            dataTestId={`${dataTestId}-label`}
            shape={shape}
            onClickLink={onClickLink}
            hovering={hovering}
            className={labelClassName}
            offset={
              isCustomMarker ? document.getElementById(customMarkerId)?.offsetHeight ?? DEFAULT_OFFSET : DEFAULT_OFFSET
            }
          >
            {children}
          </Label>
        ) : null}
      </div>
    </AdvancedMarker>
  );
};

[usefulthink]

Ok, that makes sense. But even in this situation, you can still just use a mock for the AdvancedMarker component and do assertions either against the props.children passed to the component, or have the marker and map mocks render plain html and run assertions against that.

I'll try to do a quick setup for myself so I can show you in code what I mean (that should be pretty useful to add to the documentation as well)

[usefulthink]

So here's a very rough sketch:

I'm assuming jest + @testing-library/react as testing framework (the idea applies to any other setup as well).
Suppose a component (much simpler than your example, but I hope that's enough to illustrate the point) like this:

import { AdvancedMarker } from '@vis.gl/react-google-maps';

type CustomMarkerProps = { label: string; position: google.maps.LatLngLiteral };

export const CustomMarker = (props: CustomMarkerProps) => {
  return (
    <AdvancedMarker position={props.position}>
      <h1>{props.label}</h1>
    </AdvancedMarker>
  );
};

So what do we need to test here? When testing the CustomMarker component, the only thing we need to verify is that the correct props get passed into the AdvancedMarker component.

Whatever the AdvancedMarker component does with those props isn't your concern (especially since the details of that could change at any time without changing the public API of the component). The API is your guarantee that the correct™ things will happen with the props and will produce the desired results.

So we can remove the actual implementation of AdvancedMarker and replace it with something much much simpler:

const AdvancedMarker = (props) => {
  return (
    <div
      data-testid={'marker'}
      data-position={JSON.stringify(props.position)}>
      {props.children}
    </div>
  );
};

This doesn't at all do what the AdvancedMarker does, but it makes everything we care about – the position and children props – available in the rendered DOM for easy inspection.

So, the test can now look like this:

test("something we need to test", async () => {
  render(<CustomMarker position={{ lat: 11, lng: 22 }} label={"Test Label"} />);

  await screen.findByTestId("marker");

  const m = screen.getByTestId("marker");
  expect(m).toHaveTextContent("Test Label");
  expect(JSON.parse(m.dataset.position!)).toEqual({ lat: 11, lng: 22 });
});

This is the complete test-file including the mock-setup, so our CustomMarker component doesn't even see the original AdvancedMarker implementation:

import "@testing-library/jest-dom";

import { render, screen } from "@testing-library/react";
import { CustomMarker } from "./custom-marker";

jest.mock("@vis.gl/react-google-maps", () => {
  const AdvancedMarkerMock = jest.fn((props) => {
    return (
      <div
        data-testid={"marker"}
        data-position={JSON.stringify(props.position)}
      >
        {props.children}
      </div>
    );
  });

  // only mocking advanced marker for this test
  return { AdvancedMarker: AdvancedMarkerMock };
});

test("stuff", async () => {
  render(<CustomMarker position={{ lat: 11, lng: 22 }} label={"Test Label"} />);

  await screen.findByTestId("marker");

  const m = screen.getByTestId("marker");
  expect(m).toHaveTextContent("Test Label");
  expect(JSON.parse(m.dataset.position!)).toEqual({ lat: 11, lng: 22 });
});

Thinking further, if you now have a map component that for example receives an array of places and for each place renders a marker on the map you'd do the same thing – even to the point of not even rendering your own markers (use a mock like the one above instead).

A test of that map component isn't there to verify what your marker component does (that is the job of it's own tests), it's only for making sure that every record in the array has a marker with the correct props created.

Thinking like this is a bit difficult at first, but it will make your tests a thousand times more robust.

[usefulthink]

This is an interesting read into that: https://robertmarshall.dev/blog/how-to-mock-a-react-component-in-jest/
And another alternative approach to verifying the values passed into props: https://robertmarshall.dev/blog/react-component-props-passed-to-child-jest-unit-test/ (this is what I wanted to do at first, but couldn't quickly figure out the typings for the mocked function 😄)

[alexander-lebed]

If mocking in jest.mock("@vis.gl/react-google-maps", fn) is not an option for you (for insatnce you need to mock hooks like useMap), you can create a custom Map component and mock it in your tests.

import { Map as GoogleMap, MapProps } from '@vis.gl/react-google-maps';

const Map: FC<PropsWithChildren<MapProps>> = ({ children, ...rest }) => (
  <GoogleMap {...rest}>
    {children}
  </GoogleMap>
);

__mocks__/Map.tsx:

const MapMock: FC<PropsWithChildren> = ({ children }) => {
  return <div data-testid="mocked-map">{children}</div>;
};

Test:

import { initialize } from '@googlemaps/jest-mocks';

jest.mock('@vis.gl/react-google-maps');
jest.mock('../Map');

beforeEach(() => {
  initialize(); // Mock Google Maps
  // optionally mock hooks, jest.mocked(useMap).mockReturnValue(...)
});
...
getByTestId('mocked-map');