feat(integration-tests): Test search with the CLP package.

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,6 @@ 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
+
+BASE_PORT = 55000

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,35 @@
-"""Make the fixtures defined in `tests/fixtures/` globally available without imports."""
+"""Global pytest setup."""
 
+import pytest
+
+# 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",
 ]
+
+
+def pytest_addoption(parser: pytest.Parser) -> None:
+    """
+    Adds options for pytest.
+
+    :param parser:
+    """
+    parser.addini(
+        "BASE_PORT",
+        "Base port for CLP package integration tests.",
+        default="55000",
+    )
+    parser.addoption(
+        "--job-name",
+        dest="JOB_NAME",
+        help="Filter CLP jobs by substring of their job_name.",
+    )
+    parser.addoption(
+        "--no-jobs",
+        action="store_true",
+        dest="NO_JOBS",
+        help=("Only validate CLP package start and stop. Do not create or run any test jobs."),
+    )

integration-tests/tests/fixtures/integration_test_logs.py

@@ -43,6 +43,20 @@ def postgresql(
     )
 
 
+@pytest.fixture(scope="session")
+def spark_event_logs(
+    request: pytest.FixtureRequest,
+    integration_test_path_config: IntegrationTestPathConfig,
+) -> IntegrationTestLogs:
+    """Provides shared `spark_event_logs` test logs."""
+    return _download_and_extract_dataset(
+        request=request,
+        integration_test_path_config=integration_test_path_config,
+        name="spark-event-logs",
+        tarball_url="https://zenodo.org/records/10516346/files/spark-event-logs.tar.gz?download=1",
+    )
+
+
 def _download_and_extract_dataset(
     request: pytest.FixtureRequest,
     integration_test_path_config: IntegrationTestPathConfig,

integration-tests/tests/fixtures/package_config.py

@@ -0,0 +1,88 @@
+"""Fixtures that create and remove temporary config files for CLP packages."""
+
+import contextlib
+import logging
+from collections.abc import Iterator
+
+import pytest
+from clp_py_utils.clp_config import (
+    CLP_DEFAULT_DATA_DIRECTORY_PATH,
+    CLP_DEFAULT_TMP_DIRECTORY_PATH,
+)
+
+from tests.utils.clp_job_utils import (
+    build_package_job_list,
+)
+from tests.utils.clp_mode_utils import (
+    get_clp_config_from_mode,
+    get_required_component_list,
+)
+from tests.utils.config import (
+    PackageConfig,
+    PackagePathConfig,
+)
+from tests.utils.port_utils import assign_ports_from_base
+from tests.utils.utils import unlink
+
+logger = logging.getLogger(__name__)
+
+
+@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
+    logger.debug("Creating a temporary config file for the %s package.", mode_name)
+
+    # Get the ClpConfig for this mode.
+    clp_config_obj = get_clp_config_from_mode(mode_name)
+
+    # Assign ports based on BASE_PORT from ini.
+    base_port_string = request.config.getini("BASE_PORT")
+    try:
+        base_port = int(base_port_string)
+    except ValueError as err:
+        err_msg = (
+            f"Invalid BASE_PORT value '{base_port_string}' in pytest.ini; expected an integer."
+        )
+        raise ValueError(err_msg) from err
+
+    assign_ports_from_base(base_port, clp_config_obj)
+
+    # Compute the list of required components for this mode.
+    required_components = get_required_component_list(clp_config_obj)
+
+    # Build the job list for this mode and the current job filter.
+    no_jobs: bool = bool(request.config.option.NO_JOBS)
+    job_filter: str = request.config.option.JOB_NAME or ""
+    package_job_list = None if no_jobs else build_package_job_list(mode_name, job_filter)
+
+    # Construct PackageConfig.
+    package_config = PackageConfig(
+        path_config=fixt_package_path_config,
+        mode_name=mode_name,
+        component_list=required_components,
+        clp_config=clp_config_obj,
+        package_job_list=package_job_list,
+    )
+
+    try:
+        yield package_config
+    finally:
+        logger.debug("Removing the temporary config file and var contents.")
+
+        with contextlib.suppress(FileNotFoundError):
+            package_config.temp_config_file_path.unlink()
+
+        # Clear data, tmp, and log from the package directory.
+        data_dir = package_config.path_config.clp_package_dir / CLP_DEFAULT_DATA_DIRECTORY_PATH
+        tmp_dir = package_config.path_config.clp_package_dir / CLP_DEFAULT_TMP_DIRECTORY_PATH
+        for directory_path in (data_dir, tmp_dir):
+            unlink(directory_path)

integration-tests/tests/fixtures/package_instance.py

@@ -0,0 +1,60 @@
+"""Fixtures that start and stop CLP package instances for integration tests."""
+
+import logging
+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,
+)
+
+logger = logging.getLogger(__name__)
+
+
+@pytest.fixture
+def fixt_package_instance(
+    fixt_package_config: PackageConfig,
+    request: pytest.FixtureRequest,
+) -> 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
+    no_jobs: bool = bool(request.config.option.NO_JOBS)
+    instance: PackageInstance | None = None
+    package_job_list = fixt_package_config.package_job_list
+
+    # Do not start this mode if there are no jobs and the '--no-jobs' flag wasn't specified by user.
+    if package_job_list is None and not no_jobs:
+        pytest.skip(f"No jobs to run for mode {mode_name} with current job filter.")
+
+    try:
+        logger.debug("Starting up the %s package.", mode_name)
+        start_clp_package(fixt_package_config)
+        instance = PackageInstance(package_config=fixt_package_config)
+        yield instance
+    except RuntimeError:
+        base_port_string = request.config.getini("BASE_PORT")
+        pytest.fail(
+            f"Failed to start the {mode_name} package. This could mean that one of the ports"
+            f" derived from BASE_PORT={base_port_string} was unavailable. Try changing BASE_PORT in"
+            " .pytest.ini."
+        )
+    finally:
+        logger.debug("Now stopping the %s package...", mode_name)
+        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,59 @@
+"""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,
+    validate_running_mode_correct,
+)
+from tests.utils.clp_job_utils import (
+    dispatch_test_jobs,
+)
+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(
+    request: pytest.FixtureRequest, 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:
+    """
+    mode_name = fixt_package_instance.package_config.mode_name
+    instance_id = fixt_package_instance.clp_instance_id
+
+    # Ensure that all package components are running.
+    logger.debug(
+        "Checking if all components of %s package with instance ID '%s' are running properly.",
+        mode_name,
+        instance_id,
+    )
+
+    validate_package_running(fixt_package_instance)
+
+    # Ensure that the package is running in the correct mode.
+    logger.debug(
+        "Checking that the %s package with instance ID '%s' is running in the correct mode.",
+        mode_name,
+        instance_id,
+    )
+
+    validate_running_mode_correct(fixt_package_instance)
+
+    # Run all jobs.
+    package_job_list = fixt_package_instance.package_config.package_job_list
+    if package_job_list is not None:
+        dispatch_test_jobs(request, fixt_package_instance)

integration-tests/tests/utils/asserting_utils.py

@@ -4,6 +4,15 @@
 from typing import Any
 
 import pytest
+from clp_py_utils.clp_config import ClpConfig
+from pydantic import ValidationError
+
+from tests.utils.clp_mode_utils import (
+    compute_mode_signature,
+)
+from tests.utils.config import PackageInstance
+from tests.utils.docker_utils import list_running_containers_with_prefix
+from tests.utils.utils import load_yaml_to_dict
 
 
 def run_and_assert(cmd: list[str], **kwargs: Any) -> subprocess.CompletedProcess[Any]:
@@ -20,3 +29,47 @@ 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}')."
+            )
+
+
+def validate_running_mode_correct(package_instance: PackageInstance) -> None:
+    """
+    Validate that the mode described in the shared config of the instance matches the intended mode
+    defined by the instance configuration. Calls pytest.fail if the shared config fails validation
+    or if the running mode does not match the intended mode.
+
+    :param package_instance:
+    """
+    shared_config_dict = load_yaml_to_dict(package_instance.shared_config_file_path)
+    try:
+        running_config = ClpConfig.model_validate(shared_config_dict)
+    except ValidationError as err:
+        pytest.fail(f"Shared config failed validation: {err}")
+
+    intended_config = package_instance.package_config.clp_config
+
+    running_signature = compute_mode_signature(running_config)
+    intended_signature = compute_mode_signature(intended_config)
+
+    if running_signature != intended_signature:
+        pytest.fail("Mode mismatch: running configuration does not match intended configuration.")