SAM Local Testing and Debugging

AWS Serverless Application Model (SAM) is an open-source framework for building serverless applications. SAM local testing extends the sam build and sam deploy workflow by allowing you to run your serverless application locally before deploying to AWS. This is essential for rapid development and debugging because deploying to the cloud for every code change is slow and costly. With SAM local, you can invoke Lambda functions locally, simulate API Gateway requests, and even interact with local versions of AWS services like DynamoDB and S3.

The DVA-C02 exam tests your ability to use SAM CLI commands (sam local invoke, sam local start-api, sam local start-lambda) and understand how they work under the hood. You must also know how to configure environment variables, mount local files, and use debugging tools like AWS SAM CLI with IDEs.

SAM local uses Docker containers to emulate the AWS Lambda execution environment. When you run sam local invoke, the SAM CLI: 1. Reads the SAM template (template.yaml) to understand your application's resources. 2. Builds a Docker image that mimics the Lambda runtime (e.g., Python 3.9, Node.js 18). 3. Mounts your function code into the container. 4. Passes the event payload (from a file or stdin) as the invocation event. 5. Captures the function's response, logs, and any errors.

For sam local start-api, the CLI starts a local HTTP server that emulates API Gateway. It parses the SAM template's API event sources and routes incoming HTTP requests to the appropriate Lambda function. The server runs on http://127.0.0.1:3000 by default (configurable with -p).

Key components: - Docker: Required for running Lambda containers. SAM CLI uses Docker images from public.ecr.aws/lambda/. - samconfig.toml: Optional configuration file for default parameters. - events/: Directory where you can store JSON event files to simulate various AWS event sources (e.g., API Gateway, S3, SQS).

- sam local invoke [FunctionName] [options] - -e, --event <file>: Path to a JSON event file. - -n, --env-vars <file>: Path to a JSON file containing environment variables. - -l, --log-file <file>: Write logs to a file. - -d, --docker-network <network>: Connect to a specific Docker network. - --profile <profile>: AWS credentials profile. - --region <region>: AWS region. - --container-host <host>: Host for the container (default: localhost). - --container-host-interface <interface>: Interface for the container host. - --debug: Print debug logs.

- sam local start-api [options] - -p, --port <port>: Port to listen on (default: 3000). - -l, --log-file <file>: Write logs to a file. - --profile, --region, --debug: Same as above. - --warm-containers <type>: Strategy for keeping containers warm (EAGER, LAZY). - --container-host, --container-host-interface: Same. - --env-vars, --docker-network: Same.

SAM local does not automatically inherit AWS credentials or environment variables from your shell. You must explicitly provide them via: - --env-vars flag pointing to a JSON file like:

{
  "MyFunction": {
    "TABLE_NAME": "my-table",
    "BUCKET_NAME": "my-bucket"
  }
}

For AWS credentials, SAM local uses the same credential chain as the AWS CLI: environment variables (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_SESSION_TOKEN), shared credential file (~/.aws/credentials), or IAM roles (if running on EC2). However, note that local invocations do not have IAM permissions; any calls to AWS services from your function will fail unless you provide valid credentials that have the necessary permissions.

SAM local supports step-through debugging using the AWS SAM CLI debug mode. To debug: 1. Start your function with sam local invoke -d 5858 MyFunction (or any port). 2. Attach a debugger (e.g., in VS Code, use a launch configuration that attaches to localhost:5858). 3. Set breakpoints in your code. 4. Invoke the function; execution will pause at breakpoints.

For Python, you need to install debugpy in your container or use the AWS Lambda runtime image that includes it. For Node.js, the runtime includes the inspector.

SAM local integrates with DynamoDB Local, an in-memory database that emulates DynamoDB. To use it:

Given a SAM template with an API Gateway event source:

Resources:
  HelloWorldFunction:
    Type: AWS::Serverless::Function
    Properties:
      CodeUri: hello-world/
      Handler: app.lambdaHandler
      Runtime: nodejs18.x
      Events:
        HelloWorld:
          Type: Api
          Properties:
            Path: /hello
            Method: get

To test locally: 1. Build: sam build 2. Start API: sam local start-api 3. Send request: curl http://127.0.0.1:3000/hello

The SAM CLI will invoke the HelloWorldFunction and return the response.

To test with specific events (e.g., an S3 put event):

sam local invoke ProcessS3Event -e events/s3-put.json

Where events/s3-put.json contains:

{
  "Records": [
    {
      "eventSource": "aws:s3",
      "s3": {
        "bucket": {
          "name": "my-bucket"
        },
        "object": {
          "key": "my-key"
        }
      }
    }
  ]
}

If your function uses Lambda layers, SAM local automatically downloads and mounts them if the layer is defined in the same template or is an AWS-provided layer. For custom layers stored in S3, you must have the layer locally available or reference it by ARN (SAM CLI will attempt to download it).

A fintech company develops a serverless application for processing loan applications. The application consists of multiple Lambda functions triggered by API Gateway, S3 events, and Step Functions. The team integrates SAM local testing into their CI/CD pipeline (e.g., Jenkins or GitLab CI). For every pull request, the pipeline runs sam build and sam local invoke with predefined event files to validate function logic. They also run sam local start-api and use a test suite (e.g., pytest with requests) to hit the local API endpoints. This catches integration bugs early, such as incorrect event parsing or missing environment variables. The pipeline uses Docker containers with the SAM CLI pre-installed and mounts the workspace. They use a local DynamoDB container for database tests. This approach reduces deployment failures by 40% and speeds up developer feedback loops.

A travel booking platform encounters an issue where a Lambda function fails intermittently when processing high-volume SQS messages. The developer replicates the SQS event structure using a sample event file from CloudWatch Logs. They run sam local invoke ProcessBooking -e events/sqs-event.json and attach a debugger to step through the code. They discover a race condition caused by a global variable not being reset between invocations. Without SAM local, debugging would require multiple deployments with added logging, taking hours. With local debugging, they fix the bug in 20 minutes. They also use sam local start-lambda to simulate the Lambda Invoke API for testing inter-function calls.

A large e-commerce company onboards new developers to a serverless microservices architecture. Instead of granting full AWS access, they provide a local development environment using SAM local. New hires clone the repository, run sam build and sam local start-api, and begin testing their changes immediately. They use a shared local DynamoDB container with anonymized production data. This eliminates the risk of accidental deployments or costly mistakes. The company also uses sam local invoke with a library of event files that simulate various scenarios (e.g., order placed, payment failed). Developers can run these tests without internet access. This practice reduces the learning curve and ensures code quality before the first deployment.