feat(integration-tests): Validate the running package component-wise with validate_package_running.

integration-tests/.pytest.ini

@@ -3,6 +3,7 @@ addopts =
     --capture=no
     --code-highlight=yes
     --color=yes
+    -rA
     --strict-config
     --strict-markers
     --verbose
@@ -18,3 +19,4 @@ markers =
     clp: mark tests that use the CLP storage engine
     clp_s: mark tests that use the CLP-S storage engine
     core: mark tests that test the CLP core binaries
+    package: mark tests that run when the CLP package is active

integration-tests/pyproject.toml

@@ -27,6 +27,8 @@ dev = [
     "ruff>=0.11.12",
     "pytest>=8.4.1",
     "pytest-env>=1.1.5",
+    "PyYAML>=6.0",
+    "types-PyYAML>=6.0.12.20240808",
 ]
 
 [tool.mypy]

integration-tests/tests/conftest.py

@@ -1,6 +1,9 @@
-"""Make the fixtures defined in `tests/fixtures/` globally available without imports."""
+"""Global pytest setup."""
 
+# Make the fixtures defined in `tests/fixtures/` globally available without imports.
 pytest_plugins = [
     "tests.fixtures.integration_test_logs",
     "tests.fixtures.path_configs",
+    "tests.fixtures.package_instance",
+    "tests.fixtures.package_config",
 ]

integration-tests/tests/fixtures/package_config.py

@@ -0,0 +1,46 @@
+"""Fixtures that create and remove temporary config files for CLP packages."""
+
+import contextlib
+from collections.abc import Iterator
+
+import pytest
+
+from tests.utils.clp_mode_utils import (
+    get_clp_config_from_mode,
+    get_required_component_list,
+)
+from tests.utils.config import PackageConfig, PackagePathConfig
+
+
+@pytest.fixture
+def fixt_package_config(
+    fixt_package_path_config: PackagePathConfig,
+    request: pytest.FixtureRequest,
+) -> Iterator[PackageConfig]:
+    """
+    Creates and maintains a PackageConfig object for a specific CLP mode.
+
+    :param request:
+    :return: An iterator that yields the PackageConfig object for the specified mode.
+    """
+    mode_name: str = request.param
+
+    # Get the ClpConfig for this mode.
+    clp_config_obj = get_clp_config_from_mode(mode_name)
+
+    # Compute the list of required components for this mode.
+    required_components = get_required_component_list(clp_config_obj)
+
+    # Construct PackageConfig.
+    package_config = PackageConfig(
+        path_config=fixt_package_path_config,
+        mode_name=mode_name,
+        component_list=required_components,
+        clp_config=clp_config_obj,
+    )
+
+    try:
+        yield package_config
+    finally:
+        with contextlib.suppress(FileNotFoundError):
+            package_config.temp_config_file_path.unlink()

integration-tests/tests/fixtures/package_instance.py

@@ -0,0 +1,41 @@
+"""Fixtures that start and stop CLP package instances for integration tests."""
+
+import subprocess
+from collections.abc import Iterator
+
+import pytest
+
+from tests.utils.config import (
+    PackageConfig,
+    PackageInstance,
+)
+from tests.utils.package_utils import (
+    start_clp_package,
+    stop_clp_package,
+)
+
+
+@pytest.fixture
+def fixt_package_instance(fixt_package_config: PackageConfig) -> Iterator[PackageInstance]:
+    """
+    Starts a CLP package instance for the given configuration and stops it during teardown.
+
+    :param fixt_package_config:
+    :param request:
+    :return: Iterator that yields the running package instance.
+    """
+    mode_name = fixt_package_config.mode_name
+    instance: PackageInstance | None = None
+
+    try:
+        start_clp_package(fixt_package_config)
+        instance = PackageInstance(package_config=fixt_package_config)
+        yield instance
+    except RuntimeError:
+        pytest.fail(f"Failed to start the {mode_name} package.")
+    finally:
+        if instance is not None:
+            stop_clp_package(instance)
+        else:
+            # This means setup failed after start; fall back to calling stop script directly
+            subprocess.run([str(fixt_package_config.path_config.stop_script_path)], check=False)

integration-tests/tests/fixtures/path_configs.py

@@ -25,6 +25,11 @@ def integration_test_path_config() -> IntegrationTestPathConfig:
 
 
 @pytest.fixture(scope="session")
-def package_path_config() -> PackagePathConfig:
-    """Provides paths for the clp-package directory and its contents."""
-    return PackagePathConfig(clp_package_dir=resolve_path_env_var("CLP_PACKAGE_DIR"))
+def fixt_package_path_config(
+    integration_test_path_config: IntegrationTestPathConfig,
+) -> PackagePathConfig:
+    """Fixture that provides a PackagePathConfig shared across tests."""
+    return PackagePathConfig(
+        clp_package_dir=resolve_path_env_var("CLP_PACKAGE_DIR"),
+        test_root_dir=integration_test_path_config.test_root_dir,
+    )

integration-tests/tests/test_package_start.py

@@ -0,0 +1,28 @@
+"""Integration tests verifying that the CLP package can be started and stopped."""
+
+import logging
+
+import pytest
+
+from tests.utils.asserting_utils import (
+    validate_package_running,
+)
+from tests.utils.clp_mode_utils import CLP_MODE_CONFIGS
+from tests.utils.config import PackageInstance
+
+TEST_MODES = CLP_MODE_CONFIGS.keys()
+
+logger = logging.getLogger(__name__)
+
+
+@pytest.mark.package
+@pytest.mark.parametrize("fixt_package_config", TEST_MODES, indirect=True)
+def test_clp_package(fixt_package_instance: PackageInstance) -> None:
+    """
+    Validate that all of the components of the CLP package start up successfully for the selected
+    mode of operation.
+
+    :param fixt_package_instance:
+    """
+    # Ensure that all package components are running.
+    validate_package_running(fixt_package_instance)

integration-tests/tests/utils/asserting_utils.py

@@ -5,6 +5,9 @@
 
 import pytest
 
+from tests.utils.config import PackageInstance
+from tests.utils.docker_utils import list_running_containers_with_prefix
+
 
 def run_and_assert(cmd: list[str], **kwargs: Any) -> subprocess.CompletedProcess[Any]:
     """
@@ -20,3 +23,24 @@ def run_and_assert(cmd: list[str], **kwargs: Any) -> subprocess.CompletedProcess
     except subprocess.CalledProcessError as e:
         pytest.fail(f"Command failed: {' '.join(cmd)}: {e}")
     return proc
+
+
+def validate_package_running(package_instance: PackageInstance) -> None:
+    """
+    Validate that the given package instance is running. Each required component must have at least
+    one running container whose name matches the expected prefix. Calls pytest.fail on the first
+    missing component.
+
+    :param package_instance:
+    """
+    instance_id = package_instance.clp_instance_id
+    required_components = package_instance.package_config.component_list
+
+    for component in required_components:
+        prefix = f"clp-package-{instance_id}-{component}-"
+        running_matches = list_running_containers_with_prefix(prefix)
+        if len(running_matches) == 0:
+            pytest.fail(
+                f"No running container found for component '{component}' "
+                f"(expected name prefix '{prefix}')."
+            )

integration-tests/tests/utils/clp_mode_utils.py

@@ -0,0 +1,115 @@
+"""Provides utilities related to the user-level configurations of CLP's operating modes."""
+
+from collections.abc import Callable
+
+from clp_py_utils.clp_config import (
+    API_SERVER_COMPONENT_NAME,
+    ClpConfig,
+    COMPRESSION_SCHEDULER_COMPONENT_NAME,
+    COMPRESSION_WORKER_COMPONENT_NAME,
+    DB_COMPONENT_NAME,
+    DeploymentType,
+    GARBAGE_COLLECTOR_COMPONENT_NAME,
+    MCP_SERVER_COMPONENT_NAME,
+    Package,
+    QUERY_SCHEDULER_COMPONENT_NAME,
+    QUERY_WORKER_COMPONENT_NAME,
+    QueryEngine,
+    QUEUE_COMPONENT_NAME,
+    REDIS_COMPONENT_NAME,
+    REDUCER_COMPONENT_NAME,
+    RESULTS_CACHE_COMPONENT_NAME,
+    StorageEngine,
+    WEBUI_COMPONENT_NAME,
+)
+
+CLP_MODE_CONFIGS: dict[str, Callable[[], ClpConfig]] = {
+    "clp-text": lambda: ClpConfig(
+        package=Package(
+            storage_engine=StorageEngine.CLP,
+            query_engine=QueryEngine.CLP,
+        ),
+    ),
+    "clp-json": lambda: ClpConfig(
+        package=Package(
+            storage_engine=StorageEngine.CLP_S,
+            query_engine=QueryEngine.CLP_S,
+        ),
+    ),
+}
+
+
+# TODO: This will eventually be replaced by a formalized mapping between component and service.
+def _to_docker_compose_service_name(name: str) -> str:
+    """
+    Convert a component name to a Docker Compose service name.
+
+    :param name:
+    :return: Service name with underscores replaced by hyphens
+    """
+    return name.replace("_", "-")
+
+
+CLP_BASE_COMPONENTS = [
+    _to_docker_compose_service_name(DB_COMPONENT_NAME),
+    _to_docker_compose_service_name(QUEUE_COMPONENT_NAME),
+    _to_docker_compose_service_name(REDIS_COMPONENT_NAME),
+    _to_docker_compose_service_name(REDUCER_COMPONENT_NAME),
+    _to_docker_compose_service_name(RESULTS_CACHE_COMPONENT_NAME),
+    _to_docker_compose_service_name(COMPRESSION_SCHEDULER_COMPONENT_NAME),
+    _to_docker_compose_service_name(COMPRESSION_WORKER_COMPONENT_NAME),
+    _to_docker_compose_service_name(API_SERVER_COMPONENT_NAME),
+    _to_docker_compose_service_name(WEBUI_COMPONENT_NAME),
+]
+
+CLP_QUERY_COMPONENTS = [
+    _to_docker_compose_service_name(QUERY_SCHEDULER_COMPONENT_NAME),
+    _to_docker_compose_service_name(QUERY_WORKER_COMPONENT_NAME),
+]
+
+CLP_GARBAGE_COLLECTOR_COMPONENT = _to_docker_compose_service_name(GARBAGE_COLLECTOR_COMPONENT_NAME)
+
+CLP_MCP_SERVER_COMPONENT = _to_docker_compose_service_name(MCP_SERVER_COMPONENT_NAME)
+
+
+def get_clp_config_from_mode(mode_name: str) -> ClpConfig:
+    """
+    Return a ClpConfig object for the given mode name.
+
+    :param mode_name:
+    :return: ClpConfig object corresponding to the mode.
+    :raise ValueError: If the mode is not supported.
+    """
+    try:
+        config = CLP_MODE_CONFIGS[mode_name]
+    except KeyError as err:
+        err_msg = f"Unsupported mode: {mode_name}"
+        raise ValueError(err_msg) from err
+    return config()
+
+
+def get_required_component_list(config: ClpConfig) -> list[str]:
+    """
+    Constructs a list of the components that the CLP package described in `config` needs to run
+    properly.
+
+    :param config:
+    :return: List of components required by the package.
+    """
+    component_list: list[str] = []
+    component_list.extend(CLP_BASE_COMPONENTS)
+
+    deployment_type = config.get_deployment_type()
+    if deployment_type == DeploymentType.FULL:
+        component_list.extend(CLP_QUERY_COMPONENTS)
+
+    if (
+        config.archive_output.retention_period is not None
+        or config.results_cache.retention_period is not None
+    ):
+        component_list.append(CLP_GARBAGE_COLLECTOR_COMPONENT)
+
+    if config.mcp_server is not None:
+        component_list.append(CLP_MCP_SERVER_COMPONENT)
+
+    return component_list