Add more comments to the tests.

Author: michaelsafyan

instrumentation-genai/opentelemetry-instrumentation-google-genai/tests/common/instrumentation_context.py

@@ -12,7 +12,7 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-from opentelemetry.instrumentation.google_genai import (  # pylint: disable=wrong-import-position
+from opentelemetry.instrumentation.google_genai import (
     GoogleGenAiSdkInstrumentor,
 )
 

instrumentation-genai/opentelemetry-instrumentation-google-genai/tests/common/requests_mocker.py

@@ -12,6 +12,26 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+# This file defines a "RequestMocker" that facilities mocking the "requests"
+# API. There are a few reasons that we use this approach to testing:
+#
+#    1. Security - although "vcrpy" provides a means of filtering data,
+#       it can be error-prone; use of this solution risks exposing API keys,
+#       auth tokens, etc. It can also inadvertently record fields that are
+#       visibility-restricted (such as fields that are returned and available
+#       when recording using privileged API keys where such fields would not
+#       ordinarily be returned to users with non-privileged API keys).
+#
+#    2. Reproducibility - although the tests may be reproducible once the
+#       recording is present, updating the recording often has external
+#       dependencies that may be difficult to reproduce.
+#
+#    3. Costs - there are both time costs and monetary costs to the external
+#       dependencies required for a record/replay solution.
+#
+# Because they APIs that need to be mocked are simple enough and well documented
+# enough, it seems approachable to mock the requests library, instead.
+
 import copy
 import functools
 import http.client

instrumentation-genai/opentelemetry-instrumentation-google-genai/tests/generate_content/test_async_nonstreaming.py

@@ -12,6 +12,10 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+
+# TODO: Once the async non-streaming case has been fully implemented,
+# reimplement this in terms of "nonstreaming_base.py".
+
 import asyncio
 import logging
 import unittest
@@ -44,6 +48,8 @@ def create_valid_response(
     }
 
 
+# Temporary test fixture just to ensure that the in-progress work to
+# implement this case doesn't break the original code.
 class TestGenerateContentAsyncNonstreaming(TestCase):
     def configure_valid_response(
         self,

instrumentation-genai/opentelemetry-instrumentation-google-genai/tests/generate_content/test_async_streaming.py

@@ -14,6 +14,10 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+# TODO: once the async streaming case has been implemented, we should have
+# two different tests here that inherit from "streaming_base" and "nonstreaming_base",
+# covering the cases of one response and multiple streaming responses.
+
 import asyncio
 import logging
 import unittest
@@ -46,6 +50,8 @@ def create_valid_response(
     }
 
 
+# Temporary test fixture just to ensure that the in-progress work to
+# implement this case doesn't break the original code.
 class TestGenerateContentAsyncStreaming(TestCase):
     def configure_valid_response(
         self,

instrumentation-genai/opentelemetry-instrumentation-google-genai/tests/generate_content/test_sync_streaming.py

@@ -12,6 +12,10 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+# TODO: once the async streaming case has been implemented, we should have
+# two different tests here that inherit from "streaming_base" and "nonstreaming_base",
+# covering the cases of one response and multiple streaming responses.
+
 import logging
 import unittest
 
@@ -42,7 +46,8 @@ def create_valid_response(
         ],
     }
 
-
+# Temporary test fixture just to ensure that the in-progress work to
+# implement this case doesn't break the original code.
 class TestGenerateContentSyncStreaming(TestCase):
     def configure_valid_response(
         self,