{"id":13479450,"url":"https://github.com/dempfi/ava-playback","last_synced_at":"2025-08-20T06:31:55.878Z","repository":{"id":52004441,"uuid":"90441063","full_name":"dempfi/ava-playback","owner":"dempfi","description":"📼 🚀 Record and playback http requests from your ava tests","archived":false,"fork":false,"pushed_at":"2022-12-07T09:16:23.000Z","size":85,"stargazers_count":124,"open_issues_count":10,"forks_count":6,"subscribers_count":4,"default_branch":"master","last_synced_at":"2024-12-06T14:50:46.266Z","etag":null,"topics":["ava","http-mock","http-mocking","javascript","mock","nodejs","testing","testing-tools","vcr"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/dempfi.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}},"created_at":"2017-05-06T06:00:40.000Z","updated_at":"2024-01-09T10:25:20.000Z","dependencies_parsed_at":"2023-01-24T15:31:00.334Z","dependency_job_id":null,"html_url":"https://github.com/dempfi/ava-playback","commit_stats":null,"previous_names":[],"tags_count":13,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dempfi%2Fava-playback","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dempfi%2Fava-playback/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dempfi%2Fava-playback/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dempfi%2Fava-playback/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dempfi","download_url":"https://codeload.github.com/dempfi/ava-playback/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":230400606,"owners_count":18219830,"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":["ava","http-mock","http-mocking","javascript","mock","nodejs","testing","testing-tools","vcr"],"created_at":"2024-07-31T16:02:16.340Z","updated_at":"2024-12-19T08:07:43.903Z","avatar_url":"https://github.com/dempfi.png","language":"TypeScript","funding_links":[],"categories":["TypeScript"],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\u003cimg src=\"http://i.imgur.com/1vrCZff.png\" width=\"360\"/\u003e\u003c/p\u003e\n\n___\n\nDealing with HTTP requests in the tests can be painful and what is more important error prone, since we have to stub everything by hand. There are few libraries to help with this situation, like [node-nock](https://github.com/node-nock/nock). But their setup is something complicated (I didn't manage to setup [node-nock](https://github.com/node-nock/nock) to record requests and play them back) and they require a lot of manual steps to write single test.\n\n📼 **`ava-playback`** is here to help. In `record` mode, when you write your test, you just allow your app to call real APIs and when you ready, you just switch from `record` to playback mode and it's done 🎉. In background `ava-playback` will record new requests and use already existing playbacks for the rest.\n\n\n### Installation\nFirst things first\n\n```\nyarn add ava-playback\n```\n\nor\n\n```\nnpm i ava-playback --save\n```\n\nThen in you `package.json` where you store your ava config just add a requirement of `ava-playback`.\n\n```json\n  // ...\n  \"ava\": {\n    \"require\": [\n      \"ava-playback\"\n    ]\n  }\n  // ...\n```\n\n🎉 that's it.\n\n### Playbacks location\n\nBy default playbacks will be stored in the root of your project in `/playbacks` folder, if you want to change the location just add `playbacks` settings in your `package.json`.\n\n```json\n  // ...\n  \"ava\": {\n    \"require\": [\n      \"ava-playback\"\n    ],\n    \"playbacks\": \"tests/fixtures\"\n  },\n  // ...\n```\n\n### Modes\n`ava-playback` uses env variable `AVA_PLAYBACK` to get information how it should run. If `AVA_PLAYBACK` isn't set, `ava-playback` will not do anything.\n\n- `AVA_PLAYBACK=record` record all new outgoing requests from your tests\n- `AVA_PLAYBACK=play` turn off HTTP/HTTPS connection and use playbacks to reply to the outgoing requests from the tests\n\n### Usage\n\nWith `ava-playback` the flow of writing actual test can look like this.\n\n1. You write a new test and don't activate `ava-playback` in any mode.\n2. When the test is ready you run it one more time with `AVA_PLAYBACK=record` env variable. `ava-playback` will record only missing playbacks to playbacks location.\n3. You edit new playbacks according to your needs ([wildcard](#wildcards-and-security) auth tokens in the body or in the queries).\n4. Check all tests with `AVA_PLAYBACK=play` mode to verify they pass.\n5. Done 🚀\n\nTo illustrate the flow take a look at this example\n\n```sh\n# Write new test file\nNODE_ENV=test ava --watch 'new-test-file.js'\n\n# Record all playbacks required for 'new-test-file.js'\nNODE_ENV=test AVA_PLAYBACK=record ava 'new-test-file.js'\n\n# Check all tests together\nNODE_ENV=test AVA_PLAYBACK=play ava\n```\n\n### Wildcards and security\n\nBy default `ava-playback` stores and plays back your requests by taking into account all queries and body. However, you can change this option to hide security information, like tokens in queries.\n\nFor example, Slack API allows tokens to be in query params, like `slack.com/api/users.list?token=xoxb-XXXXXXXXXX-Z7RKNoLIKOXLPKqtxUy5IhJ5`. It's totally fine unless you don't want this token to be stored in git or be available in Travis-ci. For those cases, you can use wildcards feature of `ava-playback`.\n\nAfter recording the playback, in you playbacks folder you can find the file matching that request and edit a `path` entry from\n\n```\n\"/api/users.list?token=xoxb-XXXXXXXXXX-Z7RKNoLIKOXLPKqtxUy5IhJ5\"\n```\n\nto\n\n```\n\"/api/users.list?token=*\"\n```\n\nso the file will look like this\n```json\n{\n  \"body\": \"\",\n  \"method\": \"POST\",\n  \"path\": \"/api/users.list?token=*\",\n  \"scope\": \"https://slack.com:443\",\n  \"status\": 200,\n}\n```\n\nand all future requests to slack API with anything in place of the actual token will be caught by `ava-playback`.\n\n\u003cdetails\u003e\n  \u003csummary\u003e\u003cstrong\u003eWildcard substitution rules\u003c/strong\u003e\u003c/summary\u003e\n  \u003cp\u003e\n\n`ava-playback` support wildcards only for queries, however, this may change over. Wildcards can only catch whole strings as values or as part of an array like in the examples below.\n\nWhole word match\n```js\n\"/api/users.list?token=*\"\n```\nwill match these paths\n```\n\"/api/users.list?token=34\"\n\"/api/users.list?token=xoxb-XXXXXXXXXX-Z7RKNoLIKOXLPKqtxUy5IhJ5\"\n```\n\nIn array match\n```js\n\"/api/users.list?tokens=78\u0026tokens=*\u0026tokens=some-token\"\n```\nwill match anything in the same position, like\n```js\n\"/api/users.list?tokens=78\u0026tokens=anything-here\u0026tokens=some-token\"\n```\n\u003c/p\u003e\u003c/details\u003e\n\n\n\u003cdiv align=\"right\"\u003e\u003csup\u003e\n  made with ❤️ by \u003ca href=\"https://github.com/dempfi\"\u003e@dempfi\u003c/a\u003e\n\u003c/sup\u003e\u003c/div\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdempfi%2Fava-playback","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdempfi%2Fava-playback","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdempfi%2Fava-playback/lists"}