Menttor
Library
LibraryLocal Testing with SAM

Local Testing with SAM

Learn about Local Testing with SAM as part of Serverless Architecture with AWS Lambda

Table of Contents

Local Testing with AWS SAM CLI

Developing serverless applications often involves deploying to the cloud for testing. However, this can be slow and costly. The AWS Serverless Application Model (SAM) Command Line Interface (CLI) provides powerful tools for local development and testing, significantly speeding up your workflow and reducing the need for frequent cloud deployments.

Why Local Testing is Crucial

Local testing allows you to:

  • Iterate faster: Get immediate feedback on code changes without waiting for deployments.
  • Reduce costs: Avoid unnecessary AWS service charges during development.
  • Debug efficiently: Use familiar debugging tools and techniques directly on your local machine.
  • Simulate cloud environments: Mimic AWS Lambda and API Gateway behavior locally.

Key SAM CLI Commands for Local Testing

SAM CLI simulates AWS Lambda and API Gateway locally.

The SAM CLI allows you to run your Lambda functions and API Gateway endpoints on your local machine, mimicking the behavior of the actual AWS services. This is achieved through Docker containers.

The SAM CLI leverages Docker to create isolated environments that closely resemble the AWS Lambda execution environment. When you invoke a function locally using sam local invoke, the CLI builds your function's dependencies and runs it within a Docker container configured to act like Lambda. Similarly, sam local start-api spins up a local API Gateway endpoint that routes requests to your local Lambda functions.

What are the two primary SAM CLI commands for local testing?

sam local invoke for functions and sam local start-api for API Gateway endpoints.

Invoking Lambda Functions Locally (`sam local invoke`)

The

code
sam local invoke
command allows you to execute a specific Lambda function defined in your SAM template. You can pass event payloads to simulate different triggers (e.g., API Gateway requests, S3 events).

Example usage:

bash
sam local invoke MyLambdaFunction --event events/event.json

Here,

code
MyLambdaFunction
is the logical ID of your function in the SAM template, and
code
events/event.json
is a file containing the simulated event payload.

Starting a Local API Gateway (`sam local start-api`)

The

code
sam local start-api
command starts a local web server that emulates API Gateway. It listens for HTTP requests and routes them to the appropriate Lambda functions defined in your SAM template. This is invaluable for testing REST APIs built with Lambda.

Example usage:

bash
sam local start-api

Once started, you can make HTTP requests to

code
http://127.0.0.1:3000/
to test your endpoints.

The SAM CLI uses Docker containers to simulate the AWS Lambda execution environment. When you run sam local invoke or sam local start-api, the CLI pulls or builds a Docker image that matches the runtime of your Lambda function (e.g., Node.js, Python, Java). This container then executes your function code, receiving event data and returning a response, effectively mimicking the behavior of AWS Lambda and API Gateway without requiring a network connection to AWS.

📚

Text-based content

Library pages focus on text content

Debugging Locally

SAM CLI supports attaching debuggers to your local Lambda functions. You can configure your IDE (like VS Code) to connect to the running function in the Docker container, allowing you to set breakpoints, inspect variables, and step through your code.

For Node.js, you can use the --debug-port flag with sam local invoke or sam local start-api to enable remote debugging.

Building and Packaging for Local Execution

Before invoking or starting an API locally, you often need to build your application. The

code
sam build
command compiles your code, installs dependencies, and prepares your function for execution. It creates a
code
.aws-sam/build
directory containing the deployable artifacts.

Example usage:

bash
sam build

This command reads your

code
template.yaml
and builds all the functions and layers defined within it.

Best Practices for Local Testing

  • Use realistic event payloads: Craft
    code
    event.json
    files that accurately represent the data your Lambda function will receive in production.
  • Test different event sources: Simulate various triggers like API Gateway, SQS, S3, etc.
  • Integrate with your IDE: Set up remote debugging for a more efficient development cycle.
  • Keep Docker updated: Ensure your Docker installation is current for optimal performance and compatibility.

Learning Resources

AWS SAM CLI Documentation(documentation)

Official AWS documentation for installing and using the SAM CLI, covering local testing commands and configurations.

Local Testing with AWS SAM CLI(documentation)

Detailed guide on the `sam local` commands, including `invoke`, `start-api`, and their options for simulating AWS services.

Debugging Serverless Applications Locally with AWS SAM(blog)

A blog post from AWS explaining how to set up debugging for your Lambda functions when using SAM CLI locally with popular IDEs.

AWS SAM Local Development Workflow(video)

A video tutorial demonstrating a typical local development workflow using AWS SAM CLI, from building to testing and debugging.

Simulating AWS Services with SAM Local(blog)

Learn about the expanded capabilities of SAM Local in simulating various AWS services beyond Lambda and API Gateway.

Building and Testing Serverless APIs with SAM(blog)

An article from the AWS Builders' Library focusing on best practices for building and testing serverless APIs using SAM.

AWS SAM GitHub Repository(documentation)

The official GitHub repository for AWS SAM CLI, offering source code, issue tracking, and community contributions.

Serverless Framework vs. AWS SAM(blog)

A comparative analysis of AWS SAM and the Serverless Framework, highlighting differences in local development and testing approaches.

Docker Documentation(documentation)

Essential documentation for understanding and working with Docker, the underlying technology for SAM's local testing.

AWS Lambda Event Structure(documentation)

Reference for the structure of events that AWS Lambda functions receive, crucial for creating accurate local test payloads.