feat(xtest): --scenario and --instance flags for conftest (DSPX-3302)

Adds two new pytest CLI options so xtest can be driven by a scenarios.yaml
and run against a specific otdf-local instance.

  --scenario PATH    When set, defaults --sdks-encrypt, --sdks-decrypt,
                     and --containers from the scenario's `sdks` and
                     `suite` blocks. Options explicitly passed on the
                     CLI always override.
  --instance NAME    Propagated to OTDF_LOCAL_INSTANCE_NAME so child
                     `otdf-local` invocations within the test see the
                     same instance the scenario expects.

If otdf-sdk-mgr is not installed (minimal pytest environments), the
--scenario flag silently no-ops via an ImportError guard. The flag
shape is invariant either way so CI configs don't fork.

This is the consumer side of the PR 3 / scenario-driven flow: the
authoritative entry point remains `otdf-local scenario run <path>`,
which sets these flags for you; this PR lets pytest accept them
directly when running scenario-aware sessions outside the wrapper.

Refs: https://virtru.atlassian.net/browse/DSPX-3302

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: dmihalcik-virtru

xtest/conftest.py

@@ -78,6 +78,16 @@ def sdk_spec_type(v: str) -> str:
 
 def pytest_addoption(parser: pytest.Parser):
     """Add custom CLI options for pytest."""
+    parser.addoption(
+        "--scenario",
+        help="path to scenarios.yaml; --sdks-encrypt/--sdks-decrypt/--containers default from it",
+        type=Path,
+    )
+    parser.addoption(
+        "--instance",
+        help="otdf-local instance name; sets OTDF_LOCAL_INSTANCE_NAME for child tooling",
+        type=str,
+    )
     parser.addoption(
         "--audit-log-dir",
         help="directory to write audit logs on test failure (default: tmp/audit-logs)",
@@ -130,6 +140,57 @@ def pytest_addoption(parser: pytest.Parser):
     )
 
 
+def pytest_configure(config: pytest.Config) -> None:
+    """Apply --scenario defaults and --instance env-var threading.
+
+    When `--scenario PATH` is given, missing `--sdks-encrypt`, `--sdks-decrypt`,
+    and `--containers` options are populated from the scenario file. Options
+    explicitly passed on the CLI always win. `--instance NAME` is propagated
+    via `OTDF_LOCAL_INSTANCE_NAME` so any child `otdf-local` invocation sees
+    the same instance.
+    """
+    import os
+
+    instance = config.getoption("--instance")
+    if instance:
+        os.environ["OTDF_LOCAL_INSTANCE_NAME"] = instance
+
+    scenario_path = config.getoption("--scenario")
+    if not scenario_path:
+        return
+    try:
+        from otdf_sdk_mgr.schema import (
+            installed_json_for,
+            load_scenario,
+            scenario_to_pytest_sdks,
+        )
+    except ImportError:
+        # otdf-sdk-mgr may not be installed in a minimal pytest env.
+        return
+    scenario = load_scenario(scenario_path)
+    # `sdk@<version>` tokens come from the install record so they match the
+    # dist directories #446's parser walks under `xtest/sdk/<lang>/dist/`.
+    # If the user passed --sdks-encrypt / --sdks-decrypt explicitly, their
+    # tokens win and we skip the resolution step entirely.
+    need_resolve = (
+        (not config.getoption("--sdks-encrypt") and scenario.sdks.encrypt)
+        or (not config.getoption("--sdks-decrypt") and scenario.sdks.decrypt)
+    )
+    if need_resolve:
+        try:
+            tokens = scenario_to_pytest_sdks(scenario, installed_json_for(scenario_path))
+        except FileNotFoundError as e:
+            raise pytest.UsageError(str(e)) from e
+        if not config.getoption("--sdks-encrypt") and tokens["encrypt"]:
+            config.option.sdks_encrypt = " ".join(tokens["encrypt"])
+        if not config.getoption("--sdks-decrypt") and tokens["decrypt"]:
+            config.option.sdks_decrypt = " ".join(tokens["decrypt"])
+    if not config.getoption("--containers") and scenario.suite.containers:
+        config.option.containers = scenario.suite.containers
+    if not instance and scenario.instance.metadata.name:
+        os.environ["OTDF_LOCAL_INSTANCE_NAME"] = scenario.instance.metadata.name
+
+
 def pytest_generate_tests(metafunc: pytest.Metafunc):
     """Dynamically parametrize test functions based on CLI options.