test(geocoding): hard regression tests for enable_address_descriptor (fixes #540)

tests/test_geocoding_advanced.py

@@ -0,0 +1,309 @@
+#
+# Copyright 2024 Google Inc. All rights reserved.
+#
+# 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
+#
+
+"""Advanced / regression tests for the geocoding module.
+
+These tests are specifically aimed at issue #540 ("unexpected keyword argument
+``enable_address_descriptor``"). They exhaustively pin down the public
+signature of :func:`googlemaps.Client.reverse_geocode` and the on-the-wire
+behaviour of the ``enable_address_descriptor`` flag so the regression cannot
+silently come back in a future release.
+"""
+
+import inspect
+from urllib.parse import parse_qs, urlparse
+
+import responses
+
+import googlemaps
+from googlemaps import geocoding
+
+from . import TestCase
+
+
+_GEOCODE_URL = "https://maps.googleapis.com/maps/api/geocode/json"
+
+_DESCRIPTOR_BODY = (
+    '{"status":"OK","results":[],'
+    '"address_descriptor":{'
+    '"landmarks":[{"placeId":"id","display_name":{"text":"Opera House"}}],'
+    '"areas":[{"placeId":"area1","display_name":{"text":"Sydney"}}]'
+    '}}'
+)
+_PLAIN_BODY = '{"status":"OK","results":[]}'
+
+
+def _query(call):
+    """Return the parsed query string for a captured ``responses`` call."""
+    return parse_qs(urlparse(call.request.url).query)
+
+
+class ReverseGeocodeSignatureTest(TestCase):
+    """Pin the public signature so issue #540 cannot regress."""
+
+    def test_module_function_accepts_enable_address_descriptor(self):
+        sig = inspect.signature(geocoding.reverse_geocode)
+        self.assertIn("enable_address_descriptor", sig.parameters)
+        self.assertFalse(
+            sig.parameters["enable_address_descriptor"].default,
+            "enable_address_descriptor must default to a falsy value",
+        )
+
+    def test_client_method_accepts_enable_address_descriptor(self):
+        client = googlemaps.Client(key="AIzaasdf")
+        sig = inspect.signature(client.reverse_geocode)
+        self.assertIn(
+            "enable_address_descriptor",
+            sig.parameters,
+            "Client.reverse_geocode must expose enable_address_descriptor "
+            "(regression for issue #540).",
+        )
+
+    def test_client_method_call_does_not_raise_typeerror(self):
+        """The exact failure mode from issue #540 must no longer occur."""
+        client = googlemaps.Client(key="AIzaasdf")
+        with responses.RequestsMock() as rsps:
+            rsps.add(
+                responses.GET,
+                _GEOCODE_URL,
+                body=_DESCRIPTOR_BODY,
+                status=200,
+                content_type="application/json",
+            )
+            try:
+                client.reverse_geocode(
+                    (-33.8674869, 151.2069902),
+                    enable_address_descriptor=True,
+                )
+            except TypeError as exc:  # pragma: no cover - regression guard
+                self.fail(
+                    "reverse_geocode raised TypeError for "
+                    "enable_address_descriptor (issue #540): %s" % exc
+                )
+
+
+class ReverseGeocodeAddressDescriptorTest(TestCase):
+    def setUp(self):
+        self.key = "AIzaasdf"
+        self.client = googlemaps.Client(self.key)
+
+    @responses.activate
+    def test_flag_true_sends_lowercase_true(self):
+        responses.add(
+            responses.GET, _GEOCODE_URL,
+            body=_DESCRIPTOR_BODY, status=200,
+            content_type="application/json",
+        )
+        self.client.reverse_geocode(
+            (-33.8674869, 151.2069902), enable_address_descriptor=True,
+        )
+        q = _query(responses.calls[0])
+        self.assertEqual(q["enable_address_descriptor"], ["true"])
+        self.assertEqual(q["latlng"], ["-33.8674869,151.2069902"])
+
+    @responses.activate
+    def test_flag_default_omits_parameter(self):
+        responses.add(
+            responses.GET, _GEOCODE_URL,
+            body=_PLAIN_BODY, status=200,
+            content_type="application/json",
+        )
+        self.client.reverse_geocode((-33.8674869, 151.2069902))
+        q = _query(responses.calls[0])
+        self.assertNotIn("enable_address_descriptor", q)
+
+    @responses.activate
+    def test_flag_false_omits_parameter(self):
+        responses.add(
+            responses.GET, _GEOCODE_URL,
+            body=_PLAIN_BODY, status=200,
+            content_type="application/json",
+        )
+        self.client.reverse_geocode(
+            (-33.8674869, 151.2069902), enable_address_descriptor=False,
+        )
+        q = _query(responses.calls[0])
+        self.assertNotIn("enable_address_descriptor", q)
+
+    @responses.activate
+    def test_falsy_values_omit_parameter(self):
+        for falsy in (None, 0, "", [], {}):
+            with self.subTest(value=falsy):
+                with responses.RequestsMock() as rsps:
+                    rsps.add(
+                        responses.GET, _GEOCODE_URL,
+                        body=_PLAIN_BODY, status=200,
+                        content_type="application/json",
+                    )
+                    self.client.reverse_geocode(
+                        (40.0, -73.0), enable_address_descriptor=falsy,
+                    )
+                    q = _query(rsps.calls[0])
+                    self.assertNotIn("enable_address_descriptor", q)
+
+    @responses.activate
+    def test_truthy_non_bool_values_send_true(self):
+        for truthy in (1, "yes", ["x"], {"a": 1}):
+            with self.subTest(value=truthy):
+                with responses.RequestsMock() as rsps:
+                    rsps.add(
+                        responses.GET, _GEOCODE_URL,
+                        body=_DESCRIPTOR_BODY, status=200,
+                        content_type="application/json",
+                    )
+                    self.client.reverse_geocode(
+                        (40.0, -73.0), enable_address_descriptor=truthy,
+                    )
+                    q = _query(rsps.calls[0])
+                    self.assertEqual(q["enable_address_descriptor"], ["true"])
+
+    @responses.activate
+    def test_combined_with_result_and_location_type(self):
+        responses.add(
+            responses.GET, _GEOCODE_URL,
+            body=_DESCRIPTOR_BODY, status=200,
+            content_type="application/json",
+        )
+        self.client.reverse_geocode(
+            (40.714224, -73.961452),
+            result_type=["street_address", "route"],
+            location_type="ROOFTOP",
+            language="en",
+            enable_address_descriptor=True,
+        )
+        q = _query(responses.calls[0])
+        self.assertEqual(q["enable_address_descriptor"], ["true"])
+        self.assertEqual(q["result_type"], ["street_address|route"])
+        self.assertEqual(q["location_type"], ["ROOFTOP"])
+        self.assertEqual(q["language"], ["en"])
+        self.assertEqual(q["latlng"], ["40.714224,-73.961452"])
+
+    @responses.activate
+    def test_works_with_place_id_string(self):
+        place_id = "ChIJN1t_tDeuEmsRUsoyG83frY4"
+        responses.add(
+            responses.GET, _GEOCODE_URL,
+            body=_DESCRIPTOR_BODY, status=200,
+            content_type="application/json",
+        )
+        self.client.reverse_geocode(place_id, enable_address_descriptor=True)
+        q = _query(responses.calls[0])
+        self.assertEqual(q["place_id"], [place_id])
+        self.assertNotIn("latlng", q)
+        self.assertEqual(q["enable_address_descriptor"], ["true"])
+
+    @responses.activate
+    def test_works_with_dict_latlng(self):
+        responses.add(
+            responses.GET, _GEOCODE_URL,
+            body=_DESCRIPTOR_BODY, status=200,
+            content_type="application/json",
+        )
+        self.client.reverse_geocode(
+            {"lat": -33.8674869, "lng": 151.2069902},
+            enable_address_descriptor=True,
+        )
+        q = _query(responses.calls[0])
+        self.assertEqual(q["latlng"], ["-33.8674869,151.2069902"])
+        self.assertEqual(q["enable_address_descriptor"], ["true"])
+
+    @responses.activate
+    def test_works_with_list_latlng(self):
+        responses.add(
+            responses.GET, _GEOCODE_URL,
+            body=_DESCRIPTOR_BODY, status=200,
+            content_type="application/json",
+        )
+        self.client.reverse_geocode(
+            [-33.8674869, 151.2069902], enable_address_descriptor=True,
+        )
+        q = _query(responses.calls[0])
+        self.assertEqual(q["latlng"], ["-33.8674869,151.2069902"])
+
+    @responses.activate
+    def test_works_with_string_latlng(self):
+        responses.add(
+            responses.GET, _GEOCODE_URL,
+            body=_DESCRIPTOR_BODY, status=200,
+            content_type="application/json",
+        )
+        self.client.reverse_geocode(
+            "-33.8674869,151.2069902", enable_address_descriptor=True,
+        )
+        q = _query(responses.calls[0])
+        self.assertEqual(q["latlng"], ["-33.8674869,151.2069902"])
+        self.assertEqual(q["enable_address_descriptor"], ["true"])
+
+    @responses.activate
+    def test_response_exposes_address_descriptor(self):
+        responses.add(
+            responses.GET, _GEOCODE_URL,
+            body=_DESCRIPTOR_BODY, status=200,
+            content_type="application/json",
+        )
+        response = self.client.reverse_geocode(
+            (-33.8674869, 151.2069902), enable_address_descriptor=True,
+        )
+        descriptor = response.get("address_descriptor")
+        self.assertIsNotNone(descriptor)
+        self.assertEqual(len(descriptor["landmarks"]), 1)
+        self.assertEqual(descriptor["landmarks"][0]["placeId"], "id")
+        self.assertEqual(len(descriptor["areas"]), 1)
+
+    @responses.activate
+    def test_repeated_calls_are_independent(self):
+        """A previous call with the flag must not leak into the next."""
+        responses.add(
+            responses.GET, _GEOCODE_URL,
+            body=_DESCRIPTOR_BODY, status=200,
+            content_type="application/json",
+        )
+        responses.add(
+            responses.GET, _GEOCODE_URL,
+            body=_PLAIN_BODY, status=200,
+            content_type="application/json",
+        )
+
+        self.client.reverse_geocode(
+            (40.0, -73.0), enable_address_descriptor=True,
+        )
+        self.client.reverse_geocode((40.0, -73.0))
+
+        self.assertEqual(
+            _query(responses.calls[0])["enable_address_descriptor"], ["true"],
+        )
+        self.assertNotIn(
+            "enable_address_descriptor", _query(responses.calls[1]),
+        )
+
+    @responses.activate
+    def test_keyword_only_call_via_module_function(self):
+        """Calling the underlying module function directly must also work."""
+        responses.add(
+            responses.GET, _GEOCODE_URL,
+            body=_DESCRIPTOR_BODY, status=200,
+            content_type="application/json",
+        )
+        geocoding.reverse_geocode(
+            self.client,
+            (-33.8674869, 151.2069902),
+            enable_address_descriptor=True,
+        )
+        q = _query(responses.calls[0])
+        self.assertEqual(q["enable_address_descriptor"], ["true"])
+
+    def test_unknown_kwarg_still_raises_typeerror(self):
+        """Sanity check: only the documented kwarg is accepted."""
+        client = googlemaps.Client(self.key)
+        with self.assertRaises(TypeError):
+            client.reverse_geocode(
+                (-33.8674869, 151.2069902),
+                enable_address_descriptors=True,  # note the typo / plural
+            )