Testing Lambdas locally with aws-sam-cli

Benefits of AWS SAM CLI

SAM stands for AWS Serverless Application Model, it is an open-source framework that you can use to build serverless applications on AWS.

AWS SAM Consists of the following components

  • AWS SAM template specification. This defines your serverless application. It is used to describe the functions, APIs, permissions, configurations, and events that make up a serverless application. You use an AWS SAM template file to operate on a single, deployable, versioned entity that’s your serverless application. See AWS Serverless Application Model Specification.
  • AWS SAM command line interface (AWS SAM CLI). This tool is used to build serverless applications defined by the AWS SAM templates. The CLI provides commands that enable you to verify your templates and to invoke and debug Lambda functions locally. You can also deploy serverless applications to the AWS Cloud via CloudFormation.  See AWS SAM CLI.

Whats covered?

  • Installation of AWS SAM CLI
  • Running Hello World
  • Some essential commands to get you started
  • Packaging and Deploying your Lambda


Mac or Linux

Install SAM CLI using Brew

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

Requires Docker and the AWS CLI. See installation instructions

Install SAM CLI using an MSI

Requires Docker and the AWS CLI. See installation instructions

pip install --user aws-sam-cli 

Requires Docker and the AWS CLI. See installation instructions


Make sure these commands in the directory you want to work in!

Hello World Sample App

Runtime is not required. Defaults to nodejs8.10.

On a Mac I had to install node via brew install node. Requires an npm install on hello-world directory and invoking works with event file only.

sam init --runtime <favourite-runtime>

You can invoke your function locally by passing its –SAM logical ID–and an event file. Alternatively, sam local invokeaccepts stdin as an event too.


    HelloWorldFunction: # <-- Logical ID
        Type: AWS::Serverless::Function # More info about Function Resource: https://github.com/awslabs/serverless-application-model/blob/master/versions/2016-10-31.md#awsserverlessfunction
            CodeUri: hello-world/

Invoking Function

sam local invoke "HelloWorldFunction"

Invoking Function with event file

sam local invoke "HelloWorldFunction" -e event.json

Invoking Function with event file via stdin

echo '{"message": "Hey, are you there?" }' | sam local invoke "HelloWorldFunction"

Invoking Function Output

Running API Gateway Locally

Use the sam local start-api command to start a local instance of API Gateway that you will use to test HTTP request/response functionality. This functionality features hot reloading to enable you to quickly develop and iterate over your functions.

sam local start-api

Image by AWS

Emulate AWS Lambda invoke endpoint (Automated Tests)

sam local start-lambda

This command starts a local endpoint at that emulates AWS Lambda. You can run your automated tests against this local Lambda endpoint. When you invoke this endpoint using the AWS CLI or SDK, it locally executes the Lambda function that’s specified in the request, and returns a response.

Debugging Lambda Functions Locally

Both commands sam local invoke and sam local start-api support local step-through debugging.  You must specify --debug-port or -d on the command line.

# Invoke a function locally in debug mode on port 5858
$ sam local invoke -d 5858 <function logical id>

# Start local API Gateway in debug mode on port 5858
$ sam local start-api -d 5858

Setup debugging on Node.js

Setup debugging on Python

Setup debugging on Golang

Packaging and Deploying AWS SAM CLI

 The sam package command zips your code artifacts, uploads them to Amazon S3, and produces a packaged AWS SAM template file that’s ready to be used. For example, the following command generates a packaged.yaml file:

# Package SAM template
sam package --template-file sam.yaml --s3-bucket mybucket --output-template-file packaged.yaml

The sam deploycommand uses this file to deploy your application.

# Deploy packaged SAM template
sam deploy --template-file ./packaged.yaml --stack-name mystack --capabilities CAPABILITY_IAM

These commands are identical to their AWS CLI equivalent commands of aws cloudformation package and aws cloudformation deploy.

Prev post: Terraform Enterprise vs Open-SourceNext post: GuardDuty in a multi-account organization with Terraform

Related posts

Leave a Reply

Your email address will not be published. Required fields are marked *