New features to simplify automated testing and troubleshooting of your serverless applications 💯

What is new in 🐿?

This release has two exciting features that make it even easier to programmatically test and troubleshoot your serverless applications. Here is the TL;DR:

1. Run your automated tests in a local, Lambda-like environment using the AWS SDKs
2. Troubleshoot your Lambda functions using the sam logs command to fetch, tail & filter your function logs.

Upgrade now to v0.5.0

pip install --upgrade aws-sam-cli

Run automated tests in a local, lambda-like environment

Previously, you could use the sam local invoke command to run your Lambda functions locally and manually test your code. With this release, SAM CLI makes it easier to author automated integration tests by letting you run tests against local Lambda functions before deploying to the cloud. The new sam local start-lambda command starts a local endpoint that emulates the AWS Lambda service’s invoke endpoint, and you can invoke it from your automated tests. Because this endpoint emulates the Lambda service's invoke endpoint, you can write tests once and run them (without any modifications) against the local Lambda function or against a deployed Lambda function. You can also run the same tests against a deployed SAM stack in your CI/CD pipeline.

Here is how this works:

1. Start the Local Lambda Endpoint
Start the local Lambda endpoint by running the following command in the directory that contains your AWS SAM template:

sam local start-lambda

This command starts a local endpoint at http://127.0.0.1:3001 that emulates the AWS Lambda service, and you can run your automated tests against this local Lambda endpoint. When you send an invoke to this endpoint using the AWS CLI or SDK, it will locally execute the Lambda function specified in the request and return a response.

2. Run integration test against local Lambda endpoint
In your integration test, you can use AWS SDK to invoke your Lambda function with test data, wait for response, and assert that the response what you expect. To run the integration test locally, you should configure AWS SDK to send Lambda Invoke API call to local Lambda endpoint started in previous step.

Here is an Python example (AWS SDK for other languages have similar configurations):

import boto3

# Set "running_locally" flag if you are running the integration test locally
if running_locally:

    # Create Lambda SDK client to connect to appropriate Lambda endpoint
    lambda_client = boto3.client('lambda',
                                 endpoint_url="http://127.0.0.1:3001",
                                 use_ssl=False,
                                 verify=False,
                                 config=Config(signature_version=UNSIGNED,
                                               read_timeout=0,
                                               retries={'max_attempts': 0}))
else:
    lambda_client = boto3.client('lambda')
                                        

# Invoke your Lambda function as you normally usually do. The function will run 
# locally if it is configured to do so
response = lambda_client.invoke(FunctionName="HelloWorldFunction")

# Verify the response 
assert response == "Hello World"

This code can run without modifications against a Lambda function which is deployed. To do so, set the running_locally flag to False . This will setup AWS SDK to connect to AWS Lambda service on the cloud.

Fetch, tail, and filter your function logs using the new sam logs command

To simplify troubleshooting, we added a new command called sam logs to SAM CLI. sam logs lets you fetch logs generated by your Lambda function from the command line. In addition to printing the logs on the terminal, this command has several nifty features to help you quickly find the bug. Note: This command works for all AWS Lambda functions; not just the ones you deploy using SAM.

Basic Usage: Using CloudFormation Stack
When your function is a part of a CloudFormation stack, you can fetch logs using the function's LogicalID:

sam logs -n HelloWorldFunction --stack-name mystack

Basic Usage: Using Lambda Function name
Or, you can fetch logs using the function's name

sam logs -n mystack-HelloWorldFunction-1FJ8PD

Tail Logs
Add --tail option to wait for new logs and see them as they arrive. This is very handy during deployment or when troubleshooting a production issue.

sam logs -n HelloWorldFunction --stack-name mystack --tail

View logs for specific time range
You can view logs for specific time range using the -s and -e options

sam logs -n HelloWorldFunction --stack-name mystack -s '10min ago' -e '2min ago'

Filter Logs
Use the --filter option to quickly find logs that match terms, phrases or values in your log events

sam logs -n HelloWorldFunction --stack-name mystack --filter "error"

In the output, SAM CLI will underline all occurrences of the word “error” so you can easily locate the filter keyword within the log output.

Error Highlighting
When your Lambda function crashes or times out, SAM CLI will highlight the timeout message in red. This will help you easily locate specific executions that are timing out within a giant stream of log output.

JSON pretty printing
If your log messages print JSON strings, SAM CLI will automatically pretty print the JSON to help you visually parse and understand the JSON.

More features & Bug fixes

• Support for running dotnetcore2.1 Lambda functions locally (#545)
• Support for long running Lambda functions & debugging sessions. Previously SAM CLI's socket connection to the Docker container will break when session lasted > 60 seconds (#422)
• Fixing the bug where SAM CLI didn't work when arbitrary proxy path names (#505)

Thanks to the amazing community for contributing features, reporting bugs, and helping out with pull requests. You are awesome 🔥