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.
<img width="1278" alt="42301038-3363a366-7fc8-11e8-9d0e-308b209cb92b" src="https://user-images.githubusercontent.com/22755571/42782490-f84cea3c-88fd-11e8-9c4e-5f8aeb730bc0.png">
**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.
<img width="801" alt="42301064-50c6cffa-7fc8-11e8-8f31-04ef117a9c5a" src="https://user-images.githubusercontent.com/22755571/42782507-01c4a4f6-88fe-11e8-982a-764e4724a19e.png">
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 🔥**