Testing functions
To test a function, you provide 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 to the
function.
-
Returns the function's result (the modified event object) along with any function
logs or error messages and the function's compute
utilization. The compute utilization is a number between 0 and 100 that
indicates the amount of time that the function took to run as a percentage of the
maximum allowed time. For example, a compute utilization of 35 means that the
function completed in 35% of the maximum allowed time.
Before you test a function, you must create the event
object to test it with. To create an event object, you have the following
options:
-
Use the visual editor in the CloudFront console. With the visual editor, you can create
event objects with a graphical interface and use them to test your function. After
you create an event object, you can also copy a JSON representation of the event
object to use for testing your function through other interfaces such as the AWS CLI
or CloudFront API. For more information, see the console tab at Testing functions.
-
Write the event object by hand in JSON format. For more information about the
structure of an event object, see Event structure.
When you create an event object for testing a function, you can omit the
distributionDomainName
, distributionId
, and
requestId
fields. Also, make sure the names of headers, cookies,
and query strings are lowercase.
You can test a function in the CloudFront console or with the
AWS CLI.
- Console
-
In the CloudFront console, you can create and save event objects with a graphical
interface (the visual editor) and use them to test your function. You can also
copy a JSON representation of the event object to use for testing your function
through other interfaces.
To create event objects and test a function (console)
-
If you haven't already done so, follow the steps to create a function.
To test a function, open the Functions page in
the CloudFront console at https://console.aws.amazon.com/cloudfront/v3/home#/functions, and then choose the function that
you want to test.
-
On the function page, choose the Test tab. Then
do the following:
-
Choose the Event type. If your function
modifies a request or generates a response based on the request,
choose Viewer Request. If it modifies a
response, choose Viewer Response.
-
Choose the Stage of the function that you
want to test, Development or
Live.
-
Scroll down to use the console's visual editor to create an event
object that represents an HTTP request or response that you want to
test. When you choose Viewer Response for
Event type, the visual editor adds fields so you
can test a response.
For the request, you can choose the request method, and enter a URI
path and a client IP address. To add query strings or request headers,
enter a key and a value, then choose Add.
For the response, you can add response headers and enter a response
status code and status description.
To see a JSON representation of your event object, choose the
JSON tab. You can copy the JSON representation of
the event object to use it for testing your function through other
interfaces such as the AWS CLI or CloudFront API.
The following images show the visual editor and the JSON view for the
same test event.
-
To test your function with the event object that you created, choose
Test event. The console shows the output of the
test, including function logs, query strings, and headers and cookies in
the request (and in the response, if applicable). It also shows the
compute utilization, which is a
number between 0 and 100 that indicates the amount of time that the
function took to run as a percentage of the maximum allowed time. For
example, a compute utilization of 35 means that the function completed
in 35% of the maximum allowed time. For more information, see Understanding compute utilization.
- CLI
-
After you create an event object, you can use it to test your function with
the aws cloudfront test-function command in the AWS CLI, as in
the following example. This example command uses an input file
(event-object.json
) to provide
the event object to the command. The following is an example of a simple event
object for testing, in the
event-object.json
file.
{
"version": "1.0",
"context": {
"eventType": "viewer-request"
},
"viewer": {
"ip": "198.51.100.11"
},
"request": {
"method": "GET",
"uri": "/example.png",
"headers": {
"host": {"value": "example.org"}
}
}
}
To use the following example command, do the following:
-
Replace ExampleFunction
with
the name of the function to test.
-
Replace ETVABCEXAMPLE
with the
ETag
value of the function whose code you're testing. To
get this value, you can use the aws cloudfront
describe-function command.
-
Replace event-object.json
with
the name of the file that contains the event object to test the function
with. Run the command from the same directory that contains this
file.
-
The following command tests the function in the
DEVELOPMENT
stage. If you want to test the function in the
LIVE
stage instead, replace DEVELOPMENT
with
LIVE
.
-
Run the command on one line. In the example, line breaks are provided
to make the example more readable.
aws cloudfront test-function \
--name ExampleFunction
\
--if-match ETVABCEXAMPLE
\
--event-object fileb://event-object.json
--stage DEVELOPMENT
When the command is successful, you see output like the following that shows
the result of testing the function.
The following output is formatted as a YAML string. This feature is only
available in version 2 of the AWS CLI. For more information, see
Setting the AWS CLI output format in the AWS Command Line Interface User Guide.
Note the following about the output:
-
FunctionSummary
describes the function that was
tested.
-
FunctionExecutionLogs
contains a list of log lines that
the function wrote in console.log()
statements (if
any).
-
ComputeUtilization
contains a number between 0 and 100
that indicates the amount of time that the function took to run as a
percentage of the maximum allowed time. For example, a compute
utilization of 35 means that the function completed in 35% of the
maximum allowed time. For more information, see Understanding compute utilization.
-
If the function failed, FunctionErrorMessage
contains the
error message.
-
FunctionOutput
contains the event object that the
function returned. The following output shows that the function returned
a response with HTTP status code 302 (Found)
, a
Location
header with the value
https://aws.amazon.com/cloudfront/
, and a
Cloudfront-Functions
header with the value
generated-by-CloudFront-Functions
.
TestResult:
ComputeUtilization: '21'
FunctionErrorMessage: ''
FunctionExecutionLogs: []
FunctionOutput: '{"response":{"headers":{"cloudfront-functions":{"value":"generated-by-CloudFront-Functions"},"location":{"value":"https://aws.amazon.com/cloudfront/"}},"statusDescription":"Found","cookies":{},"statusCode":302}}'
FunctionSummary:
FunctionConfig:
Comment: Example function
Runtime: cloudfront-js-1.0
FunctionMetadata:
CreatedTime: '2021-04-18T20:38:56.915000+00:00'
FunctionARN: arn:aws:cloudfront::111122223333:function/ExampleFunction
LastModifiedTime: '2021-04-18T20:38:57.057000+00:00'
Stage: DEVELOPMENT
Name: ExampleFunction
Status: UNPUBLISHED
Understanding 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.