Skip to main content

Local Testing & Debugging

Why Test Locally?​

  • Faster iteration (no AWS roundtrip)
  • Cheaper (no invocation charges)
  • Better debugging (full IDE features)
  • Test edge cases before deploying

Simple Explanation​

What it is​

Local testing lets you run a serverless function on your laptop before you deploy it to the cloud.

Why we need it​

It is faster to catch bugs locally than to deploy, wait, and debug in production.

Benefits​

  • Quick feedback during development.
  • Safer changes because you can test edge cases.
  • Lower cost by reducing cloud invocations.

Tradeoffs​

  • Local environments are not perfect replicas of cloud behavior.
  • Tooling setup adds a little upfront time.

Real-world examples (architecture only)​

  • Local HTTP request → Function → Log output.
  • Local event file → Function → Verify response.

SAM (Serverless Application Model) is AWS's framework for local serverless development.

Install SAM​

macOS:

brew tap aws/tap
brew install aws-sam-cli

Linux/Windows: Installation Guide

Verify Installation​

sam --version

You should see: SAM CLI 1.x.x

Create a Local Project​

sam init --runtime python3.12 --package-type Zip

Follow prompts. This creates a template project.

Project Structure​

SAM project structure

Run Locally​

sam local start-api

You'll see:

Mounting HelloWorldFunction at http://127.0.0.1:3000/hello [GET]

Test it:

curl http://127.0.0.1:3000/hello

Debug with Breakpoints​

sam local start-api --debug

Then attach your IDE's debugger (VS Code, PyCharm, etc.).

Option 2: AWS Toolkit for VS Code​

Install Toolkit​

  1. Open VS Code Extensions
  2. Search: "AWS Toolkit"
  3. Install by Amazon Web Services

Local Testing​

  1. Open an existing Lambda function in VS Code
  2. Right-click the handler function
  3. Select "AWS: Run/Debug Locally"
  4. Choose "Run" or "Debug"

Toolkit emulates Lambda locally without needing SAM setup.

Option 3: Functions Framework (GCP)​

Lightweight local runner for Google Cloud Functions.

Install​

python -m pip install functions-framework

Run Locally​

functions-framework --target=hello --port=8080

Test it:

curl http://localhost:8080/

Debugging Tips​

1. Add Logging​

print("Starting function...")
print(f"Event: {event}")
print("Processing complete")

View logs in CloudWatch (AWS) or terminal (local).

2. Use Debugger​

Python:

import pdb; pdb.set_trace()  # Execution pauses here

3. Test Edge Cases​

# Test with empty event
sam local invoke MyFunction -e events/empty.json

# Test with error scenario
sam local invoke MyFunction -e events/error.json

# Test with timeout
sam local invoke MyFunction --env-vars env.json

Common Issues & Solutions​

IssueSolution
"Port 3000 already in use"sam local start-api --port 3001
Function times out locallyIncrease timeout in template.yaml
IAM permission errorsUse real AWS credentials (export AWS_PROFILE)
Module not foundEnsure dependencies are in requirements.txt and installed

Best Practices​

  1. Test before deploying — Catch bugs locally
  2. Use events files — Save test scenarios
  3. Mock external services — Don't call real DynamoDB during testing
  4. Version your tests — Test new features before release
  5. Monitor logs — Both local and CloudWatch

Hands-On: Debug Your HelloServerless Function​

Step 1: Install SAM​

sam --version

Step 2: Create a test event​

{
  "name": "Debug Test"
}

Step 3: Run locally​

sam local invoke HelloServerless -e test-event.json

Step 4: Add logging​

def lambda_handler(event, context):
  print("Starting handler")
  print(f"Event: {event}")

  name = event.get("name", "World")
  print(f"Name: {name}")

  response = {"message": f"Hello, {name}!"}
  print(f"Response: {response}")

  return response

Step 5: Test again​

sam local invoke HelloServerless -e test-event.json

You should see all logs in your terminal.

Key Takeaway​

Local testing makes you a faster, more confident developer. Test everything locally before paying to run it in AWS.

Project (Cloud-Agnostic)​

Set up local testing for a Python serverless function and document the steps.

Deliverables:

  1. Show how to run the function locally.
  2. Provide at least two test events.
  3. Describe how you would debug a failing invocation.

If you want feedback, email your write-up to maarifaarchitect@gmail.com.

References​