Simplify PARAMETRIC TestClient API

tests/parametric/conftest.py

@@ -8,11 +8,9 @@
 import pytest
 import yaml
 
-from utils.parametric._library_client import APMLibrary
-
 from utils import scenarios, logger
+from utils.docker_fixtures import TestAgentAPI, ParametricTestClientApi as APMLibrary
 
-from utils.docker_fixtures import TestAgentAPI as _TestAgentAPI
 
 # Max timeout in seconds to keep a container running
 default_subprocess_run_timeout = 300
@@ -77,7 +75,7 @@ def test_agent(
     request: pytest.FixtureRequest,
     test_agent_otlp_http_port: int,
     test_agent_otlp_grpc_port: int,
-) -> Generator[_TestAgentAPI, None, None]:
+) -> Generator[TestAgentAPI, None, None]:
     with scenarios.parametric.get_test_agent_api(
         request=request,
         worker_id=worker_id,
@@ -93,7 +91,7 @@ def test_library(
     worker_id: str,
     request: pytest.FixtureRequest,
     test_id: str,
-    test_agent: _TestAgentAPI,
+    test_agent: TestAgentAPI,
     library_env: dict[str, str],
     library_extra_command_arguments: list[str],
 ) -> Generator[APMLibrary, None, None]:

tests/parametric/test_crashtracking.py

@@ -5,8 +5,7 @@
 import pytest
 
 from utils import bug, features, scenarios, logger
-from utils.parametric._library_client import APMLibrary
-from utils.docker_fixtures import TestAgentAPI
+from utils.docker_fixtures import TestAgentAPI, ParametricTestClientApi as APMLibrary
 
 
 @scenarios.parametric
@@ -44,7 +43,7 @@ def test_telemetry_timeout(self, test_agent: TestAgentAPI, test_library: APMLibr
 
         try:
             # container.wait will throw if the application doesn't exit in time
-            test_library._client.container.wait(timeout=10)  # noqa: SLF001
+            test_library.container.wait(timeout=10)
         finally:
             test_agent.set_trace_delay(0)
 

tests/parametric/test_feature_flag_exposure/test_feature_flag_exposure.py

@@ -10,7 +10,8 @@
     scenarios,
 )
 from utils.dd_constants import RemoteConfigApplyState
-from tests.parametric.conftest import _TestAgentAPI, APMLibrary
+from utils.docker_fixtures import TestAgentAPI
+from tests.parametric.conftest import APMLibrary
 
 RC_PRODUCT = "FFE_FLAGS"
 RC_PATH = f"datadog/2/{RC_PRODUCT}"
@@ -51,7 +52,7 @@ def _get_test_case_files() -> list[str]:
 
 
 def _set_and_wait_ffe_rc(
-    test_agent: _TestAgentAPI, ufc_data: dict[str, Any], config_id: str | None = None
+    test_agent: TestAgentAPI, ufc_data: dict[str, Any], config_id: str | None = None
 ) -> dict[str, Any]:
     """Set FFE Remote Config and wait for it to be acknowledged.
 
@@ -89,7 +90,7 @@ class Test_Feature_Flag_Exposure:
 
     @parametrize("library_env", [{**DEFAULT_ENVVARS}])
     def test_ffe_remote_config(
-        self, library_env: dict[str, str], test_agent: _TestAgentAPI, test_library: APMLibrary
+        self, library_env: dict[str, str], test_agent: TestAgentAPI, test_library: APMLibrary
     ) -> None:
         """Test to verify FFE can receive and acknowledge UFC configurations via Remote Config."""
 
@@ -100,7 +101,7 @@ def test_ffe_remote_config(
     @parametrize("library_env", [{**DEFAULT_ENVVARS}])
     @parametrize("test_case_file", ALL_TEST_CASE_FILES)
     def test_ffe_flag_evaluation(
-        self, library_env: dict[str, str], test_case_file: str, test_agent: _TestAgentAPI, test_library: APMLibrary
+        self, library_env: dict[str, str], test_case_file: str, test_agent: TestAgentAPI, test_library: APMLibrary
     ) -> None:
         """Test FFE flag evaluation logic with various targeting scenarios.
 

tests/parametric/test_headers_b3.py

@@ -3,8 +3,7 @@
 from utils.parametric.spec.trace import SAMPLING_PRIORITY_KEY, ORIGIN
 from utils.parametric.spec.trace import span_has_no_parent
 from utils.parametric.spec.trace import find_only_span
-from utils.docker_fixtures import TestAgentAPI
-from utils.parametric._library_client import APMLibrary
+from utils.docker_fixtures import TestAgentAPI, ParametricTestClientApi as APMLibrary
 from utils import missing_feature, context, scenarios, features, irrelevant, logger
 
 parametrize = pytest.mark.parametrize

tests/parametric/test_otel_api_interoperability.py

@@ -3,8 +3,7 @@
 from utils import scenarios, features
 from opentelemetry.trace import SpanKind
 from utils.parametric.spec.trace import find_trace, find_span, retrieve_span_links, find_only_span, find_root_span
-from utils.parametric._library_client import APMLibrary
-from utils.docker_fixtures import TestAgentAPI
+from utils.docker_fixtures import TestAgentAPI, ParametricTestClientApi as APMLibrary
 
 
 # this global mark applies to all tests in this file.

tests/parametric/test_parametric_endpoints.py

@@ -18,8 +18,8 @@
 from utils import irrelevant, bug, incomplete_test_app, scenarios, features, context
 from opentelemetry.trace import SpanKind
 from opentelemetry.trace import StatusCode
-from utils.parametric._library_client import APMLibrary, Link, LogLevel
-from utils.docker_fixtures import TestAgentAPI
+from utils.parametric._library_client import Link, LogLevel
+from utils.docker_fixtures import TestAgentAPI, ParametricTestClientApi as APMLibrary
 
 # this global mark applies to all tests in this file.
 #   DD_TRACE_OTEL_ENABLED=true is required in the tracers to enable OTel

tests/parametric/test_telemetry.py

@@ -7,7 +7,7 @@
 
 import pytest
 
-from .conftest import StableConfigWriter, _TestAgentAPI
+from .conftest import StableConfigWriter
 from utils.telemetry_utils import TelemetryUtils
 
 from utils import context, scenarios, rfc, features, missing_feature, irrelevant, logger, bug
@@ -1166,7 +1166,7 @@ class Test_TelemetrySCAEnvVar:
     )
     @missing_feature(context.library <= "[email protected]", reason="Converts boolean values to strings")
     def test_telemetry_sca_enabled_propagated(
-        self, library_env: dict[str, str], test_agent: _TestAgentAPI, test_library: APMLibrary, *, outcome_value: bool
+        self, library_env: dict[str, str], test_agent: TestAgentAPI, test_library: APMLibrary, *, outcome_value: bool
     ):
         self._assert_telemetry_sca_enabled_propagated(
             library_env,
@@ -1187,7 +1187,7 @@ def test_telemetry_sca_enabled_propagated(
     @missing_feature(context.library <= "[email protected]", reason="Converts boolean values to strings")
     @irrelevant(context.library not in ("python", "golang"))
     def test_telemetry_sca_enabled_propagated_specifics(
-        self, library_env: dict[str, str], test_agent: _TestAgentAPI, test_library: APMLibrary, *, outcome_value: bool
+        self, library_env: dict[str, str], test_agent: TestAgentAPI, test_library: APMLibrary, *, outcome_value: bool
     ):
         self._assert_telemetry_sca_enabled_propagated(
             library_env,
@@ -1197,7 +1197,7 @@ def test_telemetry_sca_enabled_propagated_specifics(
         )
 
     def _assert_telemetry_sca_enabled_propagated(
-        self, library_env: dict[str, str], test_agent: _TestAgentAPI, test_library: APMLibrary, *, outcome_value: bool
+        self, library_env: dict[str, str], test_agent: TestAgentAPI, test_library: APMLibrary, *, outcome_value: bool
     ):
         configuration_by_name = test_agent.wait_for_telemetry_configurations()
         dd_appsec_sca_enabled = TelemetryUtils.get_dd_appsec_sca_enabled_str(context.library)

tests/parametric/test_tracer.py

@@ -5,8 +5,8 @@
 from utils.parametric.spec.trace import find_first_span_in_trace_payload
 from utils.parametric.spec.trace import find_root_span
 from utils import missing_feature, context, rfc, scenarios, features
+from utils.docker_fixtures import TestAgentAPI
 
-from .conftest import _TestAgentAPI
 from .conftest import APMLibrary
 
 
@@ -18,7 +18,7 @@
 class Test_Tracer:
     @missing_feature(context.library == "cpp", reason="metrics cannot be set manually")
     @missing_feature(context.library == "nodejs", reason="nodejs overrides the manually set service name")
-    def test_tracer_span_top_level_attributes(self, test_agent: _TestAgentAPI, test_library: APMLibrary) -> None:
+    def test_tracer_span_top_level_attributes(self, test_agent: TestAgentAPI, test_library: APMLibrary) -> None:
         """Do a simple trace to ensure that the test client is working properly."""
         with (
             test_library,
@@ -51,7 +51,7 @@ def test_tracer_span_top_level_attributes(self, test_agent: _TestAgentAPI, test_
 class Test_TracerSCITagging:
     @parametrize("library_env", [{"DD_GIT_REPOSITORY_URL": "https://github.com/DataDog/dd-trace-go"}])
     def test_tracer_repository_url_environment_variable(
-        self, library_env: dict[str, str], test_agent: _TestAgentAPI, test_library: APMLibrary
+        self, library_env: dict[str, str], test_agent: TestAgentAPI, test_library: APMLibrary
     ) -> None:
         """When DD_GIT_REPOSITORY_URL is specified
         When a trace chunk is emitted
@@ -78,7 +78,7 @@ def test_tracer_repository_url_environment_variable(
 
     @parametrize("library_env", [{"DD_GIT_COMMIT_SHA": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"}])
     def test_tracer_commit_sha_environment_variable(
-        self, library_env: dict[str, str], test_agent: _TestAgentAPI, test_library: APMLibrary
+        self, library_env: dict[str, str], test_agent: TestAgentAPI, test_library: APMLibrary
     ) -> None:
         """When DD_GIT_COMMIT_SHA is specified
         When a trace chunk is emitted
@@ -139,7 +139,7 @@ def test_tracer_commit_sha_environment_variable(
     )
     @missing_feature(context.library == "nodejs", reason="nodejs does not strip credentials yet")
     def test_tracer_repository_url_strip_credentials(
-        self, library_env: dict[str, str], test_agent: _TestAgentAPI, test_library: APMLibrary
+        self, library_env: dict[str, str], test_agent: TestAgentAPI, test_library: APMLibrary
     ) -> None:
         """When DD_GIT_REPOSITORY_URL is specified
         When a trace chunk is emitted
@@ -166,7 +166,7 @@ class Test_TracerUniversalServiceTagging:
     @missing_feature(reason="FIXME: library test client sets empty string as the service name")
     @parametrize("library_env", [{"DD_SERVICE": "service1"}])
     def test_tracer_service_name_environment_variable(
-        self, library_env: dict[str, str], test_agent: _TestAgentAPI, test_library: APMLibrary
+        self, library_env: dict[str, str], test_agent: TestAgentAPI, test_library: APMLibrary
     ) -> None:
         """When DD_SERVICE is specified
         When a span is created
@@ -184,7 +184,7 @@ def test_tracer_service_name_environment_variable(
 
     @parametrize("library_env", [{"DD_ENV": "prod"}])
     def test_tracer_env_environment_variable(
-        self, library_env: dict[str, str], test_agent: _TestAgentAPI, test_library: APMLibrary
+        self, library_env: dict[str, str], test_agent: TestAgentAPI, test_library: APMLibrary
     ) -> None:
         """When DD_ENV is specified
         When a span is created

utils/_context/_scenarios/parametric.py

@@ -15,8 +15,8 @@
     TestAgentAPI,
     compute_volumes,
     ParametricTestClientFactory,
+    ParametricTestClientApi,
 )
-from utils.parametric._library_client import APMLibrary
 
 from .core import scenario_groups
 from ._docker_fixtures import DockerFixturesScenario
@@ -159,7 +159,7 @@ def get_apm_library(
         test_agent: TestAgentAPI,
         library_env: dict,
         library_extra_command_arguments: list[str],
-    ) -> Generator[APMLibrary, None, None]:
+    ) -> Generator[ParametricTestClientApi, None, None]:
         log_path = f"{self.host_log_folder}/outputs/{request.cls.__name__}/{request.node.name}/server_log.log"
         Path(log_path).parent.mkdir(parents=True, exist_ok=True)
 

utils/docker_fixtures/__init__.py

@@ -1,11 +1,12 @@
 from ._core import get_host_port, docker_run, compute_volumes
 from ._test_agent import TestAgentAPI, TestAgentFactory
-from ._test_client_parametric import ParametricTestClientFactory
+from ._test_client_parametric import ParametricTestClientFactory, ParametricTestClientApi
 from ._test_client_framework_integrations import FrameworkTestClientApi, FrameworkTestClientFactory
 
 __all__ = [
     "FrameworkTestClientApi",
     "FrameworkTestClientFactory",
+    "ParametricTestClientApi",
     "ParametricTestClientFactory",
     "TestAgentAPI",
     "TestAgentFactory",

utils/docker_fixtures/_test_agent.py

@@ -45,7 +45,11 @@ class AgentRequestV06Stats(AgentRequest):
 
 
 class TestAgentFactory:
-    """Handle everything to create the TestAgentApi"""
+    """Handle everything to create the TestAgentApi
+    This class is responsible to:
+    * build the image
+    * expose a ready to call function that runs the container and returns the client that will be used in tests
+    """
 
     def __init__(self, image: str):
         self.image = image
@@ -156,6 +160,8 @@ def get_test_agent_api(
 
 
 class TestAgentAPI:
+    """API to interact with the test agent server running in a docker container."""
+
     __test__ = False  # pytest must not collect it
 
     def __init__(

utils/docker_fixtures/_test_client_framework_integrations.py

@@ -93,6 +93,10 @@ def get_client(
 
 
 class FrameworkTestClientApi:
+    """API to interact with the tracer+framework server running in a docker container for
+    INTEGRATIONS_FRAMEWORK scenarios.
+    """
+
     def __init__(self, url: str, timeout: int, container: Container):
         self._base_url = url
         self._session = requests.Session()

utils/docker_fixtures/_test_client_parametric.py

@@ -2,7 +2,7 @@
 import contextlib
 from typing import TextIO
 
-from utils.parametric._library_client import APMLibrary, APMLibraryClient
+from utils.parametric._library_client import ParametricTestClientApi
 
 
 from ._core import get_host_port, docker_run
@@ -11,6 +11,12 @@
 
 
 class ParametricTestClientFactory(TestClientFactory):
+    """Abstracts the docker image/container that ship the tested tracer for PARAMETRIC scenario.
+    # This class is responsible to:
+    # * build the image
+    # * expose a ready to call function that runs the container and returns the client that will be used in tests
+    """
+
     @contextlib.contextmanager
     def get_apm_library(
         self,
@@ -20,7 +26,7 @@ def get_apm_library(
         library_env: dict,
         library_extra_command_arguments: list[str],
         test_server_log_file: TextIO,
-    ) -> Generator["APMLibrary", None, None]:
+    ) -> Generator["ParametricTestClientApi", None, None]:
         host_port = get_host_port(worker_id, 4500)
         container_port = 8080
 
@@ -62,12 +68,11 @@ def get_apm_library(
         ) as container:
             test_server_timeout = 60
 
-            client = APMLibraryClient(
+            client = ParametricTestClientApi(
                 self.library,
                 f"http://localhost:{host_port}",
                 test_server_timeout,
                 container,
             )
 
-            tracer = APMLibrary(client, self.library)
-            yield tracer
+            yield client