Introduction

Testing AWS Lambda locally usually means combining two levels of feedback: fast unit tests that call the handler directly, and environment-level tests that run the function in a Lambda-like runtime. The most common local tool for the second level is AWS SAM CLI, which uses Docker to emulate the Lambda execution environment.

Start With Direct Handler Tests

The fastest local tests do not try to emulate all of AWS. They import the handler and call it with an event object directly.

For a Python Lambda:

1def handler(event, context):
2    name = event.get("name", "world")
3    return {
4        "statusCode": 200,
5        "body": f"hello {name}"
6    }
7
8
9if __name__ == "__main__":
10    print(handler({"name": "Ada"}, None))

A unit test can call that handler directly:

1def test_handler():
2    result = handler({"name": "Ada"}, None)
3    assert result["statusCode"] == 200
4    assert result["body"] == "hello Ada"

This is the best place to verify business logic quickly.

Use AWS SAM for Runtime-Like Testing

When you need to test packaging, environment variables, and the Lambda runtime behavior more realistically, SAM CLI is the standard local tool.

A common workflow is:

sam build
sam local invoke MyFunction --event event.json

If the function is behind API Gateway:

sam local start-api

Then you can send HTTP requests to the locally emulated endpoint.

This is slower than unit tests, but much closer to how the function will run in AWS.

Why Docker Matters

SAM typically uses Docker containers to emulate the runtime environment. That matters because many Lambda issues are not logic bugs; they are packaging or runtime issues such as:

• missing native dependencies
• incorrect handler path
• environment-specific file access
• differences between local OS and Lambda runtime

Running locally in a Lambda-like container catches many of those earlier.

Mock AWS Services Carefully

A Lambda rarely runs in isolation. If it calls S3, DynamoDB, or SQS, you usually do not want every local test to depend on real cloud resources.

For unit tests, mock those service calls and focus on the Lambda's behavior. For broader integration tests, choose a controlled local or test environment instead of hitting production services.

The goal is to keep most tests fast and deterministic.

Event Files Make Local Runs Repeatable

A simple JSON event file is an easy way to test known scenarios.

event.json

{
  "name": "Ada"
}

Then:

sam local invoke MyFunction --event event.json

This is much easier to repeat and share than typing large event payloads by hand every time.

Separate Logic From AWS Glue

Lambda functions are easiest to test when the handler is thin and the real business logic lives in ordinary functions or classes. That way:

• unit tests target plain code
• the handler just maps event and context into that code
• local emulation is reserved for integration behavior

This design usually improves both testability and code clarity.

Common Pitfalls

The biggest mistake is treating local Lambda testing as one thing. Direct unit tests and runtime emulation solve different problems and both are useful.

Another issue is skipping Docker-based testing when the function depends on native packages or runtime-specific behavior. Pure local execution may hide packaging problems.

Developers also overuse cloud resources in tests, turning local feedback into slow and brittle integration runs.

Finally, if the handler contains all the business logic, testing becomes harder than it needs to be. Keep the handler thin and test the real logic separately.

Summary

• Test Lambda handlers directly with unit tests for fast feedback.
• Use AWS SAM CLI for runtime-like local invocation and API emulation.
• Docker-backed emulation helps catch packaging and environment issues.
• Mock AWS service calls in unit tests instead of depending on real cloud resources.
• Keep handlers thin so most behavior can be tested as ordinary application code.