AWS SAM CLI enables developers to test serverless applications locally before deploying to AWS. By simulating the Lambda execution environment on your machine, you can debug code, test integrations, and validate templates efficiently. This guide covers everything from basic testing to advanced debugging techniques.


Download Complete HTML Guide

Simple Analogy

Testing with SAM is like having a flight simulator for pilots. Instead of waiting to fly a real plane (deploy to AWS), you can practice maneuvers (test code) safely on the ground (your local machine) with realistic conditions.

Why Local Testing Matters

⏱️ Faster Iteration

Test code changes instantly without waiting for cloud deployments

💰 Cost Savings

Avoid cloud execution costs during development

🐛 Debugging Power

Use IDE debuggers with breakpoints and variable inspection

🔌 Offline Work

Develop and test without internet connectivity

Getting Started with SAM CLI

1 Install AWS SAM CLI

Follow the official installation guide for your OS.

# Verify installation
sam –version

2 Initialize Sample Project

sam init
# Choose: AWS Quick Start Templates
# Runtime: python3.9
# Template: Hello World Example

3 Start Local API

sam local start-api

# Output:
# Mounting HelloWorldFunction at http://127.0.0.1:3000/hello [GET]
# You can now test with: curl http://localhost:3000/hello

Debugging Techniques

Python Debugging Example

# Start in debug mode
sam local start-api -d 5858

# Configure VS Code launch.json:
{
  “version”: “0.2.0”,
  “configurations”: [
    {
      “name”: “Attach to SAM CLI”,
      “type”: “python”,
      “request”: “attach”,
      “port”: 5858,
      “host”: “localhost”,
      “pathMappings”: [{“localRoot”: “${workspaceFolder}”, “remoteRoot”: “/var/task”}]
    }
  ]
}

Testing Event Triggers

Simulate different event sources:

# S3 Event
sam local generate-event s3 put > s3-event.json
sam local invoke -e s3-event.json MyS3Function

# API Gateway Event
sam local generate-event apigateway aws-proxy > api-event.json
sam local invoke -e api-event.json MyApiFunction

Advanced Local Testing Scenarios

Testing with Local Databases

Use Docker to run local DynamoDB:

docker run -p 8000:8000 amazon/dynamodb-local

# In SAM template.yaml:
Environment:
  Variables:
    TABLE_NAME: my-local-table
    ENDPOINT_OVERRIDE: http://host.docker.internal:8000

Testing Step Functions Locally

Simulate state machine executions:

sam local start-state-machine
  –template template.yaml
  –log-file sf-logs.log

Best Practices

  • Mock external services: Use tools like LocalStack for AWS service emulation
  • Automate tests: Integrate with CI/CD pipelines
  • Organize templates: Follow template best practices
  • Parameterize configurations: Use different configs for dev/prod environments
  • Monitor performance: Track cold start times during local testing

Troubleshooting Common Issues

IssueSolution
Docker not runningStart Docker Desktop and verify with docker ps
Port conflictsUse sam local start-api -p 5000 to specify port
Missing dependenciesRun sam build before starting local environment
Debugger not connectingVerify port mappings and firewall settings

Real-World Use Case: E-commerce Checkout

Testing an order processing workflow locally:

  1. API Gateway endpoint (POST /orders)
  2. Lambda function processes order
  3. Sends message to SQS queue
  4. Another Lambda processes payment
  5. Stores result in DynamoDB

With SAM, you can test this entire flow locally using:

sam local start-api
sam local start-sqs
sam local invoke PaymentProcessorFunction


Download Full HTML Guide