Exasol Integration Test Docker Environment

Common errors

• ModuleNotFoundError: No module named 'exasol_integration_test_docker_environment.api.common'

  cause The `api.common` module was refactored and split into multiple files in v4.0.0, changing the import paths for many classes and functions.
  fix Update your import statements to reflect the new module structure. For example, `from exasol_integration_test_docker_environment.api.common import DockerTestEnvironment` should be changed to `from exasol_integration_test_docker_environment.environment.docker_test_environment import DockerTestEnvironment`.

• exasol_integration_test_docker_environment.lib.api.options.docker_options.DockerVersionNotSupportedError: Docker DB version 'X.Y.Z' is not supported.

  cause You are attempting to use an Exasol Docker DB version that is no longer supported by the ITDE after v5.0.0, often due to Exasol removing older images from Docker Hub.
  fix Specify a currently supported `docker_db_version` in your `DockerTestEnvironment` constructor or CLI command. Valid versions include '2025.1.8' or '8.29.13' (check the official documentation for the latest).

• RuntimeError: Python 3.9.x is not supported. Please use Python 3.10 or newer.

  cause The library requires Python 3.10 or newer, a change introduced in v4.4.0.
  fix Upgrade your Python environment to version 3.10, 3.11, 3.12, 3.13, or 3.14.

• TypeError: Object of type <class 'exasol_integration_test_docker_environment.lib.api.data_model.image_info.ImageInfo'> is not JSON serializable

  cause A bug in serialization for `ImageInfo` (and potentially other data models) was present in versions prior to 6.0.0.
  fix Upgrade to `exasol-integration-test-docker-environment` v6.0.0 or newer to fix serialization issues for internal data structures.

Warnings

• breaking Starting from v6.0.0, the Docker image tag format has changed to support platform-specific builds. This may affect CI/CD pipelines or scripts relying on a specific tag naming convention.
  Fix: Review existing scripts that interact directly with Docker image tags. The ITDE API should handle this transparently, but direct Docker CLI calls may need adjustment.
• breaking Version 5.0.0 removed support for older Exasol Docker DB versions (e.g., those prior to 2025.1.8, 8.29.13, 7.1.30) because Exasol removed them from Docker Hub. Attempting to use these versions will result in a `DockerVersionNotSupportedError`.
  Fix: Update your `docker_db_version` parameter to a currently supported Exasol Docker DB version (e.g., '2025.1.8' or '8.29.13'). Check the ITDE GitHub repository for the latest supported versions.
• breaking Minimum Python version was updated to 3.10 in v4.4.0. Running the library on Python 3.9 or older will lead to compatibility errors or crashes.
  Fix: Upgrade your Python environment to version 3.10 or newer. The library currently supports Python up to 3.14.
• breaking Version 4.0.0 introduced significant API refactorings, specifically splitting `api/common.py` into more granular modules. This changes import paths for core classes and functions like `DockerTestEnvironment` and `spawn_test_environment`.
  Fix: Update your Python import statements. For example, `from exasol_integration_test_docker_environment.api.common import DockerTestEnvironment` should become `from exasol_integration_test_docker_environment.environment.docker_test_environment import DockerTestEnvironment`.
• gotcha Prior to v4.4.1, the deprecated `bucketfs` property returned the wrong HTTP port. If you were using this property and expecting HTTP access, connections would fail.
  Fix: Upgrade to `exasol-integration-test-docker-environment` v4.4.1 or newer. It's recommended to use the `connection_info.bucketfs_port` or similar attributes for accurate port information.

Install

• pip install exasol-integration-test-docker-environment Install latest version

Imports

• DockerTestEnvironment
  wrong:

  from exasol_integration_test_docker_environment.api.common import DockerTestEnvironment

  correct:

  from exasol_integration_test_docker_environment.environment.docker_test_environment import DockerTestEnvironment

  The `api.common` module was refactored and split in v4.0.0; specific classes moved to new paths.
• spawn_test_environment
  wrong:

  from exasol_integration_test_docker_environment.api.common import spawn_test_environment

  correct:

  from exasol_integration_test_docker_environment.lib.api.spawn_test_environment import spawn_test_environment

  The `api.common` module was refactored and split in v4.0.0; specific functions moved to new paths.

Quickstart

This quickstart demonstrates how to use `DockerTestEnvironment` to launch an Exasol database instance in Docker. It automatically pulls the specified Docker image, configures the environment, and provides connection details. The `with` statement ensures the environment is properly shut down afterwards.

from exasol_integration_test_docker_environment.environment.docker_test_environment import DockerTestEnvironment

# Configure with a supported Exasol Docker DB version. (e.g., 2025.1.8, 8.29.13)
# Check the library's GitHub for currently supported versions.
EXASOL_DB_VERSION = "8.34.0" # Or '2025.1.8'

try:
    with DockerTestEnvironment(
        docker_db_version=EXASOL_DB_VERSION,
        name="my_integration_test"
    ) as environment:
        connection_info = environment.get_connection_info()
        print(f"Exasol DB IP: {connection_info.host}")
        print(f"Exasol DB Port: {connection_info.port}")
        print(f"Exasol DB User: {connection_info.user}")
        print(f"Exasol DB Password: {connection_info.password}")
        print(f"Exasol DB Schema: {connection_info.schema}")

        # Your test code goes here, using connection_info to connect to the DB
        print("Exasol test environment is running.")

except Exception as e:
    print(f"Failed to spawn Exasol Docker environment: {e}")