Testing functions - Amazon CloudFront
Set up the event objectTest the functionUnderstanding compute utilization
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Testing functions

You can test a CloudFront Function to make sure that it works as intended before you deploy the function to the live stage (production). 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:

  1. Runs the function, using the provided event object as input.

  2. 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 Understanding 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 Amazon 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 using option 1 or 2

  1. Display the Functions page in the CloudFront console and choose the function that you want to test.

  2. On the function details page, choose the Test tab. The Test function section appears with buttons that include Edit JSON and Test function.

  3. Complete Event type:

    • Choose Viewer request if the function modifies an HTTP request or generates a response based on the request. The Request section, which is already displayed applies to this type.

    • Or choose Viewer response. The Request section, which is already displayed, applies to this type. In addition, the Response section appears.

  4. Complete all the fields that you want to include in the event. As you work, you can choose Edit JSON to view the raw JSON.

  5. Save the event, if you want to.

    You can also choose Edit JSON and copy the raw JSON, and save it in your own file, outside of CloudFront.

To create using option 3

Create the event object using a text editor. Store the file in a directory that your computer can connect to.

Makes sure that you follow these guidelines:

  • Omit the distributionDomainName, distributionId, and requestId fields.

  • Make sure that the names of headers, cookies, and query strings are 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 detailed 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 Amazon CLI.

Console

In the CloudFront console, you can test a function that you have created using the console.

To test the function

  1. Display the Functions page in the CloudFront console and choose the function that you want to test.

  2. On the function page, choose the Test tab. The Test function section appears with buttons that include Edit JSON and Test function.

  3. Make sure that the correct event is displayed.

    If you want to switch from the currently displayed event, choose another event in the Select test event field.

  4. Choose the Test function button. The console shows the output of the function, including function logs. It also shows the compute utilization. For more information, see Understanding compute utilization.

CLI

You can test a function using the aws cloudfront test-function command.

  1. Run the command as shown in the example. Run the command from the same directory that contains this file.

    This example uses the fileb:// notation to pass in the event object file. It also includes line breaks to make the command more readable. 

aws cloudfront test-function \
    --name MaxAge \
    --if-match ETVABCEXAMPLE \
    --event-object fileb://event-maxage-test01.json \
    --stage DEVELOPMENT

Notes:

  • You reference the function by its name and ETag (in the if-match parameter). You reference the event object by its location in your file system.

  • The stage can be DEVELOPMENT or LIVE.

When the command is successful, you see output like the following.

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: MaxAge function
      Runtime: cloudfront-js-2.0
      KeyValueStoreAssociations= \
      {Quantity=1, \
      Items=[{KeyValueStoreARN='arn:aws:cloudfront::111122223333:key-value-store/a1b2c3d4-5678-90ab-cdef-EXAMPLE11111'}]} \
    FunctionMetadata:
      CreatedTime: '2021-04-18T20:38:56.915000+00:00'
      FunctionARN: arn:aws:cloudfront::111122223333:function/MaxAge
      LastModifiedTime: '2023-17-20T10:38:57.057000+00:00'
      Stage: DEVELOPMENT
    Name: MaxAge
    Status: UNPUBLISHED
Notes

  • FunctionExecutionLogs contains a list of log lines that the function wrote in console.log() statements (if any).

  • ComputeUtilization. See Understanding compute utilization.

  • FunctionOutput contains the event object that the function returned.

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.