{"id":17070661,"url":"https://github.com/paulhammond/cftest","last_synced_at":"2026-05-06T20:38:18.732Z","repository":{"id":66575674,"uuid":"406119444","full_name":"paulhammond/cftest","owner":"paulhammond","description":"A test utility for Cloudfront Functions","archived":false,"fork":false,"pushed_at":"2024-06-04T23:21:24.000Z","size":31,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-01-28T17:27:13.680Z","etag":null,"topics":["aws","cloudfront","cloudfront-functions","testing-tools"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/paulhammond.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-09-13T20:27:16.000Z","updated_at":"2024-10-17T22:31:06.000Z","dependencies_parsed_at":null,"dependency_job_id":"9e9c176e-37b2-4ae5-b3fd-5c688625fbeb","html_url":"https://github.com/paulhammond/cftest","commit_stats":null,"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/paulhammond%2Fcftest","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/paulhammond%2Fcftest/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/paulhammond%2Fcftest/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/paulhammond%2Fcftest/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/paulhammond","download_url":"https://codeload.github.com/paulhammond/cftest/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245090875,"owners_count":20559298,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["aws","cloudfront","cloudfront-functions","testing-tools"],"created_at":"2024-10-14T11:32:46.894Z","updated_at":"2026-05-06T20:38:18.684Z","avatar_url":"https://github.com/paulhammond.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# cftest\n\ncftest is a utility to run tests against [Cloudfront Functions][].\n\nAmazon helpfully provides a [Cloudfront TestFunction API][testfunction], which\nallows you to get the output from running a Cloudfront Function with provided\ninput values. However that API (and the associated\n`aws cloudfront test-function` command line tool) do not provide the ability to\neasily test a function with multiple inputs and ensure all of them generate the\nexpected outputs. That's where cftest comes in.\n\n[Cloudfront functions]: https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/cloudfront-functions.html\n[testfunction]: https://docs.aws.amazon.com/cloudfront/latest/APIReference/API_TestFunction.html\n\n## Installation\n\nPrebuilt binaries can be downloaded from from\n[Github Releases](https://github.com/paulhammond/cftest/releases)\n\n## Usage\n\ncftest works with a directory of JSON files. Each one is a separate test case\nand specifies the input event and the expected output. Both are specified using\nthe [Cloudfront Function event structure][event]. For example the following\nfile specifies that a request to `/` should be redirected to `/foo`\n\n```json\n{\n  \"event\": {\n    \"request\": {\n      \"method\": \"GET\",\n      \"uri\": \"/\",\n      \"querystring\": {},\n      \"headers\": {\n        \"host\": {\n          \"value\": \"example.com\"\n        }\n      },\n      \"cookies\": {}\n    }\n  },\n\n  \"output\": {\n    \"response\": {\n      \"headers\": {\n        \"location\": {\n          \"value\": \"https://example.com/foo\"\n        }\n      },\n      \"statusDescription\": \"Found\",\n      \"cookies\": {},\n      \"statusCode\": 302\n    }\n  }\n}\n```\n\nOnce you have a set of files and a cloudfront function, you can pass both to\ncftest as arguments:\n\n```\ncftest myfunction:DEVELOPMENT tests/one.json tests/two.json\n```\n\nYou can test both the `LIVE` or `DEVELOPMENT` stage of your function.\n\ncftest uses the same authentication mechanisms as other AWS tools, including\ninstance roles, ~/.aws files and associated environment variables.\n\n[event]: https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/functions-event-structure.html\n\n### Checking errors\n\nCloudfront functions can return two kinds of errors. The first is a HTTP error\nwith a code, such as \"404 Not Found\". The second is a thrown error. cftest can\ntest both.\n\nTo test a function returns a HTTP error, check the output matches the expected\nHTTP response. For example:\n\n```json\n{\n  \"event\": {…},\n\n  \"output\": {\n    \"response\": {\n      \"headers\": {},\n      \"statusDescription\": \"Not Found\",\n      \"cookies\": {},\n      \"statusCode\": 404\n    }\n  }\n}\n```\n\nTo test for a thrown error, specify an `error` instead of an `output`. For\nexample:\n\n```json\n{\n  \"event\": {…},\n  \"error\": \"My thrown error\"\n}\n```\n\n### Checking response body data\n\nCloudfront functions can return a response that includes a\n[generated body][body]. The data for these can be large and repetitive, so\ncftest gives you the option of testing for just the existence of body data\nwithout requiring a full string match.\n\nYou can do this by specifying `true` as the value of the `data` attribute. For\nexample:\n\n```json\n{\n  \"event\": {…},\n\n  \"output\": {\n    \"response\": {\n      \"headers\": {},\n      \"statusCode\": 200,\n      \"statusDescription\": \"OK\",\n      \"body\": {\n        \"encoding\": \"text\",\n        \"data\": true\n      }\n    }\n  }\n}\n```\n\nIf your function returns a body as a simple string then the underlying\n[testing APIs][testfunction] used by cftest will convert that string into a full\nobject with `encoding` and `data` attributes, so your test file will also need\nto use that longer syntax.\n\n[body]: https://aws.amazon.com/about-aws/whats-new/2023/03/http-status-response-generation-cloudfront-functions/\n\n## License\n\ncftest is licensed under the [MIT license](LICENSE). For information on the\nlicenses of all included modules run `cftest --credits`.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpaulhammond%2Fcftest","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpaulhammond%2Fcftest","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpaulhammond%2Fcftest/lists"}