MaarkssDN/Birthub-360 / .agents/skills/aws-sam-local-testing
aws-sam-local-testing
VerifiedUse when AWS Lambda functions with API Gateway need testing locally: sam local invoke with event payloads, start-api for a local API Gateway, start-lambda for SDK clients and generate-event, plus .NET Lambda handler tests with Amazon.Lambda.TestUtilities.
| File | Kind | Size |
|---|---|---|
| .tessl-plugin/plugin.json | config | 392 B |
| SKILL.md | skill md | 6.3 KB |
| references/dotnet.md | markdown | 4.5 KB |
SKILL.md
View on GitHub---
name: aws-sam-local-testing
description: "Use when AWS Lambda functions with API Gateway need testing locally: sam local invoke with event payloads, start-api for a local API Gateway, start-lambda for SDK clients and generate-event, plus .NET Lambda handler tests with Amazon.Lambda.TestUtilities."
---
# aws-sam-local-testing
## Overview
AWS SAM Local is the canonical local-testing toolchain for AWS
Lambda. Per
[docs.aws.amazon.com/serverless-application-model](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/serverless-sam-cli-using-test.html),
it runs Lambdas in Docker containers locally with images that
mirror the Lambda runtime - same Linux, same Node/Python/Java
binaries, same handler-invocation contract.
## When to use
- Local unit + integration tests for Lambda handlers.
- Testing API Gateway + Lambda routing locally.
- Reproducing prod Lambda behaviour without deploying.
- Event-payload-driven tests (S3 event, SQS message, API GW
request).
## Authoring
### Install
```bash
brew install aws-sam-cli
sam --version # 1.x or higher
docker --version # Required for sam local
```
### Project structure
A SAM project has `template.yaml` declaring Lambda functions:
```yaml
AWSTemplateFormatVersion: '2010-09-09'
Transform: AWS::Serverless-2016-10-31
Resources:
HelloFunction:
Type: AWS::Serverless::Function
Properties:
CodeUri: src/
Handler: app.handler
Runtime: python3.12
Timeout: 10
MemorySize: 512
Events:
Api:
Type: Api
Properties:
Path: /hello
Method: GET
```
### Generate an event payload
Per SAM docs:
```bash
sam local generate-event apigateway aws-proxy --path /hello --method GET > event.json
sam local generate-event s3 put --bucket mybucket --key file.txt > s3-event.json
sam local generate-event sqs receive-message > sqs-event.json
```
### Single invocation
```bash
sam local invoke HelloFunction --event event.json
```
Output: handler's return value, plus the simulated Lambda runtime
log lines.
### Local API Gateway
```bash
sam local start-api --port 3000
```
Now `curl http://localhost:3000/hello` exercises the full
API Gateway → Lambda routing.
### Local Lambda invoke endpoint
```bash
sam local start-lambda --port 3001
```
Then point AWS SDK clients at `http://localhost:3001`:
```python
import boto3
lambda_client = boto3.client('lambda', endpoint_url='http://localhost:3001', region_name='us-east-1')
lambda_client.invoke(FunctionName='HelloFunction', Payload=b'{}')
```
Useful for testing **Lambda → Lambda** invocations end-to-end.
### .NET Lambdas - handler-direct testing
For C#/.NET Lambda handlers, prefer in-process handler-direct invocation
with `Amazon.Lambda.TestUtilities` (`TestLambdaContext`,
`TestLambdaLogger`) over per-test `sam local invoke` spawns - setup,
worked tests, and the dotnet-lambda CLI are in
[references/dotnet.md](references/dotnet.md).
### Integration with pytest
```python
import subprocess, json
def invoke_lambda(name, event):
proc = subprocess.run(
["sam", "local", "invoke", name, "--event", "-"],
input=json.dumps(event), text=True, capture_output=True,
)
return json.loads(proc.stdout)
def test_hello():
result = invoke_lambda("HelloFunction", {"name": "world"})
assert result["statusCode"] == 200
assert "Hello, world" in result["body"]
```
## Running
```bash
sam build # Package Lambdas
sam local invoke HelloFunction --event event.json
```
For watch-mode:
```bash
sam build --use-container --watch
```
## CI integration
```yaml
jobs:
sam-local-tests:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v5
- uses: aws-actions/setup-sam@v2
- run: sam build --use-container
- run: pytest tests/lambda/
```
## Anti-patterns
| Anti-pattern | Why it fails | Fix |
|---|---|---|
| Skip `sam build` between code changes | Stale package; old code runs | `sam build` (or watch mode) |
| `sam local invoke` for full-suite | Spawn cost per invocation; slow | `sam local start-lambda` once, invoke many |
| Compare local timing to prod | Docker overhead; cold-start model differs per `serverless-integration-test-builder` (its cold-start budget reference) | Test correctness locally; latency in prod |
| No event-payload generation | Hand-rolled events miss fields | `sam local generate-event` |
| Mock AWS SDK calls locally | Tests pass but prod IAM / endpoints fail | Use LocalStack or test against real low-cost AWS account |
| Skip API Gateway routing test | Lambda alone passes; API GW integration breaks | `sam local start-api` |
| Hardcoded path in test | OS-specific | Use generated events |
## Limitations
- **Docker overhead.** Cold starts in SAM Local are 5-15s
(Docker container spin-up); not representative of prod
cold-start budgets per `serverless-integration-test-builder` (its cold-start budget reference).
- **Doesn't test IAM.** Local invocations run with your AWS
CLI credentials, not the Lambda's role.
- **Doesn't test event-source mapping.** SQS / DynamoDB Streams /
EventBridge bindings are SAM-template-only locally.
- **VPC + private endpoints can't be simulated.** Local Lambdas
reach internet directly.
- **Pair with LocalStack** for fuller AWS-service emulation
([localstack.cloud](https://localstack.cloud/)).
## References
- AWS SAM docs:
[docs.aws.amazon.com/serverless-application-model](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/).
- SAM Local testing:
[docs.aws.amazon.com/serverless-application-model/latest/developerguide/serverless-sam-cli-using-test.html](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/serverless-sam-cli-using-test.html).
- `sam local generate-event`:
[docs.aws.amazon.com/serverless-application-model/latest/developerguide/sam-cli-command-reference-sam-local-generate-event.html](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/sam-cli-command-reference-sam-local-generate-event.html).
- .NET handler-direct testing:
[references/dotnet.md](references/dotnet.md).
- Companion catalog:
`serverless-integration-test-builder` (its cold-start budget reference: cold-start + timeout budgets).
- Sibling tools:
`cloudflare-workers-miniflare`,
`azure-functions-tests`.
- Builder:
`serverless-integration-test-builder`.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the work | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixes | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation code | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |