feat(integration-tests): Test the startup and teardown of the clp-text and clp-json packages.

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

@@ -17,14 +17,18 @@ build-backend = "hatchling.build"
 
 [dependency-groups]
 dev = [
+    "clp-py-utils",
     "mypy>=1.16.0",
     "ruff>=0.11.12",
     "pytest>=8.4.1",
     "pytest-env>=1.1.5",
+    "PyYAML>=6.0",
+    "types-PyYAML>=6.0.12.20240808",
 ]
 
 [tool.mypy]
 strict = true
+ignore_missing_imports = true
 
 # Additional output
 pretty = true
@@ -69,3 +73,6 @@ isort.order-by-type = false
 [tool.ruff.format]
 docstring-code-format = true
 docstring-code-line-length = 100
+
+[tool.uv.sources]
+clp-py-utils = { path = "../components/clp-py-utils" }

integration-tests/tests/conftest.py

@@ -3,4 +3,6 @@
 pytest_plugins = [
     "tests.fixtures.integration_test_config",
     "tests.fixtures.integration_test_logs",
+    "tests.fixtures.package_instance_fixtures",
+    "tests.fixtures.package_config_fixtures",
 ]

integration-tests/tests/fixtures/integration_test_config.py

@@ -24,7 +24,9 @@ def core_config() -> CoreConfig:
 def package_config() -> PackageConfig:
     """Fixture that provides a PackageConfig shared across tests."""
     return PackageConfig(
-        clp_package_dir=Path(get_env_var("CLP_PACKAGE_DIR")).expanduser().resolve()
+        clp_package_dir=Path(get_env_var("CLP_PACKAGE_DIR")).expanduser().resolve(),
+        test_root_dir=Path(get_env_var("CLP_BUILD_DIR")).expanduser().resolve()
+        / "integration-tests",
     )
 
 

integration-tests/tests/fixtures/package_config_fixtures.py

@@ -0,0 +1,73 @@
+"""Fixtures that create and remove temporary config files for CLP packages."""
+
+import logging
+from collections.abc import Iterator
+from pathlib import Path
+from typing import Any
+
+import pytest
+
+from tests.utils.config import (
+    PackageConfig,
+    PackageInstanceConfig,
+    PackageModeConfig,
+)
+from tests.utils.package_utils import (
+    CLP_MODE_CONFIGS,
+    get_dict_from_mode_name,
+    write_temp_config_file,
+)
+
+logger = logging.getLogger(__name__)
+
+
+def _build_package_instance_config(
+    mode_name: str,
+    package_config: PackageConfig,
+) -> PackageInstanceConfig:
+    """Construct a PackageInstanceConfig for the given `mode_name`."""
+    if mode_name not in CLP_MODE_CONFIGS:
+        err_msg = f"Unknown CLP mode '{mode_name}'. Known modes: {list(CLP_MODE_CONFIGS.keys())}"
+        raise KeyError(err_msg)
+
+    # Find the corresponding PackageModeConfig object and instantiate PackageInstanceConfig.
+    mode_config: PackageModeConfig = CLP_MODE_CONFIGS[mode_name]
+    run_config = PackageInstanceConfig(
+        package_config=package_config,
+        mode_config=mode_config,
+    )
+
+    # Write the temporary config file that the instance will use during the test.
+    mode_kv_dict: dict[str, Any] = get_dict_from_mode_name(mode_name)
+    temp_config_file_path: Path = write_temp_config_file(
+        mode_kv_dict=mode_kv_dict,
+        temp_config_dir=package_config.temp_config_dir,
+        mode_name=mode_name,
+    )
+    object.__setattr__(run_config, "temp_config_file_path", temp_config_file_path)
+
+    return run_config
+
+
+@pytest.fixture
+def clp_config(
+    request: pytest.FixtureRequest,
+    package_config: PackageConfig,
+) -> Iterator[PackageInstanceConfig]:
+    """
+    Parameterized fixture that creates and removes a temporary config file for a mode of operation.
+    The mode name arrives through request.param from the test's indirect parametrization.
+    """
+    mode_name: str = request.param
+    logger.info("Creating a temporary config file for the %s package...", mode_name)
+
+    run_config = _build_package_instance_config(mode_name, package_config)
+
+    logger.info("The temporary config file has been written for the %s package.", mode_name)
+
+    try:
+        yield run_config
+    finally:
+        logger.info("Removing the temporary config file...")
+        run_config.temp_config_file_path.unlink()
+        logger.info("The temporary config file has been removed.")

integration-tests/tests/fixtures/package_instance_fixtures.py

@@ -0,0 +1,48 @@
+"""Fixtures that start and stop CLP package instances for integration tests."""
+
+import logging
+from collections.abc import Iterator
+
+import pytest
+
+from tests.utils.config import (
+    PackageInstance,
+    PackageInstanceConfig,
+)
+from tests.utils.package_utils import (
+    start_clp_package,
+    stop_clp_package,
+)
+
+logger = logging.getLogger(__name__)
+
+
+@pytest.fixture
+def clp_package(
+    clp_config: PackageInstanceConfig,
+) -> Iterator[PackageInstance]:
+    """
+    Parameterized fixture that starts a CLP instance for the mode supplied to `clp_config`,
+    and gracefully stops it at scope boundary (fixture teardown).
+    """
+    mode_name = clp_config.mode_config.name
+    logger.info("Starting up the %s package...", mode_name)
+
+    start_clp_package(clp_config)
+
+    instance = PackageInstance(package_instance_config=clp_config)
+    instance_id = instance.clp_instance_id
+    logger.info(
+        "An instance of the %s package was started successfully. Its instance ID is '%s'",
+        mode_name,
+        instance_id,
+    )
+
+    try:
+        yield instance
+    finally:
+        logger.info("Now stopping the %s package with instance ID '%s'...", mode_name, instance_id)
+        stop_clp_package(instance)
+        logger.info(
+            "The %s package with instance ID '%s' was stopped successfully.", mode_name, instance_id
+        )

integration-tests/tests/test_package_start.py

@@ -0,0 +1,65 @@
+"""Integration tests verifying that the CLP package can be started and stopped."""
+
+import logging
+
+import pytest
+
+from tests.utils.config import PackageInstance
+from tests.utils.package_utils import (
+    CLP_MODE_CONFIGS,
+    is_package_running,
+    is_running_mode_correct,
+)
+
+TEST_MODES = CLP_MODE_CONFIGS.keys()
+
+logger = logging.getLogger(__name__)
+
+
+@pytest.mark.package
+@pytest.mark.parametrize("clp_config", TEST_MODES, indirect=True)
+def test_clp_package(clp_package: PackageInstance) -> None:
+    """
+    Validate that all of the components of the CLP package start up successfully for the selected
+    mode of operation.
+    """
+    # Spin up the package by getting the PackageInstance fixture.
+    package_instance = clp_package
+    mode_name = package_instance.package_instance_config.mode_config.name
+    instance_id = package_instance.clp_instance_id
+
+    # Ensure that all package components are running.
+    logger.info(
+        "Checking if all components of %s package with instance ID '%s' are running properly...",
+        mode_name,
+        instance_id,
+    )
+
+    running, fail_msg = is_package_running(package_instance)
+    if not running:
+        assert fail_msg is not None
+        pytest.fail(fail_msg)
+
+    logger.info(
+        "All components of the %s package with instance ID '%s' are running properly.",
+        mode_name,
+        instance_id,
+    )
+
+    # Ensure that the package is running in the correct mode.
+    logger.info(
+        "Checking that the %s package with instance ID '%s' is running in the correct mode...",
+        mode_name,
+        instance_id,
+    )
+
+    correct, fail_msg = is_running_mode_correct(package_instance)
+    if not correct:
+        assert fail_msg is not None
+        pytest.fail(fail_msg)
+
+    logger.info(
+        "The %s package with instance ID '%s' is running in the correct mode.",
+        mode_name,
+        instance_id,
+    )

integration-tests/tests/utils/config.py

@@ -2,12 +2,19 @@
 
 from __future__ import annotations
 
+import re
+from collections.abc import Callable
 from dataclasses import dataclass, field, InitVar
 from pathlib import Path
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from clp_py_utils.clp_config import CLPConfig
 
 from tests.utils.utils import (
     unlink,
     validate_dir_exists,
+    validate_file_exists,
 )
 
 
@@ -57,18 +64,26 @@ def clp_s_binary_path(self) -> Path:
 
 @dataclass(frozen=True)
 class PackageConfig:
-    """The configuration for the clp package subject to testing."""
+    """Metadata for the clp package test on this system."""
 
-    #:
+    #: The directory the package is located in.
     clp_package_dir: Path
 
-    def __post_init__(self) -> None:
-        """Validates that the CLP package directory exists and contains all required directories."""
+    #: Root directory for package tests output.
+    test_root_dir: Path
+
+    temp_config_dir_init: InitVar[Path | None] = None
+    #: Directory to store any cached package config files.
+    temp_config_dir: Path = field(init=False, repr=True)
+
+    def __post_init__(self, temp_config_dir_init: Path | None) -> None:
+        """Validates the values specified at init, and initialises attributes."""
+        # Validate that the CLP package directory exists and contains all required directories.
         clp_package_dir = self.clp_package_dir
         validate_dir_exists(clp_package_dir)
 
         # Check for required package script directories
-        required_dirs = ["bin", "etc", "lib", "sbin"]
+        required_dirs = ["etc", "sbin"]
         missing_dirs = [d for d in required_dirs if not (clp_package_dir / d).is_dir()]
         if len(missing_dirs) > 0:
             err_msg = (
@@ -77,6 +92,100 @@ def __post_init__(self) -> None:
             )
             raise ValueError(err_msg)
 
+        # Initialize and create required cache directory for package tests.
+        if temp_config_dir_init is not None:
+            object.__setattr__(self, "temp_config_dir", temp_config_dir_init)
+        else:
+            object.__setattr__(self, "temp_config_dir", self.test_root_dir / "config-cache")
+
+        self.test_root_dir.mkdir(parents=True, exist_ok=True)
+        self.temp_config_dir.mkdir(parents=True, exist_ok=True)
+
+    @property
+    def start_script_path(self) -> Path:
+        """:return: The absolute path to the package start script."""
+        return self.clp_package_dir / "sbin" / "start-clp.sh"
+
+    @property
+    def stop_script_path(self) -> Path:
+        """:return: The absolute path to the package stop script."""
+        return self.clp_package_dir / "sbin" / "stop-clp.sh"
+
+
+@dataclass(frozen=True)
+class PackageModeConfig:
+    """Builds a fully formed CLPConfig for a named mode."""
+
+    name: str
+    build_config: Callable[[], CLPConfig]
+
+
+@dataclass(frozen=True)
+class PackageInstanceConfig:
+    """Metadata for the clp-config.yml file used to configure a clp package instance."""
+
+    #: The PackageConfig object corresponding to this package run.
+    package_config: PackageConfig
+
+    #: The PackageModeConfig object describing this config file's configuration.
+    mode_config: PackageModeConfig
+
+    #: The location of the configfile used during this package run.
+    temp_config_file_path: Path = field(init=False, repr=True)
+
+
+@dataclass(frozen=True)
+class PackageInstance:
+    """Metadata for a run of the clp package."""
+
+    #:
+    package_instance_config: PackageInstanceConfig
+
+    #:
+    clp_log_dir: Path = field(init=False, repr=True)
+
+    #:
+    clp_instance_id: str = field(init=False, repr=True)
+
+    #: The path to the .clp-config.yml file constructed by the package during spin-up.
+    shared_config_file_path: Path = field(init=False, repr=True)
+
+    def __post_init__(self) -> None:
+        """Validates the values specified at init, and initialises attributes."""
+        # Set clp_log_dir and validate that it exists.
+        clp_log_dir = self.package_instance_config.package_config.clp_package_dir / "var" / "log"
+        validate_dir_exists(clp_log_dir)
+        object.__setattr__(self, "clp_log_dir", clp_log_dir)
+
+        # Set clp_instance_id.
+        clp_instance_id_file_path = self.clp_log_dir / "instance-id"
+        validate_file_exists(clp_instance_id_file_path)
+        clp_instance_id = self._get_clp_instance_id(clp_instance_id_file_path)
+        object.__setattr__(self, "clp_instance_id", clp_instance_id)
+
+        # Set shared_config_file_path after validating it.
+        shared_config_file_path = self.clp_log_dir / ".clp-config.yml"
+        validate_file_exists(shared_config_file_path)
+        object.__setattr__(self, "shared_config_file_path", shared_config_file_path)
+
+    @staticmethod
+    def _get_clp_instance_id(clp_instance_id_file_path: Path) -> str:
+        """Return the 4-digit hexadecimal CLP instance-id stored at clp_instance_id_file_path."""
+        try:
+            contents = clp_instance_id_file_path.read_text(encoding="utf-8").strip()
+        except OSError as err:
+            err_msg = f"Cannot read instance-id file {clp_instance_id_file_path}: {err}"
+            raise ValueError(err_msg) from err
+
+        if not re.fullmatch(r"[0-9a-fA-F]{4}", contents):
+            err_msg = (
+                f"Invalid instance ID in {clp_instance_id_file_path}: expected a 4-character"
+                f" hexadecimal string, but read {contents}."
+            )
+            raise ValueError(err_msg)
+
+        return contents
+
 
 @dataclass(frozen=True)
 class IntegrationTestConfig: