{"id":16292469,"url":"https://github.com/exogen/ava-nock","last_synced_at":"2025-07-28T12:35:16.963Z","repository":{"id":39801137,"uuid":"109762237","full_name":"exogen/ava-nock","owner":"exogen","description":"Like AVA snapshots but for HTTP requests. Drop-in, zero-config record \u0026 replay!","archived":false,"fork":false,"pushed_at":"2023-01-07T04:13:57.000Z","size":1232,"stargazers_count":7,"open_issues_count":10,"forks_count":3,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-03-16T14:53:56.620Z","etag":null,"topics":["ava","http","mocking","nock","record","testing","vcr"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","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/exogen.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-11-06T23:30:21.000Z","updated_at":"2022-12-07T16:06:48.000Z","dependencies_parsed_at":"2023-02-06T11:30:59.661Z","dependency_job_id":null,"html_url":"https://github.com/exogen/ava-nock","commit_stats":null,"previous_names":[],"tags_count":14,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/exogen%2Fava-nock","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/exogen%2Fava-nock/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/exogen%2Fava-nock/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/exogen%2Fava-nock/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/exogen","download_url":"https://codeload.github.com/exogen/ava-nock/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244543734,"owners_count":20469552,"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","mocking","nock","record","testing","vcr"],"created_at":"2024-10-10T20:06:50.568Z","updated_at":"2025-03-20T03:30:50.857Z","avatar_url":"https://github.com/exogen.png","language":"JavaScript","readme":"# ava-nock\n\nDrop-in, zero-config HTTP record \u0026 replay for\n[AVA](https://github.com/avajs/ava)!\n\nInstall with npm:\n\n```console\n$ npm install ava-nock --save-dev\n```\n\nInstall with Yarn:\n\n```console\n$ yarn add ava-nock --dev\n```\n\n## Features\n\n- It just works: call the setup function and you’re good to go, requiring no\n  changes to your tests.\n- Strict isolation of HTTP calls per test so you can be certain of exactly what\n  each test does.\n- Recorded fixtures can filter out sensitive values like API keys, auth tokens,\n  passwords, etc.\n- Compatible with any HTTP client.\n\n## How it works\n\nThere are generally two approaches to mocking HTTP requests when we don’t\ncontrol or can’t manually mock the code that makes the request: either use a\nproxy to fulfill requests (this requires starting a server and being able to\nchange your request code to point to it), or intercept the host language’s\nunderlying code for sending requests. Libraries like\n[yakbak](https://github.com/flickr/yakbak) use the former, while libraries like\n[VCR](https://github.com/vcr/vcr), [Nock](https://github.com/node-nock/nock),\nand [Sepia](https://github.com/linkedin/sepia) use the latter. As the name\nimplies, ava-nock uses Nock.\n\nLikewise, there are multiple levels of granularity at which to capture requests.\nOne approach is to generate a hash for each request and serve the same response\nany time a matching request is made throughout the entire test suite. Another\napproach is to isolate the specific requests made in each test. This library\ncurrently uses the latter approach, so that each test’s requests are completely\nisolated from one another.\n\n## Usage\n\nImport and run the `setupTests()` function in any test files that make network\nrequests. This function will add `beforeEach`, `afterEach`, and\n`afterEach.always` hooks that manage Nock fixtures for you.\n\n```js\nimport test from 'ava';\nimport fetch from 'isomorphic-fetch';\nimport { setupTests } from 'ava-nock';\n\nsetupTests();\n\ntest('using fetch to get JSON', async (t) =\u003e {\n  const response = await fetch(\n    'https://musicbrainz.org/ws/2/artist/c8da2e40-bd28-4d4e-813a-bd2f51958ba8?fmt=json'\n  );\n  const data = await response.json();\n  t.is(data.name, 'Lures');\n});\n```\n\nFixtures behave similarly to AVA snapshots: they are stored in a `.nock` file\nalongside snapshots, named after the test file that generated them. Within each\nfixture, each test’s requests and responses are stored for later playback.\n\nNote that due to the way Nock works by globally intercepting requests to the\n`http` and `https` modules, each test in a file that calls `setupTests()` will\neffectively be run serially – otherwise there is no way to isolate requests\nper-test. The `beforeEach` hook will enforce this for you automatically.\nParallel tests running in different processes are not affected.\n\n## Modes\n\nYou can control ava-nock’s behavior using the `NOCK_MODE` environment variable.\n\n| NOCK_MODE |    Network requests?    |     Read fixtures?      |     Write fixtures?     |\n| :-------: | :---------------------: | :---------------------: | :---------------------: |\n|   live    | :ballot_box_with_check: |                         |                         |\n|  preview  | :ballot_box_with_check: | :ballot_box_with_check: |                         |\n|  record   | :ballot_box_with_check: |                         | :ballot_box_with_check: |\n|   cache   | :ballot_box_with_check: | :ballot_box_with_check: | :ballot_box_with_check: |\n|   play    |                         | :ballot_box_with_check: |                         |\n\n- **live** will disable replay and recording completely. All requests will hit\n  the network like normal.\n- **preview** will replay existing fixtures and send any other requests over the\n  network without recording them. This is useful if you are writing new tests\n  and want to make sure they pass before recording them.\n- **record** will ignore existing fixtures and record new ones. All requests\n  will hit the network and be recorded. When you update the requests made in a\n  test, you should re-record its fixtures.\n- **cache** will replay existing fixtures and record any other requests from the\n  network. This is useful if you have written new tests and verified that they\n  are correct and ready to be recorded.\n- **play** will replay existing fixtures and never hit the network. Any requests\n  that do not have a fixture will result in an error. This is the default\n  behavior. It is useful if you are done writing tests and want to verify that\n  they all pass. Use this mode in CI environments.\n\n## Configuration\n\nava-nock can be configured using either an `ava-nock` field in your package.json\nfile, or by importing and calling `configure()`.\n\n### Options\n\n#### decodeResponse\n\nWhen Nock outputs a response, it is normally minimally altered from how it\narrived. If the response is compressed, Nock will output an array of encoded\nbuffers. By default, ava-nock will instead attempt to decode responses encoded\nwith `gzip`, `deflate`, and `br` so that fixtures are more easily inspectable.\nIf successful, the relevant `Content-Encoding` header will also be removed from\nthe saved fixture so that clients don’t attempt to decode it again.\n\nSet this to `false` to leave responses encoded.\n\n#### fixtureDir\n\nThe directory relative to each test file in which to store Nock fixtures. The\noutput structure mirrors how AVA’s snapshots work: if your test file is at\n`src/file.test.js`, and this is set to `fixtures`, the fixture file will be\n`src/fixtures/file.test.js.nock`.\n\nIf unset, it will use same directory as snapshots via AVA’s\n`meta.snapshotDirectory` value if available, or a default value of `snapshots`\notherwise.\n\n#### headerFilter\n\nAn object mapping header names to replacement functions or arrays of arguments\nto pass to `.replace()` on the header value. The transformation will be applied\nto outgoing fixtures for _both the request headers and response headers_. This\nmeans that the filtered response headers will be used when the test is replayed,\nso you should ensure that no part of your test depends on the filtered value of\nthe headers; otherwise, your test could pass when being recorded and fail when\nplayed back, or vice versa.\n\nIf the replacement result is an empty string or null, the header will be removed\nfrom the fixture entirely.\n\n```js\n{\n  headerFilter: {\n    authorization: ['^(Bearer|Basic) .+$', '$1 \u003csecret\u003e'];\n  }\n}\n```\n\n#### pathFilter\n\nA function or array of arguments to pass to Nock’s `filteringPath` method on\neach scope. The transformation will be applied to both incoming request paths\nand outgoing fixture paths.\n\nFor example, the following value will cause any saved fixtures to have\n`secretKey` query parameters replaced with `secretKey=\u003csecret\u003e`, and will\nlikewise cause any requests with a `secretKey` value to match against it. The\nreplacement value (`\u003csecret\u003e` in this example) is not meaningful, it can be any\nvalue you deem suitable to store in your fixtures. The requests themselves will\nbe sent with their original, unaltered `secretKey` – but it will be censored in\nthe fixture. This way you can use sensitive values in your requests but keep\nthem out of source control.\n\n```js\n{\n  pathFilter: ['([?\u0026]secretKey=)([^\u0026#]+)', '$1\u003csecret\u003e'];\n}\n```\n\n#### requestBodyFilter\n\nA function or array of arguments to pass to Nock’s `filteringRequestBody` method\non each scope. The transformation will be applied to both incoming request\nbodies and outgoing fixture bodies.\n\nNote that it’s possible for Nock to output the request body as something other\nthan a string; for example, if it detects that it’s a JSON object. In this case,\nava-nock will call `JSON.stringify` on it first so that `filteringRequestBody`\nalways receives a string.\n\n#### responseBodyFilter\n\nA function or array of arguments to pass to `.replace()` on the response body\nstring. The transformation will be applied to outgoing fixture responses,\nmeaning that the filtered response body will be used when the test is replayed.\nThis means you should ensure that no part of your test depends on the filtered\npart of the response; otherwise, your test could pass when being recorded and\nfail when played back, or vice versa.\n\nNote that it’s possible for Nock to output the response body as something other\nthan a string; for example, if the response is still encoded, or if it detects\nthat it’s a JSON object. In this case, ava-nock will call `JSON.stringify` on it\nfirst.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fexogen%2Fava-nock","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fexogen%2Fava-nock","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fexogen%2Fava-nock/lists"}