iris-devtester 1.8.1__py3-none-any.whl → 1.9.1__py3-none-any.whl

iris_devtester/containers/iris_container.py

@@ -1,487 +1,319 @@
-"""
-Enhanced IRIS container wrapper.
-
-Extends testcontainers-iris-python with automatic connection management,
-password reset, and better wait strategies.
-"""
-
-import hashlib
 import logging
 import os
-import platform as platform_module
 import subprocess
 import time
-from typing import Any, Optional, TYPE_CHECKING, Union
-
-from iris_devtester.config.models import IRISConfig
-from iris_devtester.connections.manager import get_connection
-from iris_devtester.utils.password_reset import reset_password_if_needed
-from iris_devtester.containers.wait_strategies import IRISReadyWaitStrategy
-from iris_devtester.containers.monitoring import (
-    MonitoringPolicy,
-    configure_monitoring,
-    disable_monitoring,
-)
-from iris_devtester.containers.performance import get_resource_metrics
-
-if TYPE_CHECKING:
-    from iris_devtester.ports.registry import PortRegistry
-    from iris_devtester.containers.models import HealthCheckLevel, ValidationResult
-    from iris_devtester.config.container_config import ContainerConfig
+from typing import Any, Dict, List, Literal, Optional, Tuple, Type, Union
+
+from iris_devtester.config import IRISConfig, discover_config
+from iris_devtester.connections import get_connection
 
 logger = logging.getLogger(__name__)
 
-try:
-    from testcontainers.iris import IRISContainer as BaseIRISContainer
-    HAS_TESTCONTAINERS_IRIS = True
-except ImportError:
-    logger.warning("testcontainers-iris-python not installed.")
-    HAS_TESTCONTAINERS_IRIS = False
 
-    class BaseIRISContainer:
-        def __init__(self, image: str = "", **kwargs):
-            self.image = image
-            self.port = 1972
-        def __enter__(self): return self
-        def __exit__(self, *args): pass
-        def start(self): 
-            logger.info("Mock IRIS container started (test mode)")
-            return self
-        def stop(self, *args, **kwargs): pass
+# Single base class definition to satisfy LSP
+class _IRISMockContainer:
+    def __init__(self, image: str = "", **kwargs):
+        self.image = image
+        self._container = None
+
+    def start(self):
+        return self
+
+    def stop(self, *args, **kwargs):
+        pass
+
+    def get_container_host_ip(self) -> str:
+        return "localhost"
+
+    def get_exposed_port(self, port: int) -> int:
+        return port
+
+    def with_env(self, key: str, value: str):
+        return self
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *args):
+        pass
+
+    def get_container_name(self) -> str:
+        return "iris_db"
+
 
+# Select the base class. We use Any type to bypass strict type check on the class itself.
+IRISBase: Any = _IRISMockContainer
 
+# Check for testcontainers
+HAS_TESTCONTAINERS = False
+try:
+    from testcontainers.iris import IRISContainer as _ActualBase
 
-        def get_wrapped_container(self): return None
-        def with_env(self, key: str, value: str): return self
-        def with_volume_mapping(self, host: str, container: str, mode: str = "rw"): return self
-        def with_bind_ports(self, container: int, host: int): return self
-        def with_name(self, name: str): return self
-        def get_container_host_ip(self): return "localhost"
-        def get_exposed_port(self, port: int): return port
+    IRISBase = _ActualBase
+    HAS_TESTCONTAINERS = True
+except ImportError:
+    pass
 
 
-class IRISContainer(BaseIRISContainer):
-    """Enhanced IRIS container with automatic connection and password reset."""
+class IRISContainer(IRISBase):
+    """
+    Enhanced IRIS container with automatic connection and password management.
+    """
 
     def __init__(
         self,
         image: str = "intersystemsdc/iris-community:latest",
-        port_registry: Optional["PortRegistry"] = None,
-        project_path: Optional[str] = None,
-        preferred_port: Optional[int] = None,
+        username: str = "SuperUser",
+        password: str = "SYS",
+        namespace: str = "USER",
         **kwargs,
     ):
-        if not HAS_TESTCONTAINERS_IRIS:
-            raise ImportError("testcontainers-iris-python not installed")
-
-        # Extract known args for BaseIRISContainer if it's the mock one
-        base_kwargs = {}
-        if not HAS_TESTCONTAINERS_IRIS:
-            base_kwargs = {k: v for k, v in kwargs.items() if k in ["username", "password", "namespace"]}
-        
+        if not HAS_TESTCONTAINERS:
+            logger.warning("testcontainers not installed. Functionality will be limited.")
+
         super().__init__(image=image, **kwargs)
+        self._username = username
+        self._password = password
+        self._namespace = namespace
         self._connection = None
-        self._config = None
         self._callin_enabled = False
+        self._password_preconfigured = False
         self._is_attached = False
-        self._port_registry = port_registry
-        self._port_assignment = None
-        self._preferred_port = preferred_port
-        self._cpf_manager = None
-        self._cpf_merge_path = None
-        self._project_path = project_path or os.getcwd()
-        self._container_name = "iris_container"
-        self._username = kwargs.get("username", "SuperUser")
-        self._password = kwargs.get("password", "SYS")
-        self._namespace = kwargs.get("namespace", "USER")
-
-    def get_assigned_port(self) -> int:
-        """Get the port assigned to this container."""
-        if os.environ.get("IRIS_TEST_MODE"):
-            return self._port_assignment.port if self._port_assignment else 1972
-            
-        if self._port_assignment:
-            return self._port_assignment.port
-        return int(self.get_exposed_port(1972))
-
-    def get_test_namespace(self) -> str:
-        """Generate a unique test namespace."""
-        import uuid
-        ns = f"TEST_{str(uuid.uuid4())[:8].upper()}"
-        self.execute_objectscript(f'Set status = ##class(Config.Namespaces).Create("{ns}",.p)')
-        return ns
+        self._container_name: Optional[str] = kwargs.get("name")
+        self._config: Optional[IRISConfig] = None
 
-    def delete_namespace(self, namespace: str):
-        """Delete a namespace."""
-        self.execute_objectscript(f'Do ##class(Config.Namespaces).Delete("{namespace}")')
-
-    def with_cpf_merge(self, path_or_content: str) -> "IRISContainer":
-        """Configure a CPF merge file for the container."""
-        from .cpf_manager import TempCPFManager
-        
-        if os.path.exists(path_or_content) and os.path.isfile(path_or_content):
-            self._cpf_merge_path = os.path.abspath(path_or_content)
-        else:
-            if self._cpf_manager is None:
-                self._cpf_manager = TempCPFManager()
-            self._cpf_merge_path = self._cpf_manager.create_temp_cpf(path_or_content)
-            
-        container_path = "/usr/irissys/merge.cpf"
-        self.with_env("ISC_CPF_MERGE_FILE", container_path)
-        self.with_volume_mapping(self._cpf_merge_path, container_path, "ro")
-        return self
+        # Standard attributes used by fixtures
+        # IMPORTANT: self.port must remain the INTERNAL container port (1972)
+        # for testcontainers' get_exposed_port() to work correctly.
+        # Use self._mapped_port for the host-side mapped port.
+        self.host = "localhost"
+        self.port = 1972  # Internal container port - DO NOT CHANGE
+        self._mapped_port: Optional[int] = None  # Host-side mapped port
 
-    def start(self):
-        """Start IRIS container with port registry integration."""
-        if self._port_registry:
-            self._port_assignment = self._port_registry.assign_port(
-                project_path=self._project_path, preferred_port=self._preferred_port
-            )
-            assigned_port = self._port_assignment.port
-            if self._config:
-                self._config.port = assigned_port
-
-            self.with_bind_ports(1972, assigned_port)
-            # Ensure assigned_port is set on self for base class
-            self.port = assigned_port
-            project_hash = hashlib.md5(self._project_path.encode()).hexdigest()[:8]
-            container_name = f"iris_{project_hash}_{assigned_port}"
-            self._port_assignment.container_name = container_name
-            self.with_name(container_name)
-            self._container_name = container_name
-
-        try:
-            if HAS_TESTCONTAINERS_IRIS and not os.environ.get("IRIS_TEST_MODE"):
-                result = super().start()
-            else:
-                logger.info("Mock IRIS container started (test mode)")
-                result = self
-        except Exception as e:
-            logger.error(f"Failed to start container: {e}")
-            raise
-
-        # Only wait if we actually have a running container and haven't already waited
-        # testcontainers.iris.IRISContainer already waits for "Enabling logons"
-        if HAS_TESTCONTAINERS_IRIS and not os.environ.get("IRIS_TEST_MODE"):
-            # We skip wait_for_ready() here because super().start() already waited
-            # but we still need to perform the initial password reset hardening
-            config = self.get_config()
-            from iris_devtester.utils.password_reset import reset_password
-            try:
-                reset_password(
-                    container_name=self.get_container_name(), 
-                    username=config.username, 
-                    new_password=config.password, 
-                    hostname=None, 
-                    port=config.port, 
-                    namespace=config.namespace,
-                    timeout=10 # Short timeout for auto-start
-                )
-            except Exception as e:
-                logger.debug(f"Initial password reset failed (non-critical): {e}")
-        
-        return result
-
-        if self._config:
-            self._config.host = self.get_container_host_ip()
-            if self._port_registry:
-                self._config.port = self._port_assignment.port
-            else:
-                self._config.port = int(self.get_exposed_port(self.port or 1972))
-
-        return result
-
-    def stop(self, *args, **kwargs):
-        """Stop IRIS container and release resources."""
-        try:
-            super().stop(*args, **kwargs)
-        finally:
-            if self._port_registry and self._port_assignment:
-                try:
-                    self._port_registry.release_port(self._project_path)
-                except Exception as e:
-                    logger.warning(f"Failed to release port assignment: {e}")
-            if self._cpf_manager:
-                self._cpf_manager.cleanup()
+        # Pre-configuration fields (Feature 001)
+        self._preconfigure_password: Optional[str] = None
+        self._preconfigure_username: Optional[str] = None
 
     @classmethod
-    def community(
-        cls,
-        namespace: str = "USER",
-        username: str = "SuperUser",
-        password: str = "SYS",
-        **kwargs,
-    ) -> "IRISContainer":
-        """Create Community Edition IRIS container."""
-        if "image" not in kwargs:
+    def community(cls, image: Optional[str] = None, **kwargs) -> "IRISContainer":
+        """Create a Community Edition container."""
+        if image is None:
+            import platform as platform_module
+
             if platform_module.machine() == "arm64":
-                kwargs["image"] = "containers.intersystems.com/intersystems/iris-community:2025.1"
+                image = "containers.intersystems.com/intersystems/iris-community:2025.1"
             else:
-                kwargs["image"] = "intersystemsdc/iris-community:latest"
-
-        container = cls(
-            username=username,
-            password=password,
-            namespace=namespace,
-            **kwargs
-        )
+                image = "intersystemsdc/iris-community:latest"
+        return cls(image=image, **kwargs)
 
-        container._config = IRISConfig(
-            host="localhost",
-            port=1972,
-            namespace=namespace,
-            username=username,
-            password=password,
-            container_name=container.get_container_name()
-        )
+    @classmethod
+    def enterprise(cls, license_key: str, image: Optional[str] = None, **kwargs) -> "IRISContainer":
+        """Create an Enterprise Edition container."""
+        if image is None:
+            image = "containers.intersystems.com/intersystems/iris:latest"
+        container = cls(image=image, **kwargs)
         return container
 
-    @classmethod
-    def from_existing(cls, auto_discover: bool = True) -> Optional[IRISConfig]:
-        """Detect existing IRIS instance."""
-        if not auto_discover: return None
-        from iris_devtester.config.auto_discovery import auto_discover_iris
-        config_dict = auto_discover_iris()
-        if config_dict is None: return None
-        return IRISConfig(
-            host=config_dict.get("host", "localhost"),
-            port=config_dict.get("port", 1972),
-            namespace=config_dict.get("namespace", "USER"),
-            username=config_dict.get("username", "_SYSTEM"),
-            password=config_dict.get("password", "SYS"),
-        )
+    def with_name(self, name: str) -> "IRISContainer":
+        """Set the container name."""
+        self._container_name = name
+        if hasattr(self, "with_kwargs"):
+            self.with_kwargs(name=name)
+        return self
 
-    @classmethod
-    def enterprise(
-        cls,
-        license_key: Optional[str] = None,
-        namespace: str = "USER",
-        username: str = "SuperUser",
-        password: str = "SYS",
-        **kwargs,
-    ) -> "IRISContainer":
-        """Create Enterprise Edition IRIS container."""
-        license_key = license_key or os.environ.get("IRIS_LICENSE_KEY")
-        if license_key is None:
-            raise ValueError("Enterprise Edition requires license key")
-
-        if platform_module.machine() == "arm64":
-            image = "containers.intersystems.com/intersystems/iris-arm64:2025.1"
-        else:
-            image = "intersystemsdc/iris:latest"
-
-        container = cls(
-            image=image,
-            username=username,
-            password=password,
-            namespace=namespace,
-            **kwargs
-        )
-        container.with_env("ISC_LICENSE_KEY", license_key)
-        container._config = IRISConfig(
-            host="localhost",
-            port=1972,
-            namespace=namespace,
-            username=username,
-            password=password,
-            container_name=container.get_container_name()
-        )
-        return container
+    def get_container_name(self) -> str:
+        """Get the actual container name."""
+        # Priority 1: Explicit name set by with_name()
+        if self._container_name:
+            return self._container_name
 
-    @classmethod
-    def attach(cls, container_name: str) -> "IRISContainer":
-        """Attach to existing IRIS container."""
-        import subprocess
-        check_cmd = ["docker", "ps", "--filter", f"name={container_name}", "--format", "{{.Names}}"]
-        result = subprocess.run(check_cmd, capture_output=True, text=True, timeout=10)
-        if container_name not in result.stdout:
-            raise ValueError(f"Container '{container_name}' not found")
-
-        port_cmd = ["docker", "port", container_name, "1972"]
-        result = subprocess.run(port_cmd, capture_output=True, text=True, timeout=10)
-        exposed_port = int(result.stdout.strip().split(":")[-1]) if result.returncode == 0 and result.stdout.strip() else 1972
-
-        instance = cls.__new__(cls)
-        instance._connection = None
-        instance._callin_enabled = False
-        instance._is_attached = True
-        instance._config = IRISConfig(
-            host="localhost", 
-            port=exposed_port, 
-            namespace="USER", 
-            username="SuperUser", 
-            password="SYS", 
-            container_name=container_name
-        )
-        instance._container_name = container_name
-        return instance
+        # Priority 2: Get from actual Docker container (after start)
+        try:
+            if hasattr(self, "_container") and self._container is not None:
+                return str(self._container.name)
+        except Exception:
+            pass
 
-    def get_connection(self, enable_callin: bool = True) -> Any:
-        """Get database connection."""
-        if self._connection is not None: return self._connection
-        
+        # Priority 3: Try parent class method (testcontainers might have one)
+        try:
+            parent_name = super().get_container_name()
+            if parent_name and parent_name != "iris_db":
+                return str(parent_name)
+        except Exception:
+            pass
+
+        # Fallback - but this is problematic if container isn't started yet
+        return "iris_db"
+
+    def execute_objectscript(self, script: str, namespace: Optional[str] = None) -> str:
+        """Execute ObjectScript in the container."""
         container_name = self.get_container_name()
-        
-        if enable_callin and not self._callin_enabled:
-            self.enable_callin_service()
+        ns = namespace or self._namespace
 
-        from iris_devtester.utils.unexpire_passwords import unexpire_all_passwords
-        unexpire_all_passwords(container_name)
+        cmd = ["docker", "exec", "-i", container_name, "iris", "session", "IRIS", "-U", ns]
 
-        from iris_devtester.utils.password_reset import reset_password
-        config = self.get_config()
-        
-        reset_password(
-            container_name=container_name,
-            username=config.username,
-            new_password=config.password,
-            hostname=config.host,
-            port=config.port,
-            namespace=config.namespace,
+        result = subprocess.run(
+            cmd, input=f"{script}\nHalt\n".encode("utf-8"), capture_output=True, timeout=30
         )
 
-        self._connection = get_connection(config)
-        return self._connection
+        if result.returncode != 0:
+            raise RuntimeError(f"OS failed: {result.stderr.decode()}")
 
-    def get_config(self) -> IRISConfig:
-        """Get connection configuration."""
-        if self._config is None: self._config = IRISConfig()
-        try:
-            if HAS_TESTCONTAINERS_IRIS and hasattr(self, "get_container_host_ip"):
-                self._config = IRISConfig(
-                    host=self.get_container_host_ip(),
-                    port=int(self.get_exposed_port(1972)),
-                    namespace=self._config.namespace,
-                    username=self._config.username,
-                    password=self._config.password,
-                    container_name=self.get_container_name()
-                )
-            elif self._is_attached:
-                self._config.container_name = self.get_container_name()
-        except Exception as e:
-            logger.debug(f"Could not update config: {e}")
-        return self._config
+        return result.stdout.decode("utf-8", errors="replace")
 
-    def wait_for_ready(self, timeout: int = 60) -> bool:
-        """Wait for IRIS to be fully ready."""
-        config = self.get_config()
-        strategy = IRISReadyWaitStrategy(port=config.port, timeout=timeout)
-        try:
-            ready = strategy.wait_until_ready(
-                config.host, 
-                config.port, 
-                timeout, 
-                container_name=self.get_container_name()
-            )
-            if not ready: return False
-            
-            from iris_devtester.utils.password_reset import reset_password
-            # Convert result to bool to satisfy type checker
-            result = reset_password(
-                container_name=self.get_container_name(), 
-                username=config.username, 
-                new_password=config.password, 
-                hostname=None, 
-                port=config.port, 
-                namespace=config.namespace
-            )
-            if hasattr(result, "success"):
-                return bool(getattr(result, "success"))
-            return bool(result[0])
-        except (TimeoutError, IndexError, TypeError): return False
-
-    def reset_password(self, username: str = "_SYSTEM", new_password: str = "SYS") -> bool:
-        """Reset user password."""
-        from iris_devtester.utils.password_reset import reset_password
-        config = self.get_config()
-        result = reset_password(
-            container_name=self.get_container_name(), 
-            username=username, 
-            new_password=new_password, 
-            hostname=config.host, 
-            port=config.port, 
-            namespace=config.namespace
-        )
-        # Handle both Tuple[bool, str] and PasswordResetResult
-        if hasattr(result, "success"):
-            success = bool(getattr(result, "success"))
-        elif isinstance(result, (list, tuple)):
-            success = bool(result[0])
-        else:
-            success = False
-            
-        if success: config.password = new_password
-        return success
+    def enable_callin_service(self) -> bool:
+        """Enable the CallIn service (required for DBAPI)."""
+        if self._callin_enabled:
+            return True
 
-    def get_container_name(self) -> str:
-        """Get current container name."""
-        if hasattr(self, "_is_attached") and self._is_attached: return self._container_name
-        if HAS_TESTCONTAINERS_IRIS:
-            try:
-                wrapped = self.get_wrapped_container()
-                if wrapped and hasattr(wrapped, "name"):
-                    return str(wrapped.name)
-            except Exception: pass
-        return "iris_container"
-
-    def get_project_path(self) -> Optional[str]:
-        """Get project path if port registry is used."""
-        if self._port_registry:
-            return self._project_path
-        return None
+        from iris_devtester.utils.enable_callin import enable_callin_service
 
-    def enable_callin_service(self) -> bool:
-        """Enable CallIn service."""
-        if self._callin_enabled: return True
-        try:
-            container_name = self.get_container_name()
-            script = 'Do ##class(Security.Services).Get("%Service_CallIn",.p) Set p("Enabled")=1,p("AutheEnabled")=48 Do ##class(Security.Services).Modify("%Service_CallIn",.p) Write "OK" Halt'
-            cmd = ["docker", "exec", "-u", "root", container_name, "sh", "-c", f'iris session IRIS -U %SYS << "EOF"\n{script}\nEOF']
-            result = subprocess.run(cmd, capture_output=True, text=True, timeout=10)
-            if result.returncode == 0 and "OK" in result.stdout:
-                self._callin_enabled = True
-                return True
+        success, msg = enable_callin_service(self.get_container_name())
+        if success:
+            self._callin_enabled = True
+            return True
+        else:
+            logger.error(f"Failed to enable CallIn: {msg}")
             return False
-        except Exception: return False
 
     def check_callin_enabled(self) -> bool:
         """Check if CallIn is enabled."""
         try:
-            script = 'Do ##class(Security.Services).Get("%Service_CallIn",.s) Write s.Enabled'
-            cmd = ["docker", "exec", self.get_container_name(), "iris", "session", "IRIS", "-U", "%SYS", script]
-            result = subprocess.run(cmd, capture_output=True, text=True, timeout=5)
-            is_enabled = result.returncode == 0 and "1" in result.stdout
-            if is_enabled: self._callin_enabled = True
+            script = 'Do ##class(Security.Services).Get("%Service_CallIn",.p) Write "ENABLED:",p("Enabled")'
+            output = self.execute_objectscript(script, namespace="%SYS")
+            is_enabled = "ENABLED:1" in output
+            if is_enabled:
+                self._callin_enabled = True
             return is_enabled
-        except Exception: return False
-
-    def execute_objectscript(self, code: str, namespace: Optional[str] = None) -> str:
-        """Execute ObjectScript code."""
-        ns = namespace or self.get_config().namespace
-        if "Halt" not in code: code += "\nHalt"
-        cmd = ["docker", "exec", self.get_container_name(), "sh", "-c", f'iris session IRIS -U {ns} << "EOF"\n{code}\nEOF']
-        result = subprocess.run(cmd, capture_output=True, text=True, timeout=30)
-        if result.returncode != 0: raise RuntimeError(f"OS failed: {result.stderr}")
-        return result.stdout
-
-    def validate(self, level: Any = None) -> Any:
-        """Validate container health."""
-        from iris_devtester.containers.models import HealthCheckLevel
-        from iris_devtester.containers.validation import validate_container
-        return validate_container(container_name=self.get_container_name(), level=level or HealthCheckLevel.STANDARD, docker_client=None)
-
-    def assert_healthy(self, level: Any = None):
-        """Raise if not healthy."""
-        res = self.validate(level=level)
-        if not res.success: raise RuntimeError(res.format_message())
+        except:
+            return False
 
-    @classmethod
-    def from_config(cls, config: Any) -> "IRISContainer":
-        """Create from ContainerConfig."""
-        image = config.get_image_name()
-        if getattr(config, "edition", "community") == "community":
-            container = cls.community(namespace=getattr(config, "namespace", "USER"), username=getattr(config, "username", "SuperUser"), password=getattr(config, "password", "SYS"), image=image)
-        else:
-            container = cls.enterprise(license_key=getattr(config, "license_key", None), namespace=getattr(config, "namespace", "USER"), username=getattr(config, "username", "SuperUser"), password=getattr(config, "password", "SYS"), image=image)
-        if getattr(config, "cpf_merge", None): container.with_cpf_merge(config.cpf_merge)
-        return container
+    def get_test_namespace(self, prefix: str = "TEST") -> str:
+        """Generate a unique test namespace with its own database."""
+        import uuid
+
+        ns = f"{prefix}_{str(uuid.uuid4())[:8].upper()}"
+        db_dir = f"/usr/irissys/mgr/db_{ns.lower()}"
+
+        script = f"""
+ Set ns="{ns}"
+ Set dbDir="{db_dir}"
+ If '##class(%File).DirectoryExists(dbDir) Do ##class(%File).CreateDirectoryChain(dbDir)
+ Set db=##class(SYS.Database).%New() Set db.Directory=dbDir Do db.%Save()
+ Do ##class(Config.Databases).Create(ns,dbDir)
+ Set p("Globals")=ns,p("Routines")=ns Do ##class(Config.Namespaces).Create(ns,.p)
+ Write "SUCCESS" Halt
+ """
+        self.execute_objectscript(script, namespace="%SYS")
+        return ns
+
+    def delete_namespace(self, namespace: str):
+        """Delete a namespace and its associated database files cleanly."""
+        script = f"""
+ Set ns="{namespace}"
+ Do ##class(Config.Namespaces).Delete(ns)
+ If ##class(Config.Databases).Get(ns,.p) {{
+     Set dir = p("Directory")
+     Do ##class(SYS.Database).DismountDatabase(dir)
+     Do ##class(Config.Databases).Delete(ns)
+     Do ##class(%File).RemoveDirectoryTree(dir)
+ }}
+ Write "SUCCESS" Halt
+ """
+        self.execute_objectscript(script, namespace="%SYS")
+
+    def get_config(self) -> IRISConfig:
+        """Get connection configuration."""
+        if self._config is None:
+            self._config = IRISConfig(
+                username=self._username,
+                password=self._password,
+                namespace=self._namespace,
+                container_name=self.get_container_name(),
+            )
+        config = self._config
+        try:
+            # Get host and mapped port from testcontainers
+            # IMPORTANT: self.port must remain 1972 (internal port) for get_exposed_port() to work
+            self.host = self.get_container_host_ip()
+            self._mapped_port = int(self.get_exposed_port(1972))  # Use internal port to get mapping
+            config.host = self.host
+            config.port = (
+                self._mapped_port
+            )  # Config uses the host-mapped port for connections
+        except Exception:
+            pass
+        return config
+
+    def get_mapped_port(self, internal_port: int = 1972) -> int:
+        """Get the host-side mapped port for a given internal container port.
+
+        This is a convenience wrapper around get_exposed_port() that ensures
+        we always pass the internal port (not the host port).
+
+        Args:
+            internal_port: The port inside the container (default: 1972 for IRIS superserver)
+
+        Returns:
+            The host-side port that maps to the internal port
+        """
+        if self._mapped_port is not None and internal_port == 1972:
+            return self._mapped_port
+        return int(self.get_exposed_port(internal_port))
+
+    def get_connection(self, enable_callin: bool = True) -> Any:
+        """Get database connection."""
+        if self._connection is not None:
+            return self._connection
+
+        if enable_callin:
+            self.enable_callin_service()
+
+        from iris_devtester.utils.password import unexpire_all_passwords
+
+        unexpire_all_passwords(self.get_container_name())
+
+        config = self.get_config()
+        from iris_devtester.connections.connection import get_connection as get_modern_connection
+
+        self._connection = get_modern_connection(config)
+        return self._connection
+
+    def with_preconfigured_password(self, password: str) -> "IRISContainer":
+        """Set password for pre-configuration."""
+        if not password:
+            raise ValueError("Password cannot be empty")
+        self._preconfigure_password = password
+        self._password = password
+        return self
+
+    def with_credentials(self, username: str, password: str) -> "IRISContainer":
+        """Set credentials for pre-configuration."""
+        if not username:
+            raise ValueError("Username cannot be empty")
+        if not password:
+            raise ValueError("Password cannot be empty")
+        self._preconfigure_username = username
+        self._preconfigure_password = password
+        self._username = username
+        self._password = password
+        return self
+
+    def start(self) -> "IRISContainer":
+        """Start container with pre-config support."""
+        if self._preconfigure_password:
+            self.with_env("IRIS_PASSWORD", self._preconfigure_password)
+        if self._preconfigure_username:
+            self.with_env("IRIS_USERNAME", self._preconfigure_username)
+
+        super().start()
+        # Ensure host/port are updated after start
+        self.get_config()
+        self._password_preconfigured = True
+        return self
+
+    def wait_for_ready(self, timeout: int = 60) -> bool:
+        """Wait for IRIS to be ready."""
+        # Simple wait for prototype
+        time.sleep(15)
+        return True