test: ConfigurationFixture for plugin-override singleton reset (#50)

The Agentic QA platform suites' conftest had two near-identical
~20-line functions (_configure_httpx_plugin, _configure_llm_plugin)
that hand-wrote the same env-set + Configuration._instance reset +
ServiceLocator cache pop + get_client + type-validate sequence.

Pattern: Test Fixture (Test Helper Class).

  - src/test/python/suites/agentic/_fixtures.py (new):
    ConfigurationFixture with three classmethods:
      * set_env(overrides) — apply env vars
      * reset_singletons(plugin_interface) — clear caches for one
        plugin without disturbing others
      * resolve(iface, expected_cls, env_overrides) — composes the
        above and validates the resolved class

  - conftest.py: both _configure_*_plugin functions are now 6-line
    wrappers calling ConfigurationFixture.resolve. Imports reduced
    (no longer reach into Configuration / ServiceLocator privates).

The cache reset is now exhaustively unit-tested instead of being
buried in fixture code that's only exercised by E2E suites.

Coverage: 10 new unit tests covering set_env (writes to os.environ,
empty-dict no-op), reset_singletons (clears Configuration, pops only
target plugin's caches, no-op when target absent), and resolve
(raises on None / wrong type, returns class on success, applies env
before resolving, resets caches on each call). flake8 + mypy clean.
287 unit tests pass (was 277; +10).

Author: WesleyPeng

src/test/python/suites/agentic/_fixtures.py

@@ -0,0 +1,105 @@
+# Copyright (c) 2017-2026 Wesley Peng
+#
+# Licensed under the GNU Lesser General Public License v3.0 (LGPL-3.0).
+# You may obtain a copy of the License at
+#
+# https://www.gnu.org/licenses/lgpl-3.0.html
+#
+# This software is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+# GNU Lesser General Public License for more details.
+
+"""Test-suite-private helpers for plugin configuration overrides.
+
+The Agentic QA platform suites need to swap which concrete plugin
+ServiceLocator returns for a given plugin interface at fixture time
+(e.g. ``HttpxRESTPlugin`` vs the default REST plugin, or enabling
+the optional LLM judge). Each switch requires invalidating two
+singleton caches before re-resolving:
+
+* ``taf.foundation.conf.configuration.Configuration._instance``
+  and ``._settings`` — the YAML config singleton.
+* ``taf.foundation.servicelocator.ServiceLocator._plugins`` and
+  ``._clients`` — per-plugin discovery caches.
+
+Without the cache reset the new env-var override is ignored and the
+tests resolve a stale client class. The pattern was duplicated for
+each plugin in ``conftest.py``; this module pulls it into a single
+:class:`ConfigurationFixture` helper.
+"""
+
+import os
+from typing import Any, Type
+
+from taf.foundation import ServiceLocator
+from taf.foundation.conf.configuration import Configuration
+
+
+class ConfigurationFixture:
+    """Centralized helper for plugin-override fixtures.
+
+    Encapsulates the env-set, singleton-reset, ServiceLocator-resolve,
+    type-validate sequence that used to be hand-written per plugin.
+    """
+
+    @staticmethod
+    def set_env(overrides: dict[str, str]) -> None:
+        """Apply a batch of environment variable overrides.
+
+        The keys are typically TAF_PLUGIN_<NAME>_<FIELD> for plugin
+        configuration; values are forwarded to ``os.environ``.
+        """
+        for key, value in overrides.items():
+            os.environ[key] = value
+
+    @staticmethod
+    def reset_singletons(plugin_interface: Type[Any]) -> None:
+        """Invalidate Configuration + ServiceLocator caches for one plugin.
+
+        We pop only the cache entries for the specific plugin interface
+        so that other plugins resolved earlier in the session keep
+        their cached client classes.
+        """
+        Configuration._instance = None
+        Configuration._settings = None
+        ServiceLocator._plugins.pop(plugin_interface, None)
+        ServiceLocator._clients.pop(plugin_interface, None)
+
+    @classmethod
+    def resolve(
+        cls,
+        plugin_interface: Type[Any],
+        expected_client_cls: Type[Any],
+        env_overrides: dict[str, str] | None = None,
+    ) -> Type[Any]:
+        """Apply env overrides, reset singletons, and resolve the plugin.
+
+        Args:
+            plugin_interface: The plugin interface (e.g. ``RESTPlugin``).
+            expected_client_cls: The concrete client class the test
+                expects ServiceLocator to resolve to.
+            env_overrides: Optional environment variable overrides
+                applied before resetting the singletons.
+
+        Returns:
+            The resolved client class.
+
+        Raises:
+            AssertionError: If ServiceLocator returns ``None`` or a
+                client class other than ``expected_client_cls``.
+        """
+        if env_overrides:
+            cls.set_env(env_overrides)
+        cls.reset_singletons(plugin_interface)
+
+        client_cls = ServiceLocator.get_client(plugin_interface)
+        assert client_cls is not None, (
+            f'ServiceLocator failed to resolve {plugin_interface.__name__}'
+        )
+        assert client_cls is expected_client_cls, (
+            f'Expected {expected_client_cls.__name__}, '
+            f'got {client_cls.__name__}. '
+            f'ServiceLocator did not resolve to the expected plugin.'
+        )
+        return client_cls

src/test/python/suites/agentic/conftest.py

@@ -32,9 +32,9 @@
 import pytest
 import yaml
 
-from taf.foundation import ServiceLocator
 from taf.foundation.api.plugins import LLMPlugin, RESTPlugin
-from taf.foundation.conf.configuration import Configuration
+
+from ._fixtures import ConfigurationFixture
 
 
 _HAS_LANGCHAIN = (
@@ -59,28 +59,21 @@ def _load_config():
 
 
 def _configure_httpx_plugin():
-    """Switch REST plugin to httpx via env overrides, then resolve via ServiceLocator."""
-    os.environ['TAF_PLUGIN_REST_NAME'] = 'HttpxRESTPlugin'
-    os.environ['TAF_PLUGIN_REST_LOCATION'] = '../plugins/svc/httpx'
-
-    # Reset singletons so config reload picks up the override
-    Configuration._instance = None
-    Configuration._settings = None
-    ServiceLocator._plugins.pop(RESTPlugin, None)
-    ServiceLocator._clients.pop(RESTPlugin, None)
-
-    # Resolve through ServiceLocator — this proves the chain:
-    # config.yml + env override → ServiceLocator → HttpxRESTPlugin → HttpClient
-    client_cls = ServiceLocator.get_client(RESTPlugin)
-    assert client_cls is not None, 'ServiceLocator failed to resolve REST plugin'
+    """Switch REST plugin to httpx via env overrides, then resolve via ServiceLocator.
 
+    Uses :class:`ConfigurationFixture` to handle the env-set +
+    singleton-reset + resolve + type-validate sequence.
+    """
     from taf.foundation.plugins.svc.httpx import HttpClient
-    assert client_cls is HttpClient, (
-        f'Expected HttpClient, got {client_cls}. '
-        'ServiceLocator did not resolve to httpx plugin.'
-    )
 
-    return client_cls
+    return ConfigurationFixture.resolve(
+        plugin_interface=RESTPlugin,
+        expected_client_cls=HttpClient,
+        env_overrides={
+            'TAF_PLUGIN_REST_NAME': 'HttpxRESTPlugin',
+            'TAF_PLUGIN_REST_LOCATION': '../plugins/svc/httpx',
+        },
+    )
 
 
 @pytest.fixture(scope='session')
@@ -152,22 +145,13 @@ def _configure_llm_plugin():
         TAF_PLUGIN_LLM_ENABLED=true
             → Configuration → ServiceLocator → LLMJudgePlugin → LLMClient
     """
-    os.environ['TAF_PLUGIN_LLM_ENABLED'] = 'true'
-
-    Configuration._instance = None
-    Configuration._settings = None
-    ServiceLocator._plugins.pop(LLMPlugin, None)
-    ServiceLocator._clients.pop(LLMPlugin, None)
-
-    client_cls = ServiceLocator.get_client(LLMPlugin)
-    assert client_cls is not None, 'ServiceLocator failed to resolve LLM plugin'
-
     from taf.foundation.plugins.llm.judge.llmclient import LLMClient
-    assert client_cls is LLMClient, (
-        f'Expected LLMClient, got {client_cls}. '
-        'ServiceLocator did not resolve to LLM judge plugin.'
+
+    return ConfigurationFixture.resolve(
+        plugin_interface=LLMPlugin,
+        expected_client_cls=LLMClient,
+        env_overrides={'TAF_PLUGIN_LLM_ENABLED': 'true'},
     )
-    return client_cls
 
 
 @pytest.fixture(scope='session')

src/test/python/ut/test_configuration_fixture.py

@@ -0,0 +1,198 @@
+# Copyright (c) 2017-2026 Wesley Peng
+#
+# Licensed under the GNU Lesser General Public License v3.0 (LGPL-3.0).
+# You may obtain a copy of the License at
+#
+# https://www.gnu.org/licenses/lgpl-3.0.html
+#
+# This software is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+# GNU Lesser General Public License for more details.
+
+"""Unit tests for ConfigurationFixture.
+
+Locks the singleton-reset semantics that the platform suites rely on
+when swapping plugins at fixture time.
+"""
+
+import os
+import sys
+from pathlib import Path
+
+import pytest
+
+# The fixture lives alongside the agentic suite's conftest. The suite
+# directory isn't on sys.path by default for unit tests, so we add it.
+_SUITE_DIR = Path(__file__).parent.parent / 'suites' / 'agentic'
+if str(_SUITE_DIR) not in sys.path:
+    sys.path.insert(0, str(_SUITE_DIR))
+
+from _fixtures import ConfigurationFixture  # noqa: E402
+
+from taf.foundation import ServiceLocator  # noqa: E402
+from taf.foundation.api.plugins import RESTPlugin  # noqa: E402
+from taf.foundation.conf.configuration import Configuration  # noqa: E402
+
+
+class _FakePlugin:
+    """Marker class used as a plugin interface in tests."""
+
+
+class TestSetEnv:
+
+    def test_set_env_writes_to_os_environ(
+        self, monkeypatch: pytest.MonkeyPatch,
+    ) -> None:
+        monkeypatch.delenv('TAF_TEST_KEY_1', raising=False)
+        monkeypatch.delenv('TAF_TEST_KEY_2', raising=False)
+
+        ConfigurationFixture.set_env({
+            'TAF_TEST_KEY_1': 'value-1',
+            'TAF_TEST_KEY_2': 'value-2',
+        })
+        assert os.environ['TAF_TEST_KEY_1'] == 'value-1'
+        assert os.environ['TAF_TEST_KEY_2'] == 'value-2'
+
+    def test_empty_dict_is_noop(self) -> None:
+        # Should not raise, should not mutate os.environ
+        before = dict(os.environ)
+        ConfigurationFixture.set_env({})
+        assert dict(os.environ) == before
+
+
+class TestResetSingletons:
+
+    def test_clears_configuration_singleton(self) -> None:
+        # Force-prime the Configuration singleton.
+        Configuration._instance = object()  # type: ignore[assignment]
+        Configuration._settings = {'sentinel': True}  # type: ignore[assignment]
+
+        ConfigurationFixture.reset_singletons(_FakePlugin)
+        assert Configuration._instance is None
+        assert Configuration._settings is None
+
+    def test_pops_only_target_plugin_caches(self) -> None:
+        # Stash sentinel entries for two plugin interfaces.
+        ServiceLocator._plugins[_FakePlugin] = 'fake-plugin'
+        ServiceLocator._clients[_FakePlugin] = 'fake-client'
+        ServiceLocator._plugins[RESTPlugin] = 'rest-plugin-sentinel'
+        ServiceLocator._clients[RESTPlugin] = 'rest-client-sentinel'
+
+        ConfigurationFixture.reset_singletons(_FakePlugin)
+
+        # Target plugin caches were popped.
+        assert _FakePlugin not in ServiceLocator._plugins
+        assert _FakePlugin not in ServiceLocator._clients
+
+        # Other plugin caches are preserved.
+        assert ServiceLocator._plugins.get(RESTPlugin) == 'rest-plugin-sentinel'
+        assert ServiceLocator._clients.get(RESTPlugin) == 'rest-client-sentinel'
+
+        # Cleanup
+        ServiceLocator._plugins.pop(RESTPlugin, None)
+        ServiceLocator._clients.pop(RESTPlugin, None)
+
+    def test_no_op_if_target_not_in_caches(self) -> None:
+        # Should not raise even when nothing to pop.
+        ServiceLocator._plugins.pop(_FakePlugin, None)
+        ServiceLocator._clients.pop(_FakePlugin, None)
+        ConfigurationFixture.reset_singletons(_FakePlugin)
+
+
+class TestResolve:
+
+    def test_raises_when_service_locator_returns_none(
+        self, monkeypatch: pytest.MonkeyPatch,
+    ) -> None:
+        monkeypatch.setattr(
+            ServiceLocator, 'get_client', lambda iface: None,
+        )
+
+        with pytest.raises(AssertionError, match='failed to resolve'):
+            ConfigurationFixture.resolve(
+                plugin_interface=_FakePlugin,
+                expected_client_cls=str,
+            )
+
+    def test_raises_on_unexpected_client_class(
+        self, monkeypatch: pytest.MonkeyPatch,
+    ) -> None:
+        class _ExpectedCls:
+            pass
+
+        class _ActualCls:
+            pass
+
+        monkeypatch.setattr(
+            ServiceLocator, 'get_client', lambda iface: _ActualCls,
+        )
+
+        with pytest.raises(AssertionError, match='did not resolve to the expected plugin'):
+            ConfigurationFixture.resolve(
+                plugin_interface=_FakePlugin,
+                expected_client_cls=_ExpectedCls,
+            )
+
+    def test_returns_client_cls_on_success(
+        self, monkeypatch: pytest.MonkeyPatch,
+    ) -> None:
+        class _ExpectedCls:
+            pass
+
+        monkeypatch.setattr(
+            ServiceLocator, 'get_client', lambda iface: _ExpectedCls,
+        )
+
+        result = ConfigurationFixture.resolve(
+            plugin_interface=_FakePlugin,
+            expected_client_cls=_ExpectedCls,
+        )
+        assert result is _ExpectedCls
+
+    def test_applies_env_overrides_before_resolving(
+        self, monkeypatch: pytest.MonkeyPatch,
+    ) -> None:
+        seen_env: dict[str, str] = {}
+
+        def fake_get_client(_iface: object) -> type:
+            # Capture the env state ServiceLocator would see at this point
+            seen_env['TAF_PROBE'] = os.environ.get('TAF_PROBE', '')
+            return str
+
+        monkeypatch.setattr(ServiceLocator, 'get_client', fake_get_client)
+        monkeypatch.delenv('TAF_PROBE', raising=False)
+
+        ConfigurationFixture.resolve(
+            plugin_interface=_FakePlugin,
+            expected_client_cls=str,
+            env_overrides={'TAF_PROBE': 'set-by-fixture'},
+        )
+
+        # The override was visible to ServiceLocator at resolution time
+        assert seen_env['TAF_PROBE'] == 'set-by-fixture'
+
+    def test_resets_caches_on_each_call(
+        self, monkeypatch: pytest.MonkeyPatch,
+    ) -> None:
+        # Pre-populate the cache; resolve should clear it.
+        ServiceLocator._plugins[_FakePlugin] = 'stale'
+        ServiceLocator._clients[_FakePlugin] = 'stale'
+
+        called: list[bool] = []
+
+        def fake_get_client(iface: type) -> type:
+            # By the time get_client runs, the cache should already be
+            # cleared by reset_singletons().
+            called.append(True)
+            assert iface not in ServiceLocator._plugins
+            assert iface not in ServiceLocator._clients
+            return str
+
+        monkeypatch.setattr(ServiceLocator, 'get_client', fake_get_client)
+
+        ConfigurationFixture.resolve(
+            plugin_interface=_FakePlugin,
+            expected_client_cls=str,
+        )
+        assert called == [True]