feat(examples): Update targeting examples to v19 and add test suite

- Ensured all Python scripts in examples/targeting/ use Google Ads API v19.
- Created a new test suite in examples/targeting/tests/.
- Added __init__.py to the new test directory.
- Implemented basic unit tests for:
    - add_campaign_targeting_criteria.py
    - add_customer_negative_criteria.py
    - add_demographic_targeting_criteria.py
    - get_geo_target_constants_by_names.py

The tests mock the GoogleAdsClient and relevant services to verify that API calls are made with the expected parameters and that criteria are constructed correctly.

Author: google-labs-jules[bot]

examples/targeting/tests/.keep

@@ -0,0 +1,2 @@
+# This file is intentionally left blank.
+# It is used to ensure the directory is tracked by Git.

examples/targeting/tests/__init__.py

@@ -0,0 +1,2 @@
+# This file is intentionally left blank.
+# It marks this directory as a Python package.

examples/targeting/tests/test_add_campaign_targeting_criteria.py

@@ -0,0 +1,118 @@
+import unittest
+from unittest.mock import MagicMock, patch, call
+import sys
+
+# Add the examples directory to the system path to import the script
+sys.path.append(".")
+
+from examples.targeting.add_campaign_targeting_criteria import main
+
+class TestAddCampaignTargetingCriteria(unittest.TestCase):
+    @patch("examples.targeting.add_campaign_targeting_criteria.GoogleAdsClient.load_from_storage")
+    def test_main_function_calls(self, mock_load_client):
+        # Mock customer and campaign IDs
+        MOCK_CUSTOMER_ID = "1234567890"
+        MOCK_CAMPAIGN_ID = "9876543210"
+        MOCK_KEYWORD_TEXT = "negative keyword"
+        MOCK_LOCATION_ID = "21167"  # New York
+
+        # Create a mock GoogleAdsClient
+        mock_google_ads_client = MagicMock()
+        mock_load_client.return_value = mock_google_ads_client
+
+        # Mock the CampaignCriterionService
+        mock_campaign_criterion_service = MagicMock()
+        mock_google_ads_client.get_service.return_value = mock_campaign_criterion_service
+
+        # Mock the get_type method for various types
+        mock_campaign_criterion_operation = MagicMock()
+        mock_keyword_info = MagicMock()
+        mock_location_info = MagicMock()
+        mock_proximity_info = MagicMock()
+        mock_address_info = MagicMock()
+
+        # Configure client.get_type to return appropriate mocks
+        def get_type_side_effect(type_name, version=None):
+            if type_name == "CampaignCriterionOperation":
+                # Return a new MagicMock each time to ensure operations are distinct
+                return MagicMock()
+            elif type_name == "KeywordInfo":
+                return mock_keyword_info
+            elif type_name == "LocationInfo":
+                return mock_location_info
+            elif type_name == "ProximityInfo":
+                return mock_proximity_info
+            elif type_name == "AddressInfo":
+                return mock_address_info
+            return MagicMock()
+
+        mock_google_ads_client.get_type.side_effect = get_type_side_effect
+
+        # Call the main function
+        main(
+            mock_google_ads_client,
+            MOCK_CUSTOMER_ID,
+            MOCK_CAMPAIGN_ID,
+            MOCK_KEYWORD_TEXT,
+            MOCK_LOCATION_ID,
+        )
+
+        # Assert that mutate_campaign_criteria was called
+        mock_campaign_criterion_service.mutate_campaign_criteria.assert_called_once()
+
+        # Get the arguments passed to mutate_campaign_criteria
+        args, kwargs = mock_campaign_criterion_service.mutate_campaign_criteria.call_args
+        
+        self.assertEqual(kwargs["customer_id"], MOCK_CUSTOMER_ID)
+        operations = kwargs["operations"]
+        self.assertEqual(len(operations), 3) # Location, Negative Keyword, Proximity
+
+        # Expected campaign resource name format
+        expected_campaign_rname = mock_google_ads_client.get_service(
+            "CampaignService"
+        ).campaign_path(MOCK_CUSTOMER_ID, MOCK_CAMPAIGN_ID)
+
+
+        # --- Verify Location Operation ---
+        location_operation = operations[0]
+        self.assertEqual(location_operation.create.campaign, expected_campaign_rname)
+        # LocationInfo is set directly on the criterion, not via client.get_type in the script for create
+        # We need to access it from the actual operation object passed to the service
+        created_location_criterion = location_operation.create
+        self.assertEqual(
+            created_location_criterion.location.geo_target_constant,
+            mock_google_ads_client.get_service(
+                "GeoTargetConstantService"
+            ).geo_target_constant_path(MOCK_LOCATION_ID),
+        )
+
+        # --- Verify Negative Keyword Operation ---
+        keyword_operation = operations[1]
+        self.assertEqual(keyword_operation.create.campaign, expected_campaign_rname)
+        created_keyword_criterion = keyword_operation.create
+        self.assertTrue(created_keyword_criterion.negative)
+        self.assertEqual(created_keyword_criterion.keyword.text, MOCK_KEYWORD_TEXT)
+        # Access KeywordMatchTypeEnum from the GoogleAdsClient's enums
+        KeywordMatchTypeEnum = mock_google_ads_client.enums.KeywordMatchTypeEnum
+        self.assertEqual(created_keyword_criterion.keyword.match_type, KeywordMatchTypeEnum.BROAD)
+
+        # --- Verify Proximity Operation ---
+        proximity_operation = operations[2]
+        self.assertEqual(proximity_operation.create.campaign, expected_campaign_rname)
+        created_proximity_criterion = proximity_operation.create
+        
+        # AddressInfo
+        self.assertEqual(created_proximity_criterion.proximity.address.street_address, "38 avenue de l'Opera")
+        self.assertEqual(created_proximity_criterion.proximity.address.city_name, "Paris")
+        self.assertEqual(created_proximity_criterion.proximity.address.postal_code, "75002")
+        self.assertEqual(created_proximity_criterion.proximity.address.country_code, "FR")
+        
+        # Radius
+        self.assertEqual(created_proximity_criterion.proximity.radius, 10.0)
+        # Access ProximityRadiusUnitsEnum from the GoogleAdsClient's enums
+        ProximityRadiusUnitsEnum = mock_google_ads_client.enums.ProximityRadiusUnitsEnum
+        self.assertEqual(created_proximity_criterion.proximity.radius_units, ProximityRadiusUnitsEnum.MILES)
+
+
+if __name__ == "__main__":
+    unittest.main()

examples/targeting/tests/test_add_customer_negative_criteria.py

@@ -0,0 +1,74 @@
+import unittest
+from unittest.mock import MagicMock, patch, call
+import sys
+
+# Add the examples directory to the system path to import the script
+sys.path.append(".")
+
+from examples.targeting.add_customer_negative_criteria import main
+
+class TestAddCustomerNegativeCriteria(unittest.TestCase):
+    @patch("examples.targeting.add_customer_negative_criteria.GoogleAdsClient.load_from_storage")
+    def test_main_function_calls(self, mock_load_client):
+        # Mock customer ID
+        MOCK_CUSTOMER_ID = "1234567890"
+
+        # Create a mock GoogleAdsClient
+        mock_google_ads_client = MagicMock()
+        mock_load_client.return_value = mock_google_ads_client
+
+        # Mock the CustomerNegativeCriterionService
+        mock_customer_negative_criterion_service = MagicMock()
+        mock_google_ads_client.get_service.return_value = mock_customer_negative_criterion_service
+
+        # Mock the get_type method for CustomerNegativeCriterionOperation
+        # In the script, client.get_type is called for "CustomerNegativeCriterionOperation"
+        # and then attributes like "create.content_label.type_" or "create.placement.url" are set.
+        # We need to ensure that when get_type("CustomerNegativeCriterionOperation") is called,
+        # the returned mock can handle further attribute assignments for "create".
+
+        def get_type_side_effect(type_name):
+            if type_name == "CustomerNegativeCriterionOperation":
+                # Return a new MagicMock each time to ensure operations are distinct
+                # and allow "create" attribute to be set on it.
+                mock_operation = MagicMock()
+                # mock_operation.create = MagicMock() # This might be too early or too specific
+                return mock_operation
+            return MagicMock() # Default for other types if any
+
+        mock_google_ads_client.get_type.side_effect = get_type_side_effect
+        
+        # Mock enums that are accessed from the client instance
+        ContentLabelTypeEnum = mock_google_ads_client.enums.ContentLabelTypeEnum
+        
+        # Call the main function
+        main(mock_google_ads_client, MOCK_CUSTOMER_ID)
+
+        # Assert that mutate_customer_negative_criteria was called
+        mock_customer_negative_criterion_service.mutate_customer_negative_criteria.assert_called_once()
+
+        # Get the arguments passed to mutate_customer_negative_criteria
+        args, kwargs = mock_customer_negative_criterion_service.mutate_customer_negative_criteria.call_args
+        
+        self.assertEqual(kwargs["customer_id"], MOCK_CUSTOMER_ID)
+        operations = kwargs["operations"]
+        self.assertEqual(len(operations), 2)  # Content Label and Placement
+
+        # --- Verify Content Label Operation ---
+        content_label_operation = operations[0]
+        # The criterion is directly on the operation's "create" attribute
+        created_content_label_criterion = content_label_operation.create
+        self.assertEqual(
+            created_content_label_criterion.content_label.type_,
+            ContentLabelTypeEnum.TRAGEDY,
+        )
+
+        # --- Verify Placement Operation ---
+        placement_operation = operations[1]
+        created_placement_criterion = placement_operation.create
+        self.assertEqual(
+            created_placement_criterion.placement.url, "http://www.example.com"
+        )
+
+if __name__ == "__main__":
+    unittest.main()

examples/targeting/tests/test_add_demographic_targeting_criteria.py

@@ -0,0 +1,88 @@
+import unittest
+from unittest.mock import MagicMock, patch, call
+import sys
+
+# Add the examples directory to the system path to import the script
+sys.path.append(".")
+
+from examples.targeting.add_demographic_targeting_criteria import main
+
+class TestAddDemographicTargetingCriteria(unittest.TestCase):
+    @patch("examples.targeting.add_demographic_targeting_criteria.GoogleAdsClient.load_from_storage")
+    def test_main_function_calls(self, mock_load_client):
+        # Mock IDs
+        MOCK_CUSTOMER_ID = "1234567890"
+        MOCK_AD_GROUP_ID = "9876543210"
+
+        # Create a mock GoogleAdsClient
+        mock_google_ads_client = MagicMock()
+        mock_load_client.return_value = mock_google_ads_client
+
+        # Mock the AdGroupCriterionService
+        mock_ad_group_criterion_service = MagicMock()
+        
+        # Mock the AdGroupService (for ad_group_path)
+        mock_ad_group_service = MagicMock()
+
+        def get_service_side_effect(service_name, version=None):
+            if service_name == "AdGroupCriterionService":
+                return mock_ad_group_criterion_service
+            elif service_name == "AdGroupService":
+                return mock_ad_group_service
+            return MagicMock()
+
+        mock_google_ads_client.get_service.side_effect = get_service_side_effect
+        
+        # Expected ad_group resource name
+        expected_ad_group_rname = mock_ad_group_service.ad_group_path(
+            MOCK_CUSTOMER_ID, MOCK_AD_GROUP_ID
+        )
+
+        # Mock the get_type method for AdGroupCriterionOperation
+        def get_type_side_effect(type_name):
+            if type_name == "AdGroupCriterionOperation":
+                # Return a new MagicMock each time for distinct operations
+                return MagicMock()
+            return MagicMock()
+
+        mock_google_ads_client.get_type.side_effect = get_type_side_effect
+        
+        # Mock enums
+        GenderTypeEnum = mock_google_ads_client.enums.GenderTypeEnum
+        AgeRangeTypeEnum = mock_google_ads_client.enums.AgeRangeTypeEnum
+        
+        # Call the main function
+        main(mock_google_ads_client, MOCK_CUSTOMER_ID, MOCK_AD_GROUP_ID)
+
+        # Assert that mutate_ad_group_criteria was called
+        mock_ad_group_criterion_service.mutate_ad_group_criteria.assert_called_once()
+
+        # Get the arguments passed to mutate_ad_group_criteria
+        args, kwargs = mock_ad_group_criterion_service.mutate_ad_group_criteria.call_args
+        
+        self.assertEqual(kwargs["customer_id"], MOCK_CUSTOMER_ID)
+        operations = kwargs["operations"]
+        self.assertEqual(len(operations), 2)  # Gender and Age Range
+
+        # --- Verify Gender Criterion Operation ---
+        gender_operation = operations[0]
+        created_gender_criterion = gender_operation.create
+        self.assertEqual(created_gender_criterion.ad_group, expected_ad_group_rname)
+        self.assertEqual(created_gender_criterion.gender.type_, GenderTypeEnum.MALE)
+        # In the script, gender is positive targeting, so .negative should not be True
+        # A non-existent attribute or one that is False would be fine.
+        # We'll check it's not explicitly True. If it's not set, getattr will raise AttributeError.
+        # If it's set to False, this check will pass.
+        self.assertNotEqual(getattr(created_gender_criterion, 'negative', False), True)
+
+
+        # --- Verify Age Range Criterion Operation (Negative) ---
+        age_range_operation = operations[1]
+        created_age_range_criterion = age_range_operation.create
+        self.assertEqual(created_age_range_criterion.ad_group, expected_ad_group_rname)
+        self.assertEqual(created_age_range_criterion.age_range.type_, AgeRangeTypeEnum.AGE_RANGE_18_24)
+        self.assertTrue(created_age_range_criterion.negative)
+
+
+if __name__ == "__main__":
+    unittest.main()

examples/targeting/tests/test_get_geo_target_constants_by_names.py

@@ -0,0 +1,89 @@
+import unittest
+from unittest.mock import MagicMock, patch, call
+import sys
+
+# Add the examples directory to the system path to import the script
+sys.path.append(".")
+
+from examples.targeting.get_geo_target_constants_by_names import main
+
+class TestGetGeoTargetConstantsByNames(unittest.TestCase):
+    @patch("examples.targeting.get_geo_target_constants_by_names.GoogleAdsClient.load_from_storage")
+    def test_main_function_calls(self, mock_load_client):
+        # Create a mock GoogleAdsClient
+        mock_google_ads_client = MagicMock()
+        mock_load_client.return_value = mock_google_ads_client
+
+        # Mock the GeoTargetConstantService
+        mock_geo_target_constant_service = MagicMock()
+        mock_google_ads_client.get_service.return_value = mock_geo_target_constant_service
+
+        # Mock the GeoTargetConstantService
+        mock_geo_target_constant_service = MagicMock()
+        mock_google_ads_client.get_service.return_value = mock_geo_target_constant_service
+
+        # Mock the SuggestGeoTargetConstantsRequest object that client.get_type will return.
+        # client.get_type("SuggestGeoTargetConstantsRequest") returns an instance, not a class.
+        mock_request_instance = MagicMock(name="SuggestGeoTargetConstantsRequestInstance")
+        mock_google_ads_client.get_type.return_value = mock_request_instance
+        
+        # Set up the nested structure for location_names.names on this instance.
+        # The script accesses request.location_names.names
+        mock_location_names_object = MagicMock(name="LocationNamesObject")
+        mock_request_instance.location_names = mock_location_names_object
+        # Initialize .names as a list on this mock_location_names_object because the script appends to it.
+        mock_location_names_object.names = []
+
+
+        # Mock the response from suggest_geo_target_constants
+        # This should be an iterable where each item has the attributes accessed in the script's loop
+        mock_suggestion_1 = MagicMock()
+        mock_suggestion_1.resource_name = "geoTargetConstants/1000"
+        mock_suggestion_1.name = "Paris"
+        mock_suggestion_1.country_code = "FR"
+        mock_suggestion_1.target_type = "City"
+        mock_suggestion_1.status = "ENABLED"
+        
+        mock_suggestion_2 = MagicMock()
+        mock_suggestion_2.resource_name = "geoTargetConstants/2000"
+        mock_suggestion_2.name = "Quebec"
+        mock_suggestion_2.country_code = "CA"
+        mock_suggestion_2.target_type = "Province"
+        mock_suggestion_2.status = "ENABLED"
+
+        # Mock the response from suggest_geo_target_constants
+        mock_response = MagicMock()
+        mock_response.geo_target_constant_suggestions = [
+            mock_suggestion_1, mock_suggestion_2
+        ]
+        mock_geo_target_constant_service.suggest_geo_target_constants.return_value = mock_response
+        
+        # Call the main function
+        main(mock_google_ads_client)
+
+        # Assert that suggest_geo_target_constants was called
+        mock_geo_target_constant_service.suggest_geo_target_constants.assert_called_once()
+
+        # The first argument to suggest_geo_target_constants is the request object
+        # In the script, this is constructed and then passed.
+        # Our mock_request_instance should be what was passed.
+        passed_request = mock_geo_target_constant_service.suggest_geo_target_constants.call_args[0][0]
+        
+        # Verify the attributes of the passed request object
+        self.assertEqual(passed_request.locale, "en")
+        self.assertEqual(passed_request.country_code, "FR")
+        
+        # Verify location_names.names
+        # The script does: request.location_names.names.extend(["Paris", "Quebec", "Spain", "Deutschland"])
+        # We check the final state of this list on mock_location_names_object.names
+        self.assertListEqual(
+            mock_location_names_object.names, 
+            ["Paris", "Quebec", "Spain", "Deutschland"]
+        )
+        
+        # Also, ensure the request object passed to the service call is the one we configured
+        self.assertEqual(passed_request, mock_request_instance)
+
+
+if __name__ == "__main__":
+    unittest.main()