Test functions
Before you deploy the function to the live stage (production), you can test your function to verify that it works as intended. To test a function, you specify an event object that represents an HTTP request or response that your CloudFront distribution could receive in production.
CloudFront Functions does the following:
-
Runs the function, using the provided event object as input.
-
Returns the function's result (the modified event object) along with any function logs or error messages and the function's compute utilization. For more information about compute utilization, see Understand compute utilization.
Set up the event object
Before you test a function, you must set up the event object to test it with. There are several options.
- Option 1: Set up an event object without saving it
-
You can set up an event object in the visual editor in the CloudFront console and not save it.
You can use this event object to test the function from the CloudFront console, even though it's not saved.
- Option 2: Create an event object in the visual editor
-
You can set up an event object in the visual editor in the CloudFront console and not save it. You can create 10 event objects for each function so that you can, for example, test different possible inputs.
When you create the event object in this way, you can use the event object to test the function in the CloudFront console. You can't use it to test the function using an AWS API or SDK.
- Option 3: Create an event object using a text editor
-
You can use a text editor to create an event object in JSON format. For information about the structure of an event object, see Event structure.
You can use this event object to test the function using the CLI. But you can't use it to test the function in the CloudFront console.
To create an event object (option 1 or 2)
-
Sign in to the CloudFront console at https://console.aws.amazon.com/cloudfront/v4/home#/functions
and choose the Functions page. Choose the function that you want to test.
-
On the function details page, choose the Test tab.
-
For Event type, choose one of the following options:
-
Choose Viewer request if the function modifies an HTTP request or generates a response based on the request. The Request section appears.
-
Choose Viewer response. The Request and the Response sections appear.
-
-
Complete the fields to include in the event. You can choose Edit JSON to view the raw JSON.
-
(Optional) To save the event, choose Save and in the Save test event, enter a name and then choose Save.
You can also choose Edit JSON and copy the raw JSON, and save it in your own file, outside of CloudFront.
To create an event object (option 3)
Create the event object using a text editor. Store the file in a directory that your computer can connect to.
Verify that you follow these guidelines:
-
Omit the
distributionDomainName
,distributionId
, andrequestId
fields. -
The names of headers, cookies, and query strings must be lowercase.
One option for creating an event object in this way is to create a sample using the visual editor. You can be sure that the sample is correctly formatted. You can then copy the raw JSON and paste it into a text editor and save the file.
For more information about the structure of an event, see Event structure.
Test the function
You can test a function in the CloudFront console or with the AWS Command Line Interface (AWS CLI).
Notes
-
FunctionExecutionLogs
contains a list of log lines that the function wrote inconsole.log()
statements (if any). -
ComputeUtilization
contains information about running your function. See Understand compute utilization. -
FunctionOutput
contains the event object that the function returned.
Understand compute utilization
Compute utilization is the amount of time that the function took to run as a percentage of the maximum allowed time. For example, a value of 35 means that the function completed in 35% of the maximum allowed time.
If a function continuously exceeds the maximum allowed time, CloudFront throttles the function. The following list explains the likelihood of a function getting throttled based on the compute utilization value.
Compute utilization value:
-
1 – 50 – The function is comfortably below the maximum allowed time and should run without throttling.
-
51 – 70 – The function is nearing the maximum allowed time. Consider optimizing the function code.
-
71 – 100 – The function is very close to or exceeds the maximum allowed time. CloudFront is likely to throttle this function if you associate it with a distribution.