testcontainers-aws 0.1.0__py3-none-any.whl

testcontainers_aws/__init__.py

@@ -0,0 +1,12 @@
+"""
+testcontainers-aws: Simplified AWS service testing with Testcontainers
+
+Provides easy-to-use abstractions for testing AWS services using Testcontainers
+and LocalStack. Automatically handles container lifecycle, service initialization,
+and boto3 client configuration.
+"""
+
+from testcontainers_aws.core import AWSTestEnvironment
+
+__version__ = "0.1.0"
+__all__ = ["AWSTestEnvironment"]

testcontainers_aws/core.py

@@ -0,0 +1,261 @@
+"""Core AWS test environment orchestration."""
+
+from typing import Dict, List, Optional, Any
+import boto3
+from testcontainers.localstack import LocalStackContainer
+
+from testcontainers_aws.services.s3 import S3ServiceManager
+from testcontainers_aws.services.dynamodb import DynamoDBServiceManager
+from testcontainers_aws.services.sqs import SQSServiceManager
+from testcontainers_aws.services.kinesis import KinesisServiceManager
+from testcontainers_aws.services.lambda_service import LambdaServiceManager
+from testcontainers_aws.services.sns import SNSServiceManager
+
+
+class AWSTestEnvironment:
+    """
+    Orchestrates AWS services for testing using LocalStack.
+
+    Provides a unified interface to spin up and configure multiple AWS services
+    in a single container, with automatic boto3 client configuration and
+    helper methods for common testing operations.
+
+    Example:
+        ```python
+        with AWSTestEnvironment(services=['s3', 'dynamodb']) as aws:
+            s3 = aws.get_s3_client()
+            dynamodb = aws.get_dynamodb_client()
+
+            # Use clients for testing
+            s3.create_bucket(Bucket='test-bucket')
+        ```
+    """
+
+    # Map service names to LocalStack service strings
+    SERVICE_MAP = {
+        's3': 's3',
+        'dynamodb': 'dynamodb',
+        'sqs': 'sqs',
+        'sns': 'sns',
+        'kinesis': 'kinesis',
+        'lambda': 'lambda',
+        'logs': 'logs',
+        'cloudformation': 'cloudformation',
+        'iam': 'iam',
+        'sts': 'sts',
+        'ssm': 'ssm',
+        'secretsmanager': 'secretsmanager',
+    }
+
+    def __init__(
+        self,
+        services: Optional[List[str]] = None,
+        init_config: Optional[Dict[str, Any]] = None,
+        image_tag: str = "latest",
+    ):
+        """
+        Initialize AWS test environment.
+
+        Args:
+            services: List of AWS services to enable (e.g., ['s3', 'dynamodb']).
+                     If None, all common services are enabled.
+            init_config: Configuration for initializing resources (buckets, tables, etc.)
+            image_tag: LocalStack Docker image tag (default: 'latest')
+        """
+        self.services = services or ['s3', 'dynamodb', 'sqs', 'kinesis']
+        self.init_config = init_config or {}
+        self.image_tag = image_tag
+
+        self._container: Optional[LocalStackContainer] = None
+        self._clients: Dict[str, Any] = {}
+        self._service_managers: Dict[str, Any] = {}
+
+    def __enter__(self) -> 'AWSTestEnvironment':
+        """Start the container and initialize services."""
+        self.start()
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        """Stop the container and cleanup."""
+        self.stop()
+
+    def start(self) -> None:
+        """Start LocalStack container and initialize configured services."""
+        # Convert service names to LocalStack service strings
+        localstack_services = [self.SERVICE_MAP.get(s, s) for s in self.services]
+
+        # Create and start LocalStack container
+        self._container = LocalStackContainer(
+            image=f"localstack/localstack:{self.image_tag}"
+        )
+
+        # Set services to enable
+        for service in localstack_services:
+            self._container = self._container.with_services(service)
+
+        self._container.start()
+
+        # Initialize service managers
+        self._init_service_managers()
+
+        # Run initialization tasks
+        self._initialize_resources()
+
+    def stop(self) -> None:
+        """Stop the LocalStack container."""
+        if self._container:
+            self._container.stop()
+            self._container = None
+            self._clients.clear()
+            self._service_managers.clear()
+
+    def _init_service_managers(self) -> None:
+        """Initialize service manager instances."""
+        if 's3' in self.services:
+            self._service_managers['s3'] = S3ServiceManager(self)
+
+        if 'dynamodb' in self.services:
+            self._service_managers['dynamodb'] = DynamoDBServiceManager(self)
+
+        if 'sqs' in self.services:
+            self._service_managers['sqs'] = SQSServiceManager(self)
+
+        if 'kinesis' in self.services:
+            self._service_managers['kinesis'] = KinesisServiceManager(self)
+
+        if 'lambda' in self.services:
+            self._service_managers['lambda'] = LambdaServiceManager(self)
+
+        if 'sns' in self.services:
+            self._service_managers['sns'] = SNSServiceManager(self)
+
+    def _initialize_resources(self) -> None:
+        """Initialize AWS resources based on init_config."""
+        # Initialize S3 buckets
+        if 's3_buckets' in self.init_config and 's3' in self._service_managers:
+            for bucket in self.init_config['s3_buckets']:
+                if isinstance(bucket, str):
+                    self._service_managers['s3'].create_bucket(bucket)
+                elif isinstance(bucket, dict):
+                    self._service_managers['s3'].create_bucket(**bucket)
+
+        # Initialize DynamoDB tables
+        if 'dynamodb_tables' in self.init_config and 'dynamodb' in self._service_managers:
+            for table in self.init_config['dynamodb_tables']:
+                self._service_managers['dynamodb'].create_table(**table)
+
+        # Initialize SQS queues
+        if 'sqs_queues' in self.init_config and 'sqs' in self._service_managers:
+            for queue in self.init_config['sqs_queues']:
+                if isinstance(queue, str):
+                    self._service_managers['sqs'].create_queue(queue)
+                elif isinstance(queue, dict):
+                    self._service_managers['sqs'].create_queue(**queue)
+
+        # Initialize Kinesis streams
+        if 'kinesis_streams' in self.init_config and 'kinesis' in self._service_managers:
+            for stream in self.init_config['kinesis_streams']:
+                if isinstance(stream, str):
+                    self._service_managers['kinesis'].create_stream(stream)
+                elif isinstance(stream, dict):
+                    self._service_managers['kinesis'].create_stream(**stream)
+
+        # Initialize SNS topics
+        if 'sns_topics' in self.init_config and 'sns' in self._service_managers:
+            for topic in self.init_config['sns_topics']:
+                if isinstance(topic, str):
+                    self._service_managers['sns'].create_topic(topic)
+                elif isinstance(topic, dict):
+                    self._service_managers['sns'].create_topic(**topic)
+
+        # Initialize Lambda functions
+        if 'lambda_functions' in self.init_config and 'lambda' in self._service_managers:
+            for function in self.init_config['lambda_functions']:
+                self._service_managers['lambda'].create_function(**function)
+
+    def get_client(self, service_name: str) -> Any:
+        """
+        Get a boto3 client for the specified AWS service.
+
+        Args:
+            service_name: AWS service name (e.g., 's3', 'dynamodb')
+
+        Returns:
+            Configured boto3 client for the service
+        """
+        if service_name not in self._clients:
+            if not self._container:
+                raise RuntimeError("Container not started. Use 'with' statement or call start().")
+
+            endpoint_url = self._container.get_url()
+
+            self._clients[service_name] = boto3.client(
+                service_name,
+                endpoint_url=endpoint_url,
+                aws_access_key_id='test',
+                aws_secret_access_key='test',
+                region_name='us-east-1',
+            )
+
+        return self._clients[service_name]
+
+    def get_s3_client(self):
+        """Get pre-configured S3 client."""
+        return self.get_client('s3')
+
+    def get_dynamodb_client(self):
+        """Get pre-configured DynamoDB client."""
+        return self.get_client('dynamodb')
+
+    def get_sqs_client(self):
+        """Get pre-configured SQS client."""
+        return self.get_client('sqs')
+
+    def get_kinesis_client(self):
+        """Get pre-configured Kinesis client."""
+        return self.get_client('kinesis')
+
+    def get_sns_client(self):
+        """Get pre-configured SNS client."""
+        return self.get_client('sns')
+
+    def get_lambda_client(self):
+        """Get pre-configured Lambda client."""
+        return self.get_client('lambda')
+
+    @property
+    def s3(self):
+        """Access S3 service manager with helper methods."""
+        return self._service_managers.get('s3')
+
+    @property
+    def dynamodb(self):
+        """Access DynamoDB service manager with helper methods."""
+        return self._service_managers.get('dynamodb')
+
+    @property
+    def sqs(self):
+        """Access SQS service manager with helper methods."""
+        return self._service_managers.get('sqs')
+
+    @property
+    def kinesis(self):
+        """Access Kinesis service manager with helper methods."""
+        return self._service_managers.get('kinesis')
+
+    @property
+    def lambda_(self):
+        """Access Lambda service manager with helper methods."""
+        return self._service_managers.get('lambda')
+
+    @property
+    def sns(self):
+        """Access SNS service manager with helper methods."""
+        return self._service_managers.get('sns')
+
+    @property
+    def endpoint_url(self) -> str:
+        """Get the LocalStack endpoint URL."""
+        if not self._container:
+            raise RuntimeError("Container not started")
+        return self._container.get_url()

testcontainers_aws/fixtures.py

@@ -0,0 +1,291 @@
+"""Pytest fixtures for AWS testing with testcontainers."""
+
+import pytest
+from testcontainers_aws.core import AWSTestEnvironment
+
+
+@pytest.fixture(scope='session')
+def aws_environment():
+    """
+    Session-scoped AWS test environment with common services.
+
+    Provides S3, DynamoDB, SQS, Kinesis, Lambda, and SNS services. The container is
+    shared across all tests in the session for performance.
+
+    Yields:
+        AWSTestEnvironment: Configured AWS environment
+    """
+    with AWSTestEnvironment(services=['s3', 'dynamodb', 'sqs', 'kinesis', 'lambda', 'sns']) as aws:
+        yield aws
+
+
+@pytest.fixture(scope='function')
+def aws_environment_function():
+    """
+    Function-scoped AWS test environment with common services.
+
+    Provides S3, DynamoDB, SQS, Kinesis, Lambda, and SNS services. A fresh container
+    is created for each test function for complete isolation.
+
+    Yields:
+        AWSTestEnvironment: Configured AWS environment
+    """
+    with AWSTestEnvironment(services=['s3', 'dynamodb', 'sqs', 'kinesis', 'lambda', 'sns']) as aws:
+        yield aws
+
+
+@pytest.fixture(scope='session')
+def s3_client(aws_environment):
+    """
+    Session-scoped S3 client.
+
+    Args:
+        aws_environment: AWS environment fixture
+
+    Returns:
+        boto3 S3 client configured for LocalStack
+    """
+    return aws_environment.get_s3_client()
+
+
+@pytest.fixture(scope='session')
+def dynamodb_client(aws_environment):
+    """
+    Session-scoped DynamoDB client.
+
+    Args:
+        aws_environment: AWS environment fixture
+
+    Returns:
+        boto3 DynamoDB client configured for LocalStack
+    """
+    return aws_environment.get_dynamodb_client()
+
+
+@pytest.fixture(scope='session')
+def sqs_client(aws_environment):
+    """
+    Session-scoped SQS client.
+
+    Args:
+        aws_environment: AWS environment fixture
+
+    Returns:
+        boto3 SQS client configured for LocalStack
+    """
+    return aws_environment.get_sqs_client()
+
+
+@pytest.fixture(scope='session')
+def kinesis_client(aws_environment):
+    """
+    Session-scoped Kinesis client.
+
+    Args:
+        aws_environment: AWS environment fixture
+
+    Returns:
+        boto3 Kinesis client configured for LocalStack
+    """
+    return aws_environment.get_kinesis_client()
+
+
+@pytest.fixture(scope='session')
+def lambda_client(aws_environment):
+    """
+    Session-scoped Lambda client.
+
+    Args:
+        aws_environment: AWS environment fixture
+
+    Returns:
+        boto3 Lambda client configured for LocalStack
+    """
+    return aws_environment.get_lambda_client()
+
+
+@pytest.fixture(scope='session')
+def sns_client(aws_environment):
+    """
+    Session-scoped SNS client.
+
+    Args:
+        aws_environment: AWS environment fixture
+
+    Returns:
+        boto3 SNS client configured for LocalStack
+    """
+    return aws_environment.get_sns_client()
+
+
+@pytest.fixture
+def s3_bucket(aws_environment):
+    """
+    Function-scoped S3 bucket that's automatically cleaned up.
+
+    Creates a test bucket and removes it after the test completes.
+
+    Args:
+        aws_environment: AWS environment fixture
+
+    Yields:
+        str: Bucket name
+    """
+    bucket_name = 'test-bucket'
+    aws_environment.s3.create_bucket(bucket_name)
+
+    yield bucket_name
+
+    # Cleanup
+    try:
+        aws_environment.s3.delete_bucket(bucket_name, force=True)
+    except Exception:
+        pass  # Bucket might already be deleted
+
+
+@pytest.fixture
+def dynamodb_table(aws_environment):
+    """
+    Function-scoped DynamoDB table that's automatically cleaned up.
+
+    Creates a test table with a simple schema and removes it after the test.
+
+    Args:
+        aws_environment: AWS environment fixture
+
+    Yields:
+        str: Table name
+    """
+    table_name = 'test-table'
+    aws_environment.dynamodb.create_table(
+        name=table_name,
+        key_schema=[
+            {'AttributeName': 'id', 'KeyType': 'HASH'}
+        ],
+        attribute_definitions=[
+            {'AttributeName': 'id', 'AttributeType': 'S'}
+        ]
+    )
+
+    yield table_name
+
+    # Cleanup
+    try:
+        aws_environment.dynamodb.delete_table(table_name)
+    except Exception:
+        pass
+
+
+@pytest.fixture
+def sqs_queue(aws_environment):
+    """
+    Function-scoped SQS queue that's automatically cleaned up.
+
+    Creates a test queue and removes it after the test completes.
+
+    Args:
+        aws_environment: AWS environment fixture
+
+    Yields:
+        str: Queue URL
+    """
+    queue_response = aws_environment.sqs.create_queue('test-queue')
+    queue_url = queue_response['QueueUrl']
+
+    yield queue_url
+
+    # Cleanup
+    try:
+        aws_environment.sqs.delete_queue(queue_url)
+    except Exception:
+        pass
+
+
+@pytest.fixture
+def kinesis_stream(aws_environment):
+    """
+    Function-scoped Kinesis stream that's automatically cleaned up.
+
+    Creates a test stream and removes it after the test completes.
+
+    Args:
+        aws_environment: AWS environment fixture
+
+    Yields:
+        str: Stream name
+    """
+    stream_name = 'test-stream'
+    aws_environment.kinesis.create_stream(stream_name, shard_count=1)
+
+    yield stream_name
+
+    # Cleanup
+    try:
+        aws_environment.kinesis.delete_stream(stream_name)
+    except Exception:
+        pass
+
+
+@pytest.fixture
+def sns_topic(aws_environment):
+    """
+    Function-scoped SNS topic that's automatically cleaned up.
+
+    Creates a test topic and removes it after the test completes.
+
+    Args:
+        aws_environment: AWS environment fixture
+
+    Yields:
+        str: Topic ARN
+    """
+    response = aws_environment.sns.create_topic('test-topic')
+    topic_arn = response['TopicArn']
+
+    yield topic_arn
+
+    # Cleanup
+    try:
+        aws_environment.sns.delete_topic(topic_arn)
+    except Exception:
+        pass
+
+
+@pytest.fixture
+def lambda_function(aws_environment):
+    """
+    Function-scoped Lambda function that's automatically cleaned up.
+
+    Creates a simple test Lambda function and removes it after the test.
+
+    Args:
+        aws_environment: AWS environment fixture
+
+    Yields:
+        str: Function name
+    """
+    from testcontainers_aws.services.lambda_service import create_lambda_zip
+
+    function_name = 'test-function'
+    code = create_lambda_zip("""
+def handler(event, context):
+    return {
+        'statusCode': 200,
+        'body': 'Hello from Lambda!'
+    }
+""")
+
+    aws_environment.lambda_.create_function(
+        function_name=function_name,
+        runtime='python3.11',
+        handler='index.handler',
+        code=code
+    )
+
+    yield function_name
+
+    # Cleanup
+    try:
+        aws_environment.lambda_.delete_function(function_name)
+    except Exception:
+        pass

testcontainers_aws/services/__init__.py

@@ -0,0 +1,17 @@
+"""AWS service managers for simplified resource management."""
+
+from testcontainers_aws.services.s3 import S3ServiceManager
+from testcontainers_aws.services.dynamodb import DynamoDBServiceManager
+from testcontainers_aws.services.sqs import SQSServiceManager
+from testcontainers_aws.services.kinesis import KinesisServiceManager
+from testcontainers_aws.services.lambda_service import LambdaServiceManager
+from testcontainers_aws.services.sns import SNSServiceManager
+
+__all__ = [
+    "S3ServiceManager",
+    "DynamoDBServiceManager",
+    "SQSServiceManager",
+    "KinesisServiceManager",
+    "LambdaServiceManager",
+    "SNSServiceManager",
+]

testcontainers_aws/services/base.py

@@ -0,0 +1,25 @@
+"""Base service manager for AWS services."""
+
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from testcontainers_aws.core import AWSTestEnvironment
+
+
+class BaseServiceManager:
+    """Base class for AWS service managers."""
+
+    def __init__(self, environment: 'AWSTestEnvironment'):
+        """
+        Initialize service manager.
+
+        Args:
+            environment: Parent AWSTestEnvironment instance
+        """
+        self.environment = environment
+        self._client = None
+
+    @property
+    def client(self) -> Any:
+        """Get the boto3 client for this service (implemented by subclasses)."""
+        raise NotImplementedError("Subclasses must implement the client property")