AWS Infrastructure Testing with LocalStack: Local Development and CI

TL;DR

• LocalStack emulates 80+ AWS services locally — test S3, Lambda, DynamoDB without cloud costs
• Use LocalStack for fast iteration and CI; use real AWS for integration tests before production
• The #1 mistake: treating LocalStack as production-equivalent (it’s for testing, not 100% parity)

Best for: Teams with AWS infrastructure who want faster feedback loops and lower CI costs Skip if: You need exact AWS behavior guarantees or use services LocalStack doesn’t support Read time: 10 minutes

Your Terraform tests against real AWS take 8 minutes per run. CI bills are climbing. Developers wait for cloud resources to provision before validating their changes. Meanwhile, S3 bucket configuration errors make it to production because testing felt “too slow.”

LocalStack changes this equation. It provides a local AWS cloud stack that runs in Docker, supporting 80+ services. Your tests run in seconds, not minutes. CI costs drop. Feedback loops tighten. But you need to understand what LocalStack does and doesn’t guarantee.

The Real Problem

Testing against real AWS has costs:

Time: Provisioning an RDS instance takes minutes. Creating a VPC with subnets, NAT gateways, and routes — more minutes. Developers avoid testing because it’s slow.

Money: CI running Terraform applies against real AWS accumulates costs. Forgotten test resources run overnight. Cost attribution is fuzzy.

Flakiness: Network issues, rate limits, and eventual consistency cause intermittent failures. Tests that pass locally fail in CI.

Environment conflicts: Multiple developers or CI jobs competing for the same AWS account create resource naming conflicts and state corruption.

LocalStack addresses these by providing a local, isolated AWS environment that provisions instantly and costs nothing.

LocalStack Setup

LocalStack runs as a Docker container. Basic setup:

# Start LocalStack
docker run -d \
  --name localstack \
  -p 4566:4566 \
  -e SERVICES=s3,dynamodb,lambda,sqs,sns,iam \
  -e DEBUG=1 \
  -v /var/run/docker.sock:/var/run/docker.sock \
  localstack/localstack:latest

# Verify it's running
curl http://localhost:4566/_localstack/health

For docker-compose (recommended for projects):

# docker-compose.yml
version: '3.8'

services:
  localstack:
    image: localstack/localstack:latest
    ports:

      - "4566:4566"
    environment:

      - SERVICES=s3,dynamodb,lambda,sqs,sns,iam,secretsmanager
      - DEBUG=1
      - DOCKER_HOST=unix:///var/run/docker.sock
    volumes:

      - "/var/run/docker.sock:/var/run/docker.sock"
      - "./localstack-data:/var/lib/localstack"

Start with docker-compose up -d.

Terraform with LocalStack

Configure Terraform to use LocalStack endpoints:

# providers.tf
provider "aws" {
  access_key                  = "test"
  secret_key                  = "test"
  region                      = "us-east-1"

  s3_use_path_style           = true
  skip_credentials_validation = true
  skip_metadata_api_check     = true
  skip_requesting_account_id  = true

  endpoints {
    s3             = "http://localhost:4566"
    dynamodb       = "http://localhost:4566"
    lambda         = "http://localhost:4566"
    iam            = "http://localhost:4566"
    sqs            = "http://localhost:4566"
    sns            = "http://localhost:4566"
    secretsmanager = "http://localhost:4566"
  }
}

Better approach — use environment-specific providers:

# providers.tf
locals {
  is_localstack = var.environment == "localstack"
}

provider "aws" {
  region = var.aws_region

  access_key = local.is_localstack ? "test" : null
  secret_key = local.is_localstack ? "test" : null

  s3_use_path_style           = local.is_localstack
  skip_credentials_validation = local.is_localstack
  skip_metadata_api_check     = local.is_localstack
  skip_requesting_account_id  = local.is_localstack

  dynamic "endpoints" {
    for_each = local.is_localstack ? [1] : []
    content {
      s3             = "http://localhost:4566"
      dynamodb       = "http://localhost:4566"
      lambda         = "http://localhost:4566"
      iam            = "http://localhost:4566"
      sqs            = "http://localhost:4566"
      sns            = "http://localhost:4566"
      secretsmanager = "http://localhost:4566"
    }
  }
}

Terratest with LocalStack

Terratest can target LocalStack:

package test

import (
    "testing"
    "os"

    "github.com/gruntwork-io/terratest/modules/aws"
    "github.com/gruntwork-io/terratest/modules/terraform"
    "github.com/stretchr/testify/assert"
)

func TestS3BucketWithLocalStack(t *testing.T) {
    t.Parallel()

    // Override AWS SDK to use LocalStack
    os.Setenv("AWS_ACCESS_KEY_ID", "test")
    os.Setenv("AWS_SECRET_ACCESS_KEY", "test")
    os.Setenv("AWS_DEFAULT_REGION", "us-east-1")

    terraformOptions := &terraform.Options{
        TerraformDir: "../modules/s3-bucket",
        Vars: map[string]interface{}{
            "environment":  "localstack",
            "bucket_name":  "test-bucket-" + random.UniqueId(),
        },
    }

    defer terraform.Destroy(t, terraformOptions)
    terraform.InitAndApply(t, terraformOptions)

    // Verify bucket exists
    bucketName := terraform.Output(t, terraformOptions, "bucket_name")

    // Use custom endpoint for LocalStack
    awsConfig := aws.NewConfig(
        aws.WithEndpointResolver(
            aws.EndpointResolverFunc(func(service, region string) (aws.Endpoint, error) {
                return aws.Endpoint{URL: "http://localhost:4566"}, nil
            }),
        ),
    )

    // Assert bucket properties
    assert.True(t, aws.AssertS3BucketExists(t, "us-east-1", bucketName))
}

Python Testing with moto

For Python applications, moto provides AWS mocking:

import boto3
import pytest
from moto import mock_aws

@mock_aws
def test_s3_bucket_creation():
    # Create mock S3
    s3 = boto3.client('s3', region_name='us-east-1')

    # Create bucket
    s3.create_bucket(Bucket='test-bucket')

    # Verify
    response = s3.list_buckets()
    bucket_names = [b['Name'] for b in response['Buckets']]
    assert 'test-bucket' in bucket_names

@mock_aws
def test_dynamodb_table():
    # Create mock DynamoDB
    dynamodb = boto3.resource('dynamodb', region_name='us-east-1')

    # Create table
    table = dynamodb.create_table(
        TableName='test-table',
        KeySchema=[{'AttributeName': 'id', 'KeyType': 'HASH'}],
        AttributeDefinitions=[{'AttributeName': 'id', 'AttributeType': 'S'}],
        BillingMode='PAY_PER_REQUEST'
    )

    # Write and read
    table.put_item(Item={'id': '123', 'data': 'test'})
    response = table.get_item(Key={'id': '123'})

    assert response['Item']['data'] == 'test'

@mock_aws
def test_lambda_invocation():
    # Create mock Lambda
    lambda_client = boto3.client('lambda', region_name='us-east-1')
    iam = boto3.client('iam', region_name='us-east-1')

    # Create role (required for Lambda)
    iam.create_role(
        RoleName='test-role',
        AssumeRolePolicyDocument='{}',
    )

    # Create function
    lambda_client.create_function(
        FunctionName='test-function',
        Runtime='python3.9',
        Role='arn:aws:iam::123456789:role/test-role',
        Handler='handler.main',
        Code={'ZipFile': b'fake code'},
    )

    # Verify function exists
    response = lambda_client.list_functions()
    function_names = [f['FunctionName'] for f in response['Functions']]
    assert 'test-function' in function_names

CI/CD Integration

GitHub Actions with LocalStack:

name: Infrastructure Tests

on:
  pull_request:
    paths:

      - 'terraform/**'
      - 'tests/**'

jobs:
  localstack-tests:
    runs-on: ubuntu-latest
    services:
      localstack:
        image: localstack/localstack:latest
        ports:

          - 4566:4566
        env:
          SERVICES: s3,dynamodb,lambda,sqs,sns,iam
          DEBUG: 1

    steps:

      - uses: actions/checkout@v4

      - name: Setup Terraform
        uses: hashicorp/setup-terraform@v3
        with:
          terraform_version: 1.7.0

      - name: Wait for LocalStack
        run: |
          timeout 60 bash -c 'until curl -s http://localhost:4566/_localstack/health | grep -q "running"; do sleep 2; done'

      - name: Run Terraform Tests
        run: |
          cd tests
          go test -v -timeout 10m ./...
        env:
          AWS_ACCESS_KEY_ID: test
          AWS_SECRET_ACCESS_KEY: test
          AWS_DEFAULT_REGION: us-east-1
          LOCALSTACK_ENDPOINT: http://localhost:4566

  # Real AWS tests run only on main branch
  aws-integration:
    runs-on: ubuntu-latest
    if: github.ref == 'refs/heads/main'
    steps:

      - uses: actions/checkout@v4
      - name: Configure AWS credentials
        uses: aws-actions/configure-aws-credentials@v4
        with:
          role-to-assume: arn:aws:iam::123456789:role/ci-role
          aws-region: us-east-1
      - name: Run Integration Tests
        run: go test -v -tags=integration ./tests/integration/...

LocalStack Pro vs Community

LocalStack Pro adds services not in the free tier:

For most Terraform testing, Community edition covers the common services. Pro is worth it if you heavily use RDS, EKS, or need CI persistence.

What LocalStack Doesn’t Cover

LocalStack is not AWS. Key differences:

IAM evaluation: LocalStack’s IAM is simplified. Policies that fail in real AWS might pass in LocalStack.

Eventual consistency: S3 in LocalStack is immediately consistent. Real S3 has eventual consistency for some operations.

Service limits: LocalStack doesn’t enforce AWS service quotas. Your test might pass but fail in production due to limits.

Networking: VPCs, subnets, security groups work differently. Network ACLs and complex routing aren’t fully emulated.

Performance characteristics: LocalStack doesn’t simulate AWS latency, throttling, or cold starts accurately.

Testing Strategy: Layered Approach

Use LocalStack as one layer in a complete testing strategy:

┌─────────────────────────────────────────────┐
│  Production (monitoring, canary deployments) │
├─────────────────────────────────────────────┤
│  Staging (real AWS, pre-production tests)    │
├─────────────────────────────────────────────┤
│  Integration (real AWS, CI on main branch)   │
├─────────────────────────────────────────────┤
│  LocalStack (fast feedback, all PRs)         │
├─────────────────────────────────────────────┤
│  Unit tests (no infrastructure)              │
└─────────────────────────────────────────────┘

Run LocalStack tests on every PR. Run real AWS tests on merge to main. Deploy to staging for final validation.

AI-Assisted Approaches

LocalStack configuration and mocking can be complex. AI tools help.

What AI does well:

• Generating LocalStack endpoint configurations for Terraform providers
• Converting real AWS test code to LocalStack-compatible versions
• Creating moto fixtures for Python tests
• Troubleshooting LocalStack service compatibility issues

What still needs humans:

• Deciding what tests need real AWS vs LocalStack
• Understanding which LocalStack limitations affect your use case
• Designing test architecture across the testing pyramid
• Validating that LocalStack tests actually catch real issues

Useful prompt:

I have this Terraform module that creates:

- S3 bucket with versioning and encryption
- DynamoDB table with GSI
- Lambda function triggered by S3 events

Generate:

1. docker-compose.yml for LocalStack with required services
2. Terraform provider configuration for LocalStack
3. Terratest Go code to validate the setup
4. List of limitations I should be aware of

When This Breaks Down

LocalStack testing has limitations:

Service gaps: If you use AppSync, Neptune, or other less-common services, LocalStack might not support them.

Behavior differences: Tests pass locally but fail in AWS. This happens when LocalStack’s emulation differs from AWS behavior.

State complexity: Long-running LocalStack instances accumulate state. Tests become order-dependent.

Docker overhead: On resource-constrained CI runners, LocalStack can be slow to start or consume too much memory.

Consider complementary approaches:

• Terraform testing with native test framework
• Contract tests for API behavior
• Real AWS integration tests for critical paths
• Multi-cloud testing for portability

Decision Framework

Use LocalStack when:

• Rapid iteration during development
• CI costs are a concern
• Testing common services (S3, DynamoDB, Lambda, SQS)
• Network isolation is required (offline testing)

Use real AWS when:

• Testing IAM policies and permissions
• Validating network configurations
• Using services LocalStack doesn’t support
• Final integration testing before production

Use moto when:

• Unit testing Python code with AWS SDK calls
• Speed is critical (moto is faster than LocalStack)
• You don’t need Terraform/infrastructure testing

Measuring Success

Warning signs it’s not working:

• Tests pass in LocalStack but fail in real AWS
• LocalStack becoming a bottleneck in CI
• Developers bypassing tests because LocalStack is “good enough”
• Service gaps forcing too many real AWS tests

What’s Next

Start with your most-tested services:

1. Identify which AWS services your Terraform modules use
2. Check LocalStack compatibility for those services
3. Set up docker-compose for local development
4. Convert one test suite to use LocalStack
5. Measure speed improvement and iterate
6. Add real AWS tests as integration layer

The goal is faster feedback, not replacing all AWS testing. LocalStack is a tool for speed; real AWS is the source of truth.

Related articles:

• Terraform Testing and Validation Strategies
• Multi-Cloud Infrastructure Testing
• Infrastructure as Code Testing
• Cost Estimation Testing for IaC

External resources:

• LocalStack Documentation
• LocalStack Coverage
• moto Documentation

Official Resources

• Terraform Documentation
• Terraform Registry
• Docker Documentation

See Also

• Cost Estimation Testing for Infrastructure as Code: Complete Guide - Master cost estimation testing for IaC with Infracost, terraform…
• AWS Infrastructure Testing: Complete Guide to Terraform, LocalStack & Terratest - Master AWS infrastructure testing with Terraform test framework,…
• Docker Image Testing and Security: Complete Guide to Container Vulnerability Scanning - Master Docker image security with Trivy, Snyk, and Grype. Learn…
• Matrix Testing in CI/CD Pipelines - Matrix Testing in CI/CD Pipelines: comprehensive guide covering…