How do I debug a Lambda function locally with SAM CLI?

Use `sam local invoke` with the --debug-port flag to attach a debugger (e.g., for Python or Node.js) in a Docker container. This mimics the AWS environment, allowing breakpoints and step-by-step inspection in your IDE.

SAM CLI vs Serverless Framework: which is better?

SAM CLI is tightly integrated with AWS CloudFormation and excels at local testing with Docker, while Serverless Framework supports multiple clouds and has a larger plugin ecosystem. Choose SAM for AWS-native projects and Serverless for multi-cloud or extensive community plugins.

Can I use SAM CLI with AWS CDK?

Yes, SAM CLI supports testing and deploying applications defined with AWS CDK, as mentioned in the README for local testing on CDK applications. Use `sam build` and `sam deploy` with CDK-generated CloudFormation templates.

What are the limitations of SAM local testing?

Local testing may not perfectly replicate cloud behavior for services like DynamoDB streams or X-Ray traces, and it requires Docker running. Some AWS features, such as IAM roles or VPC configurations, have limited emulation.

How to handle environment variables in SAM local testing?

Define environment variables in your SAM template under the Function properties, and they'll be loaded automatically with `sam local invoke`. You can also override them via command-line options or external files for testing.

Does SAM CLI support custom Lambda runtimes?

Yes, SAM CLI can build and test custom runtimes using the `sam build` command with appropriate configurations, as it leverages Lambda builders for supported runtimes and custom workflows.

Open-Awesome

aws-sam-local

Apache-2.0Pythonv1.161.1

A CLI tool to build, test, debug, and deploy serverless applications using AWS SAM.

Visit Website GitHub

6.7k stars1.2k forks0 contributors

What is aws-sam-local?

AWS SAM CLI is a command-line tool that helps developers build, test, debug, and deploy serverless applications using the AWS Serverless Application Model (SAM). It provides a local development environment that emulates AWS services like Lambda and API Gateway, enabling faster iteration and testing before deploying to the cloud.

Target Audience

Developers and DevOps engineers building serverless applications on AWS, particularly those using AWS SAM or CloudFormation templates who want efficient local testing and deployment workflows.

Value Proposition

It significantly accelerates serverless development by allowing local testing and debugging, reducing dependency on cloud deployments for every change, and integrates seamlessly with AWS services and CI/CD pipelines.

Overview

CLI tool to build, test, debug, and deploy Serverless applications using AWS SAM

Use Cases

Best For

Developing and testing AWS Lambda functions locally before deployment
Building serverless APIs with API Gateway and Lambda
Debugging complex serverless applications in a local Docker environment
Automating deployment of SAM or CloudFormation templates
Setting up CI/CD pipelines for serverless projects
Rapid prototyping of serverless architectures with pre-built templates

Not Ideal For

Projects targeting multi-cloud or non-AWS environments
Teams already using Terraform or other non-CloudFormation infrastructure-as-code tools
Applications heavily dependent on AWS services without robust local emulation (e.g., Aurora, Kinesis)
Developers seeking minimal setup without Docker for local testing

Pros & Cons

Pros

Local Testing Environment

Emulates Lambda and API Gateway in Docker containers, allowing full debugging and testing without cloud deployments, as highlighted by the `sam local` commands.

Cloud Sync Feature

The `sam sync` command enables rapid iteration by synchronizing code changes directly to AWS for testing, reducing feedback loops from minutes to seconds.

Build Flexibility

Supports custom build workflows with Makefile and handles both zip and image-based Lambda deployments via `sam build`, accommodating diverse project needs.

CI/CD Integration

Automates pipeline setup with prebuilt templates for popular systems like Jenkins and GitHub Actions using `sam pipeline init`, speeding up DevOps configuration.

Cons

Docker Dependency

Local execution requires Docker, which adds resource overhead and setup complexity, making it less lightweight for quick, ad-hoc testing.

AWS Ecosystem Lock-in

Designed exclusively for AWS services, so it's ineffective for hybrid or multi-cloud projects, limiting flexibility compared to agnostic tools.

Incomplete Local Emulation

Not all AWS services are fully supported locally (e.g., EventBridge or SQS may have limited emulation), requiring cloud testing for some integrations.

Frequently Asked Questions

Related Projects

serverless

⚡ Serverless Framework – Effortlessly build apps that auto-scale, incur zero costs when idle, and require minimal maintenance using AWS Lambda and other managed cloud services.

Stars46,924

Forks5,733

Last commit4 days ago

chromeless

🖥 Chrome automation made simple. Runs locally or headless on AWS Lambda.

Stars13,229

Forks568

Last commit7 years ago

Zappa

Serverless Python

Stars11,839

Forks1,174

Last commit3 years ago

lambci

A continuous integration system built on AWS Lambda

Stars3,969

Forks184

Last commit2 years ago

Community-curated · Updated weekly · 100% open source

Found a gem we're missing?

Open-Awesome is built by the community, for the community. Submit a project, suggest an awesome list, or help improve the catalog on GitHub.

Submit a project Star on GitHub