AWS SAM CLI gives a serverless project two useful local entry points: a one-off function invocation with a saved event, and an HTTP server that routes requests to functions declared in the SAM template. These checks help with code, packaging, and request handling. They do not create the AWS services in the template or prove that a deployed API, event source, IAM policy, or network behaves correctly.

This guide assumes you have a SAM project and Docker running. If you need to install the tools or create a starter project, use our AWS SAM local setup guide.

Build the project when its artifacts change

From the directory containing template.yaml, build the application before testing when you have changed dependencies, compiled code, or a previously built project:

sam build

SAM writes build artifacts under .aws-sam. Rebuild after editing code that a local command will read from that directory. If dependencies contain native code that must match Lambda's Linux environment, or your host lacks the function's matching runtime, use sam build --use-container; this requires Docker and may download a builder image. Check the mount and function messages from SAM if a test seems to run old code. AWS explains how build artifacts are used by local tests.

Exercise an HTTP route locally

sam local start-api reads the API events in your template, starts a local HTTP server, and invokes the matching function when a request reaches a declared route. Assume this project declares a POST /orders route:

sam local start-api

Leave the server running, then send a request from another terminal:

curl -i -X POST http://127.0.0.1:3000/orders \
  -H 'content-type: application/json' \
  --data '{"orderId":"local-123"}'

The default local port is 3000; if it is already in use, choose another with --port and update the URL. Test the methods, paths, headers, query parameters, and request bodies that your handler reads. This server exercises SAM's local route handling and Lambda runtime, not a deployed API Gateway endpoint or every API Gateway feature. AWS documents the sam local start-api workflow and notes that local authorizer behavior is not guaranteed to match AWS exactly.

Invoke a function with an event fixture

For event-driven code, a generated event is input data for the function. It does not publish a message, upload an object, or run an AWS trigger. Generate a service-shaped sample, edit the values to match your test case, and invoke the function's logical ID:

mkdir -p events
sam local generate-event s3 put --bucket amzn-s3-demo-bucket > events/s3-put.json
sam local invoke S3EventFunction --event events/s3-put.json

To test an HTTP proxy handler directly, choose the event format used by its API. For an API Gateway HTTP API payload version 2.0:

sam local generate-event apigateway http-api-proxy \
  --method POST --path orders > events/order-http-api-v2.json
sam local invoke OrdersFunction --event events/order-http-api-v2.json

For a REST API proxy event, use sam local generate-event apigateway aws-proxy instead. Inspect the result before invoking: the route, method, body, and payload version must match the handler. If you replace a sample body with plain JSON text, set isBase64Encoded to false; if the body is Base64-encoded, keep it true. Otherwise the handler can receive a different body than the HTTP request you intended to test. AWS lists the event generator options and documents HTTP API Lambda payload formats.

Set local values without changing the template

Declare runtime variables under the function's Environment.Variables in the template, then use --env-vars env.local.json to supply local replacement values; the file does not add undeclared variables. Use --parameter-overrides for CloudFormation template parameters that feed resource or function configuration. They solve different problems: an --env-vars JSON file changes runtime environment values; a parameter override supplies a value to a template parameter. For example:

sam local invoke OrdersFunction \
  --event events/order-created.json \
  --parameter-overrides ParameterKey=Stage,ParameterValue=local

Keep test resource names in local configuration, and keep credentials out of event and environment files. The local invoke guide covers events and environment files; the command reference documents parameter overrides.

Verify AWS integrations in a development stack

A local invocation can still make real AWS API calls if the function's SDK has valid credentials and network access. Those calls use the credentials available to the local process, not the Lambda execution role in your template. They can change real data or incur charges. Before running code that calls AWS, select a dedicated sandbox or non-production account, use short-lived credentials scoped to the test, and confirm which account the credentials identify. Point environment variables at test resources, never production resources.

When a change depends on AWS wiring, verify it in an isolated development stack. First confirm the profile points to the intended sandbox account with aws sts get-caller-identity --profile dev. Then, with permission to deploy, sam sync --stack-name sam-app-dev --profile dev --watch builds and initially deploys the application, then syncs later changes to AWS. This command changes cloud resources and can incur charges. Use it only for a development stack. AWS recommends sam sync for development and sam deploy or a delivery pipeline for production. After syncing, test the deployed API URL and verify the resource behavior the change relies on.

SAM local can check a handler against an event and can route HTTP requests locally. It does not test the deployed execution role, API authorizer and policy behavior in full, VPC routing, event-source mapping delivery and retries, AWS quotas, or production performance. Use a small cloud test when the result depends on those properties. For a broader plan for isolated deployed workflows, read our AWS end-to-end testing guide. AWS describes the boundary between local and cloud checks in its Lambda testing guidance.