Using Event Inputs
The stackery local invoke
command allows you to run your serverless functions locally. For functions with inputs such as API Gateway events, other functions, tables, and so on, running your function against actual input data is crucial. The Stackery CLI includes several flags as well as the pluck-event
command that allows you to input or generate events as you run your functions locally.
Using an Event Input
The stackery local invoke
command includes three flags that allow you to input events:
--input
--input-file
--stdin
These allow you to input an event when invoking your function.
In addition, the stackery pluck-event
command allows you to get the most recent event from the CloudWatch logs, which can then be used with the above flags.
Passing an event string
The simplest way to pass an event into your function is by using the --input
flag followed by a JSON object as a string. Here's an example:
stackery local invoke --stack-name local-demo --env-name test --function-id getEvent --input '{ "Stackery": "is awesome!" }'
This would be the result:
Passing an event file
It would be tedious to paste in most input events as strings like in the example above. That's where the --input-file
flag comes in.
In our local-demo
example, the getEvent
function is connected to an API Gateway. An easy way to replicate an API Gateway event is to trigger the function in Stackery, and then copy the event output from the CloudWatch logs.
- In the Stackery Dashboard, in your stack's View tab, double-click the
restApi
node - Click on its Stage Location to open that link in a new tab
The page that opens is blank, but clicking the link will have triggered the deployed version of the getEvent
function.
- Double-click the
getEvent
node in the Dashboard - Scroll down a bit until you see the Metrics & Logs section. Click on
Logs
- In the CloudWatch page that opens, you'll see a record that looks like this:
- Copy the object that's output and paste it the following file:
local-demo/src/getEvent/event.json
For an example output, see event.json in our sample repo.
- Run the command:
stackery local invoke --stack-name local-demo --env-name test --function-id getEvent --aws-profile <your-profile-name> --input-file 'src/getEvent/event.json'
You should see your sample event logged locally:
The path to the input file needs to be relative to the location of your
template.yaml
file. It should also be in quotes, as the command expects a string as the argument.
Plucking a recent event
If you have manually triggered an event as in the first two steps in the above instructions, the stackery pluck-event
command can save you the trouble of completing steps 3-6.
The stackery pluck-event
command takes the single most recent event from your function's CloudWatch logs and prints it on the command line, which allows you to either copy the event to a file manually, or write it to an event file when the command is run.
Run this command to get the latest event from the local-demo
stack and write it to a file called event.json
, located in that function's directory:
stackery pluck-event --stack-name local-demo --env-name test --function-id getEvent --aws-profile <your-profile-name> > src/getEvent/event.json
Then, you would invoke that function as you did above, using the generated event.json
file:
stackery local invoke --stack-name local-demo --env-name test --function-id getEvent --aws-profile <your-profile-name> --input-file 'src/getEvent/event.json'
Note that the
pluck-event
command will fail if no event has been generated in the previous 48 hours, or if your function has additionalconsole.log()
or print statements other than the one logging the event.
The default event window is 48 hours, but you can expand or narrow that window by passing in the --since
flag.
pluck-event
Event not found error when running Running pluck-event
on a function will fail if you have console.log()
or print statements before the event you are trying to pluck. This command works best on the starter function that is generated when your function resource is initially created in Stackery.
Passing in standard input
The final way of passing in an input event is using the --stdin
flag. Like --input
, --stdin
takes JSON strings as inputs, and may be a useful option for running unit tests.
Generating an event with SAM local
The SAM CLI has a generate-event
command as well. Read more about sam local generate-event
in the AWS docs.