Introduction to testing with sam local generate-event
Use the AWS Serverless Application Model Command Line Interface (AWS SAM CLI) sam local generate-event
subcommand to generate
event payload samples for supported AWS services. You can then modify and pass these events to local resources for
testing.
-
For an introduction to the AWS SAM CLI, see What is the AWS SAM CLI?
-
For a list of
sam local generate-event
command options, see sam local generate-event.
An event is a JSON object that gets generated when an AWS service performs an action or task. These events contain specific information, such as the data that was processed or the timestamp of the event. Most AWS services generate events and each service’s events are formatted uniquely for its service.
Events generated by one service are passed to other services as an event source. For example, an item placed in an Amazon Simple Storage Service (Amazon S3) bucket can generate an event. This event can then be used as the event source for an AWS Lambda function to process the data further.
Events that you generate with sam local generate-event
are formatted in the same structure as the actual
events created by the AWS service. You can modify the contents of these events and use them to test resources
in your application.
To use sam local generate-event
, install the AWS SAM CLI by completing the following:
Before using sam local generate-event
, we recommend a basic understanding of the following:
Generate sample events
Use the AWS SAM CLI sam local generate-event
subcommand to generate events for supported
AWS services.
To see a list of supported AWS services
-
Run the following:
$
sam local generate-event
-
The list of supported AWS services will display. The following is an example:
$
sam local generate-event
... Commands: alb alexa-skills-kit alexa-smart-home apigateway appsync batch cloudformation ...
To generate a local event
-
Run
sam local generate-event
and provide the supported service name. This will display a list of event types that you can generate. The following is an example:$
sam local generate-event
Usage: sam local generate-event s3 [OPTIONS] COMMAND [ARGS]... Options: -h, --help Show this message and exit. Commands: batch-invocation Generates an Amazon S3 Batch Operations Invocation Event delete Generates an Amazon S3 Delete Event put Generates an Amazon S3 Put Events3
-
To generate the sample event, run
sam local generate-event
, providing the service and event type.$
sam local generate-event
<service>
<event>
The following is an example:
$
sam local generate-event
{ "Records": [ { "eventVersion": "2.0", "eventSource": "aws:s3", "awsRegion": "us-east-1", "eventTime": "1970-01-01T00:00:00.000Z", "eventName": "ObjectCreated:Put", "userIdentity": { "principalId": "EXAMPLE" }, "requestParameters": { "sourceIPAddress": "127.0.0.1" }, "responseElements": { "x-amz-request-id": "EXAMPLE123456789", "x-amz-id-2": "EXAMPLE123/5678abcdefghijklambdaisawesome/mnopqrstuvwxyzABCDEFGH" }, "s3": { "s3SchemaVersion": "1.0", "configurationId": "testConfigRule", "bucket": { "name": "example-bucket", "ownerIdentity": { "principalId": "EXAMPLE" }, "arn": "arn:aws:s3:::example-bucket" }, "object": { "key": "test/key", "size": 1024, "eTag": "0123456789abcdef0123456789abcdef", "sequencer": "0A1B2C3D4E5F678901" } } } ] }s3 put
These sample events contain placeholder values. You can modify these values to reference actual resources in your application or values to help with local testing.
To modify a sample event
-
You can modify sample events at the command prompt. To see your options, run the following:
$
sam local generate-event
<service>
<event>
--helpThe following is an example:
$
sam local generate-event
Usage: sam local generate-event s3 put [OPTIONS] Options: --region TEXT Specify the region name you'd like, otherwise the default = us-east-1 --partition TEXT Specify the partition name you'd like, otherwise the default = aws --bucket TEXT Specify the bucket name you'd like, otherwise the default = example-bucket --key TEXT Specify the key name you'd like, otherwise the default = test/key --debug Turn on debug logging to print debug message generated by AWS SAM CLI and display timestamps. --config-file TEXT Configuration file containing default parameter values. [default: samconfig.toml] --config-env TEXT Environment name specifying default parameter values in the configuration file. [default: default] -h, --help Show this message and exit.s3
put
--help -
Use any of these options at the command prompt to modify your sample event payload. The following is an example:
$
sam local generate-event
{ "Records": [ { "eventVersion": "2.0", "eventSource": "aws:s3", "awsRegion": "us-east-1", "eventTime": "1970-01-01T00:00:00.000Z", "eventName": "ObjectCreated:Put", "userIdentity": { "principalId": "EXAMPLE" }, "requestParameters": { "sourceIPAddress": "127.0.0.1" }, "responseElements": { "x-amz-request-id": "EXAMPLE123456789", "x-amz-id-2": "EXAMPLE123/5678abcdefghijklambdaisawesome/mnopqrstuvwxyzABCDEFGH" }, "s3": { "s3SchemaVersion": "1.0", "configurationId": "testConfigRule", "bucket": { "name":s3 put--bucket MyBucket
"MyBucket"
, "ownerIdentity": { "principalId": "EXAMPLE" }, "arn": "arn:aws:s3:::MyBucket" }, "object": { "key": "test/key", "size": 1024, "eTag": "0123456789abcdef0123456789abcdef", "sequencer": "0A1B2C3D4E5F678901" } } } ] }
Use generated events for local testing
Save your generated events locally and use other sam local
subcommands to test.
To save your generated events locally
-
Run the following:
$
sam local generate-event
<service> <event> <event-option>
><filename.json>
The following is an example of an event being saved as an
s3.json
file in theevents
folder of our project.sam-app$
sam local generate-event
s3 put --bucket MyBucket
>events/s3.json
To use a generated event for local testing
-
Pass the event with other
sam local
subcommands by using the--event
option.The following is an example of using the
s3.json
event to invoke our Lambda function locally:sam-app$
sam local invoke --event
Invoking src/handlers/s3-json-logger.s3JsonLoggerHandler (nodejs18.x) Local image is up-to-date Using local image: public.ecr.aws/lambda/nodejs:18-rapid-x86_64. Mounting /Users/.../sam-app/.aws-sam/build/S3JsonLoggerFunction as /var/task:ro,delegated, inside runtime container START RequestId: f4f45b6d-2ec6-4235-bc7b-495ec2ae0128 Version: $LATEST END RequestId: f4f45b6d-2ec6-4235-bc7b-495ec2ae0128 REPORT RequestId: f4f45b6d-2ec6-4235-bc7b-495ec2ae0128 Init Duration: 1.23 ms Duration: 9371.93 ms Billed Duration: 9372 ms Memory Size: 128 MB Max Memory Used: 128 MBevents/s3.json S3JsonLoggerFunction
Learn more
For a list of all sam local generate-event
options, see
sam local
generate-event.
For a demo of using sam local
, see AWS SAM for local development. Testing AWS Cloud resources from local
development environments