cftest

cftest is a utility to run tests against Cloudfront Functions.

Amazon helpfully provides a Cloudfront TestFunction API, which allows you to get the output from running a Cloudfront Function with provided input values. However that API (and the associated aws cloudfront test-function command line tool) do not provide the ability to easily test a function with multiple inputs and ensure all of them generate the expected outputs. That's where cftest comes in.

Installation

Prebuilt binaries can be downloaded from from Github Releases

Usage

cftest works with a directory of JSON files. Each one is a separate test case and specifies the input event and the expected output. Both are specified using the Cloudfront Function event structure. For example the following file specifies that a request to / should be redirected to /foo

{
  "event": {
    "request": {
      "method": "GET",
      "uri": "/",
      "querystring": {},
      "headers": {
        "host": {
          "value": "example.com"
        }
      },
      "cookies": {}
    }
  },

  "output": {
    "response": {
      "headers": {
        "location": {
          "value": "https://example.com/foo"
        }
      },
      "statusDescription": "Found",
      "cookies": {},
      "statusCode": 302
    }
  }
}

Once you have a set of files and a cloudfront function, you can pass both to cftest as arguments:

cftest myfunction:DEVELOPMENT tests/one.json tests/two.json

You can test both the LIVE or DEVELOPMENT stage of your function.

cftest uses the same authentication mechanisms as other AWS tools, including instance roles, ~/.aws files and associated environment variables.

Checking errors

Cloudfront functions can return two kinds of errors. The first is a HTTP error with a code, such as "404 Not Found". The second is a thrown error. cftest can test both.

To test a function returns a HTTP error, check the output matches the expected HTTP response. For example:

{
  "event": {…},

  "output": {
    "response": {
      "headers": {},
      "statusDescription": "Not Found",
      "cookies": {},
      "statusCode": 404
    }
  }
}

To test for a thrown error, specify an error instead of an output. For example:

{
  "event": {…},
  "error": "My thrown error"
}

Checking response body data

Cloudfront functions can return a response that includes a generated body. The data for these can be large and repetitive, so cftest gives you the option of testing for just the existence of body data without requiring a full string match.

You can do this by specifying true as the value of the data attribute. For example:

{
  "event": {…},

  "output": {
    "response": {
      "headers": {},
      "statusCode": 200,
      "statusDescription": "OK",
      "body": {
        "encoding": "text",
        "data": true
      }
    }
  }
}

If your function returns a body as a simple string then the underlying testing APIs used by cftest will convert that string into a full object with encoding and data attributes, so your test file will also need to use that longer syntax.

License

cftest is licensed under the MIT license. For information on the licenses of all included modules run cftest --credits.