feat: implement tag-based selective container startup for behave tests

Author: HosseinNejatiJavaremi

features/atomic_transactions.feature

@@ -1,3 +1,4 @@
+@needs-postgres
 Feature: SQLAlchemy Atomic Transactions
 
   Background:

features/elastic_adapter.feature

@@ -1,4 +1,5 @@
 # features/elasticsearch.feature
+@needs-elasticsearch
 Feature: Elasticsearch Operations Testing
   As a developer
   I want to test Elasticsearch operations using the adapter pattern

features/environment.py

@@ -9,7 +9,7 @@
 import logging
 import uuid
 
-from behave.model import Scenario
+from behave.model import Scenario, Feature
 from behave.runner import Context
 from features.scenario_context_pool_manager import ScenarioContextPoolManager
 from pydantic_settings import SettingsConfigDict
@@ -63,9 +63,45 @@ def before_all(context: Context):
     # Create the scenario context pool manager
     context.scenario_context_pool = ScenarioContextPoolManager()
 
-    # Initialize and start all test containers
+    # Initialize container manager
     context.test_containers = ContainerManager
-    context.test_containers.start_all()
+
+    # Collect feature-level tags from all features being executed
+    all_tags: set[str] = set()
+    if hasattr(context, "features") and context.features:
+        for feature in context.features:
+            # Get feature-level tags - convert Tag objects to strings
+            if hasattr(feature, "tags") and feature.tags:
+                feature_tags = [str(tag) for tag in feature.tags]
+                all_tags.update(feature_tags)
+                context.logger.debug(f"Feature '{feature.name}' has tags: {feature_tags}")
+
+    # Extract required containers from tags
+    required_containers = ContainerManager.extract_containers_from_tags(list(all_tags))
+
+    if required_containers:
+        context.logger.info(f"Detected required containers from tags: {sorted(required_containers)}")
+        ContainerManager.start_containers(list(required_containers))
+    else:
+        context.logger.info("No container tags detected, no containers will be started")
+
+
+def before_feature(context: Context, feature: Feature):
+    """Setup performed before each feature runs.
+
+    This is a fallback to ensure containers are started if they weren't started in before_all().
+    """
+    # Extract feature-level tags - convert Tag objects to strings
+    if hasattr(feature, "tags") and feature.tags:
+        feature_tags = [str(tag) for tag in feature.tags]
+
+        if feature_tags:
+            # Extract required containers from tags
+            required_containers = ContainerManager.extract_containers_from_tags(feature_tags)
+
+            if required_containers:
+                # Start containers if not already started (start_containers handles this)
+                ContainerManager.start_containers(list(required_containers))
 
 
 def before_scenario(context: Context, scenario: Scenario):

features/kafka_adapters.feature

@@ -1,4 +1,5 @@
 # features/kafka_operations.feature
+@needs-kafka
 Feature: Kafka Adapter Operations Testing
   As a developer
   I want to test Kafka adapter operations

features/keycloak_adapter.feature

@@ -1,4 +1,5 @@
 # features/keycloak_auth.feature
+@needs-keycloak
 Feature: Keycloak Authentication Testing
   As a developer
   I want to test Keycloak authentication operations

features/minio_adapter.feature

@@ -1,4 +1,5 @@
 # features/minio_operations.feature
+@needs-minio
 Feature: MinIO Operations Testing
   As a developer
   I want to test MinIO storage operations

features/test_containers.py

@@ -17,13 +17,24 @@
 
 logger = logging.getLogger(__name__)
 
+# Mapping of feature tags to container names
+TAG_CONTAINER_MAP: dict[str, str] = {
+    "needs-postgres": "postgres",
+    "needs-kafka": "kafka",
+    "needs-elasticsearch": "elasticsearch",
+    "needs-minio": "minio",
+    "needs-keycloak": "keycloak",
+    "needs-redis": "redis",
+}
+
 
 class ContainerManager:
     """Registry for managing all test containers."""
 
     _containers = {}
     _container_instances = {}
     _started = False
+    _started_containers: set[str] = set()
 
     @classmethod
     def register(cls, name: str):
@@ -36,18 +47,29 @@ def decorator(container_class):
 
     @classmethod
     def get_container(cls, name: str, **kwargs):
-        """Get a container instance by name."""
+        """Get a container instance by name.
+
+        If the container is not started, it will be started lazily.
+        """
         if name not in cls._containers:
             raise KeyError(f"Container '{name}' not found. Available: {list(cls._containers.keys())}")
 
         # Return stored instance if available (Singleton pattern ensures same instance)
         if name in cls._container_instances:
-            return cls._container_instances[name]
+            instance = cls._container_instances[name]
+            # Start container if not already running (lazy startup)
+            if name not in cls._started_containers:
+                instance.start()
+                cls._started_containers.add(name)
+            return instance
 
         # Create new instance if not stored yet
         container_class = cls._containers[name]
         instance = container_class(**kwargs)
         cls._container_instances[name] = instance
+        # Start container lazily
+        instance.start()
+        cls._started_containers.add(name)
         return instance
 
     @classmethod
@@ -61,21 +83,72 @@ def start_all(cls):
             container = container_class()
             cls._container_instances[name] = container
             container.start()
+            cls._started_containers.add(name)
 
         cls._started = True
         logger.info("All test containers started")
 
+    @classmethod
+    def start_containers(cls, container_names: list[str]):
+        """Start specific containers by name.
+
+        Args:
+            container_names: List of container names to start
+        """
+        for name in container_names:
+            if name not in cls._containers:
+                logger.warning(f"Container '{name}' not found. Available: {list(cls._containers.keys())}")
+                continue
+
+            if name in cls._started_containers:
+                logger.debug(f"Container '{name}' already started, skipping")
+                continue
+
+            logger.info(f"Starting {name} container...")
+            # get_container will start the container and add it to _started_containers
+            cls.get_container(name)
+
+        logger.info(f"Started containers: {sorted(cls._started_containers)}")
+
+    @classmethod
+    def extract_containers_from_tags(cls, tags: list[str]) -> set[str]:
+        """Extract container names from feature/scenario tags.
+
+        Args:
+            tags: List of tag strings (e.g., ["needs-postgres", "needs-kafka"])
+
+        Returns:
+            Set of container names that should be started
+        """
+        containers: set[str] = set()
+        for tag in tags:
+            # Remove @ prefix if present
+            tag_name = tag.lstrip("@")
+            if tag_name in TAG_CONTAINER_MAP:
+                container_name = TAG_CONTAINER_MAP[tag_name]
+                containers.add(container_name)
+                logger.debug(f"Tag '{tag}' maps to container '{container_name}'")
+            else:
+                # Only log warning for tags that look like container tags but aren't mapped
+                if tag_name.startswith("needs-"):
+                    logger.warning(f"Unknown container tag '{tag}'. Available tags: {list(TAG_CONTAINER_MAP.keys())}")
+
+        return containers
+
     @classmethod
     def stop_all(cls):
-        """Stop all registered containers."""
-        if not cls._started:
+        """Stop all started containers."""
+        if not cls._started_containers:
             return
 
-        for name, instance in cls._container_instances.items():
-            logger.info(f"Stopping {name} container...")
-            instance.stop()
+        for name in list(cls._started_containers):
+            if name in cls._container_instances:
+                logger.info(f"Stopping {name} container...")
+                instance = cls._container_instances[name]
+                instance.stop()
 
         cls._container_instances.clear()
+        cls._started_containers.clear()
         cls._started = False
         logger.info("All test containers stopped")
 
@@ -85,6 +158,7 @@ def reset(cls):
         cls.stop_all()
         cls._containers.clear()
         cls._container_instances.clear()
+        cls._started_containers.clear()
         cls._started = False
 
     @classmethod