Locally invoke Lambda functions with AWS SAM

Locally invoking a Lambda function before testing or deploying in the cloud can have a variety of benefits. It allows you to test the logic of your function faster. Testing locally first reduces the likelihood of identifying issues when testing in the cloud or during deployment, which can help you avoid unnecessary costs. Additionally, local testing makes debugging easier to do.

You can invoke your Lambda function locally by using the sam local invoke command and providing the function's logical ID and an event file. sam local invoke also accepts stdin as an event. For more information about events, see Event in the AWS Lambda Developer Guide. For information about event message formats from different AWS services, see Using AWS Lambda with other services in the AWS Lambda Developer Guide.

You must run the sam local invoke command in the project directory that contains the function that you want to invoke.

Examples:

# Invoking function with event file
$ sam local invoke "Ratings" -e event.json

# Invoking function with event via stdin
$ echo '{"message": "Hey, are you there?" }' | sam local invoke --event - "Ratings"

# For more options
$ sam local invoke --help

Environment variable file

To declare environment variables locally that override values defined in your templates, do the following:

The --env-vars option supports two file formats. The file format is automatically detected based on the file content.

Declaring environment variables with JSON

To declare environment variables that apply globally to all resources, specify a Parameters object like the following:

{
    "Parameters": {
        "TABLE_NAME": "localtable",
        "BUCKET_NAME": "amzn-s3-demo-bucket",
        "STAGE": "dev"
    }
}

To declare different environment variables for each resource, specify objects for each resource like the following:

{
    "MyFunction1": {
        "TABLE_NAME": "localtable",
        "BUCKET_NAME": "amzn-s3-demo-bucket",
    },
    "MyFunction2": {
        "TABLE_NAME": "localtable",
        "STAGE": "dev"
    }
}

When specifying objects for each resource, you can use the following identifiers, listed in order of highest to lowest precedence:

You can use both of the preceding methods of declaring environment variables together in a single file. When doing so, environment variables that you provided for specific resources take precedence over global environment variables.

Save your environment variables in a JSON file, such as env.json.

Declaring environment variables with .env files

You can also use a .env file to declare environment variables. Variables declared in a .env file apply globally to all functions, equivalent to the Parameters object in JSON format.

TABLE_NAME=localtable
BUCKET_NAME=amzn-s3-demo-bucket
STAGE=dev

The .env format supports comments (lines starting with #) and quoted values.

Overriding environment variable values

To override environment variables with those defined in your environment variable file, use the --env-vars argument with the invoke or start-api commands. For example:

# Using a JSON file
sam local invoke --env-vars env.json

# Using a .env file
sam local invoke --env-vars .env

Layers

If your application includes layers, for information about how to debug issues with layers on your local host, see Increase efficiency using Lambda layers with AWS SAM.

Learn more

For a hands-on example of invoking functions locally, see Module 2 - Run locally in The Complete AWS SAM Workshop.