[core] feat: add support for simulating API responses

* Add `simulator` module with `ApiReportSimulator` class. Via its
  `simulate` method based on a query and `SimulatorSpecification` users
  can generate `n_rows` of simulated results based on provided
  ApiClient.
* Ensure that `GarfApiResponse` has optional `results_placeholder` field that
  contains fallback results in case API produce no results.
* Add `get_types` method to API that could be implemented in concrete
  ApiClients; provide an implementation for FakeApiClient.
* In `ApiReportFetcher.fetch` is no results are produces by ApiClient,
  generate placeholder and return empty report with
  `results_placeholder`.
* Create two custom simulators - for googleads and youtube-data-api
  fetchers
* Propagate `results_placeholder` in `YouTubeDataApiReportFetcher.fetch`
  when performing sorting.

Author: AndreyMarkinPPC

.github/workflows/test_garf_google_ads.yaml

@@ -29,6 +29,9 @@ jobs:
           uv pip install pytest
       - name: Test ${{ matrix.library }}
         run: |
+          uv pip install -e libs/core/.[all]
+          uv pip install -e libs/io/.[test,all]
+          uv pip install -e libs/executors/.[all]
           cd libs/community/google/ads/
           uv pip install -e .
           pytest tests/unit

.github/workflows/test_garf_youtube_data_api.yaml

@@ -29,6 +29,9 @@ jobs:
           uv pip install pytest python-dotenv
       - name: Test ${{ matrix.library }}
         run: |
+          uv pip install -e libs/core/.[all]
+          uv pip install -e libs/io/.[test,all]
+          uv pip install -e libs/executors/.[all]
           cd libs/community/google/youtube/youtube-data-api/
           uv pip install -e .
           pytest tests/e2e

libs/community/google/ads/garf_google_ads/__init__.py

@@ -22,4 +22,4 @@
   'GoogleAdsApiReportFetcher',
 ]
 
-__version__ = '0.0.4'
+__version__ = '0.0.5'

libs/community/google/ads/garf_google_ads/api_clients.py

@@ -18,14 +18,19 @@
 import importlib
 import logging
 import os
+import re
 from pathlib import Path
-from typing import Final
+from types import ModuleType
+from typing import Any, Final
 
 import google.auth
+import proto
+import pydantic
 import smart_open
 import tenacity
 import yaml
 from garf_core import api_clients
+from google import protobuf
 from google.ads.googleads import client as googleads_client
 from google.api_core import exceptions as google_exceptions
 from typing_extensions import override
@@ -39,6 +44,11 @@
 )
 
 
+class FieldPossibleValues(pydantic.BaseModel):
+  name: str
+  values: set[Any]
+
+
 class GoogleAdsApiClientError(exceptions.GoogleAdsApiError):
   """Google Ads API client specific error."""
 
@@ -91,6 +101,171 @@ def __init__(
     self.ads_service = self.client.get_service('GoogleAdsService')
     self.kwargs = kwargs
 
+  @property
+  def _base_module(self) -> str:
+    """Name of Google Ads module for a given API version."""
+    return f'google.ads.googleads.{self.api_version}'
+
+  @property
+  def _common_types_module(self) -> str:
+    """Name of module containing common data types."""
+    return f'{self._base_module}.common.types'
+
+  @property
+  def _metrics(self) -> ModuleType:
+    """Module containing metrics."""
+    return importlib.import_module(f'{self._common_types_module}.metrics')
+
+  @property
+  def _segments(self) -> ModuleType:
+    """Module containing segments."""
+    return importlib.import_module(f'{self._common_types_module}.segments')
+
+  def _get_google_ads_row(self) -> google_ads_service.GoogleAdsRow:
+    """Gets GoogleAdsRow proto message for a given API version."""
+    google_ads_service = importlib.import_module(
+      f'google.ads.googleads.{self.api_version}.'
+      f'services.types.google_ads_service'
+    )
+    return google_ads_service.GoogleAdsRow()
+
+  def get_types(self, request):
+    return []
+
+  def _get_types(self, request):
+    output = []
+    for field_name in request.fields:
+      try:
+        descriptor = self._get_descriptor(field_name)
+        values = self._get_possible_values_for_resource(descriptor)
+        field = FieldPossibleValues(name=field_name, values=values)
+      except (AttributeError, ModuleNotFoundError):
+        field = FieldPossibleValues(
+          name=field_name,
+          values={
+            '',
+          },
+        )
+      output.append(field)
+    return output
+
+  def _get_descriptor(
+    self, field: str
+  ) -> protobuf.descriptor_pb2.FieldDescriptorProto:
+    """Gets descriptor for specified field.
+
+    Args:
+        field: Valid field name to be sent to Ads API.
+
+    Returns:
+        FieldDescriptorProto for specified field.
+    """
+    resource, *sub_resource, base_field = field.split('.')
+    base_field = 'type_' if base_field == 'type' else base_field
+    target_resource = self._get_target_resource(resource, sub_resource)
+    return target_resource.meta.fields.get(base_field).descriptor
+
+  def _get_target_resource(
+    self, resource: str, sub_resource: list[str] | None = None
+  ) -> proto.message.Message:
+    """Gets Proto message for specified resource and its sub-resources.
+
+    Args:
+        resource:
+            Google Ads resource (campaign, ad_group, segments, etc.).
+        sub_resource:
+            Possible sub-resources (date for segments resource).
+
+    Returns:
+        Proto describing combination of resource and sub-resource.
+    """
+    if resource == 'metrics':
+      target_resource = self._metrics.Metrics
+    elif resource == 'segments':
+      # If segment has name segments.something.something
+      if sub_resource:
+        target_resource = getattr(
+          self._segments, f'{clean_resource(sub_resource[-1])}'
+        )
+      else:
+        target_resource = getattr(self._segments, f'{clean_resource(resource)}')
+    else:
+      resource_module = importlib.import_module(
+        f'{self._base_module}.resources.types.{resource}'
+      )
+
+      target_resource = getattr(resource_module, f'{clean_resource(resource)}')
+      try:
+        # If resource has name resource.something.something
+        if sub_resource:
+          target_resource = getattr(
+            target_resource, f'{clean_resource(sub_resource[-1])}'
+          )
+      except AttributeError:
+        try:
+          resource_module = importlib.import_module(
+            f'{self._base_module}.resources.types.{sub_resource[0]}'
+          )
+        except ModuleNotFoundError:
+          resource_module = importlib.import_module(
+            f'{self._common_types_module}.{sub_resource[0]}'
+          )
+        if len(sub_resource) > 1:
+          if hasattr(resource_module, f'{clean_resource(sub_resource[1])}'):
+            target_resource = getattr(
+              resource_module, f'{clean_resource(sub_resource[-1])}'
+            )
+          else:
+            resource_module = importlib.import_module(
+              f'{self._common_types_module}.ad_type_infos'
+            )
+
+            target_resource = getattr(
+              resource_module, f'{clean_resource(sub_resource[1])}Info'
+            )
+        else:
+          target_resource = getattr(
+            resource_module, f'{clean_resource(sub_resource[-1])}'
+          )
+    return target_resource
+
+  def _get_possible_values_for_resource(
+    self, descriptor: protobuf.descriptor_pb2.FieldDescriptorProto
+  ) -> set:
+    """Identifies possible values for a given descriptor or field_type.
+
+    If descriptor's type is ENUM function gets all possible values for
+    this Enum, otherwise the default value for descriptor type is taken
+    (0 for int, '' for str, False for bool).
+
+    Args:
+        descriptor: FieldDescriptorProto for specified field.
+
+    Returns:
+        Possible values for a given descriptor.
+    """
+    mapping = {
+      'INT64': int,
+      'FLOAT': float,
+      'DOUBLE': float,
+      'BOOL': bool,
+    }
+    if descriptor.type == 14:  # 14 stands for ENUM
+      enum_class, enum = descriptor.type_name.split('.')[-2:]
+      file_name = re.sub(r'(?<!^)(?=[A-Z])', '_', enum).lower()
+      enum_resource = importlib.import_module(
+        f'{self._base_module}.enums.types.{file_name}'
+      )
+      return {p.name for p in getattr(getattr(enum_resource, enum_class), enum)}
+
+    field_type = mapping.get(
+      proto.primitives.ProtoType(descriptor.type).name, str
+    )
+    default_value = field_type()
+    return {
+      default_value,
+    }
+
   @override
   @tenacity.retry(
     stop=tenacity.stop_after_attempt(3),
@@ -103,24 +278,14 @@ def __init__(
   def get_response(
     self, request: query_editor.GoogleAdsApiQuery, account: int, **kwargs: str
   ) -> api_clients.GarfApiResponse:
-    """Executes query for a given entity_id (customer_id).
-
-    Args:
-        account: Google Ads customer_id.
-        query_text: GAQL query text.
-
-    Returns:
-        SearchGoogleAdsStreamResponse for a given API version.
-
-    Raises:
-        google_exceptions.InternalServerError:
-            When data cannot be fetched from Ads API.
-    """
+    """Executes a single API request for a given customer_id and GAQL query."""
     response = self.ads_service.search_stream(
       customer_id=account, query=request.text
     )
     results = [result for batch in response for result in batch.results]
-    return api_clients.GarfApiResponse(results=results)
+    return api_clients.GarfApiResponse(
+      results=results, results_placeholder=[self._get_google_ads_row()]
+    )
 
   def _init_client(
     self,
@@ -204,3 +369,8 @@ def from_googleads_client(
       version=ads_client.version,
       use_proto_plus=use_proto_plus,
     )
+
+
+def clean_resource(resource: str) -> str:
+  """Converts nested resource to a TitleCase format."""
+  return resource.title().replace('_', '')

libs/community/google/ads/garf_google_ads/simulator.py

@@ -0,0 +1,53 @@
+# Copyright 2026 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
+#
+#     https://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.
+
+"""Simulates response from Google Ads API based on a query."""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+import garf_core
+from garf_core import simulator
+
+from garf_google_ads import parsers, query_editor
+from garf_google_ads.api_clients import GoogleAdsApiClient
+
+logger = logging.getLogger(__name__)
+
+
+class GoogleAdsApiSimulatorSpecification(simulator.SimulatorSpecification):
+  """Google Ads API specific simulator specification."""
+
+
+class GoogleAdsApiReportSimulator(simulator.ApiReportSimulator):
+  def __init__(
+    self,
+    api_client: GoogleAdsApiClient | None = None,
+    parser: garf_core.parsers.ProtoParser = parsers.GoogleAdsRowParser,
+    query_spec: query_editor.GoogleAdsApiQuery = (
+      query_editor.GoogleAdsApiQuery
+    ),
+    **kwargs: str,
+  ) -> None:
+    if not api_client:
+      api_client = GoogleAdsApiClient(**kwargs)
+    super().__init__(api_client, parser, query_spec)
+
+  def _generate_random_values(
+    self,
+    response_types: dict[str, Any],
+  ) -> dict[str, Any]:
+    return self.api_client._get_google_ads_row()

libs/community/google/ads/tests/unit/test_simulator.py

@@ -0,0 +1,30 @@
+# Copyright 2026 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
+#
+#     https://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.
+import os
+
+import pytest
+from garf_google_ads import simulator
+
+
+@pytest.mark.skipif(
+  not os.getenv('GOOGLE_ADS_CONFIGURATION_FILE_PATH'),
+  reason='Env variable GOOGLE_ADS_CONFIGURATION_FILE_PATH is not set',
+)
+class TestGoogleAdsApiReportSimulator:
+  def test_simulate(self):
+    fake_simulator = simulator.GoogleAdsApiReportSimulator()
+    query_spec = 'SELECT campaign.id, metrics.clicks AS clicks FROM campaign'
+    simulator_spec = simulator.GoogleAdsApiSimulatorSpecification()
+    simulated_report = fake_simulator.simulate(query_spec, simulator_spec)
+    assert len(simulated_report) == simulator_spec.n_rows

libs/community/google/youtube/youtube-data-api/garf_youtube_data_api/__init__.py

@@ -24,4 +24,4 @@
   'YouTubeDataApiReportFetcher',
 ]
 
-__version__ = '0.0.12'
+__version__ = '0.0.13'