{"id":13774090,"url":"https://github.com/airtasker/proxay","last_synced_at":"2025-04-07T13:07:07.444Z","repository":{"id":32807258,"uuid":"143241892","full_name":"airtasker/proxay","owner":"airtasker","description":"Proxay is a record/replay proxy server that helps you write faster and more reliable tests.","archived":false,"fork":false,"pushed_at":"2024-09-15T19:39:48.000Z","size":1621,"stargazers_count":78,"open_issues_count":16,"forks_count":6,"subscribers_count":46,"default_branch":"master","last_synced_at":"2025-03-29T06:04:53.145Z","etag":null,"topics":["mocking","proxy","testing"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/airtasker.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-08-02T04:20:57.000Z","updated_at":"2025-02-27T13:05:56.000Z","dependencies_parsed_at":"2023-12-21T04:59:56.533Z","dependency_job_id":"a56ce72a-367f-4d92-bce6-7b581b130e3f","html_url":"https://github.com/airtasker/proxay","commit_stats":{"total_commits":429,"total_committers":16,"mean_commits":26.8125,"dds":0.4289044289044289,"last_synced_commit":"466a8b1da7b6af58fb3c82a67330616912a57eb1"},"previous_names":[],"tags_count":13,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/airtasker%2Fproxay","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/airtasker%2Fproxay/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/airtasker%2Fproxay/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/airtasker%2Fproxay/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/airtasker","download_url":"https://codeload.github.com/airtasker/proxay/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247657281,"owners_count":20974345,"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":["mocking","proxy","testing"],"created_at":"2024-08-03T17:01:23.615Z","updated_at":"2025-04-07T13:07:07.426Z","avatar_url":"https://github.com/airtasker.png","language":"TypeScript","funding_links":[],"categories":["\u003ca id=\"58b6684347a223e01d4d76d9ca185a88\"\u003e\u003c/a\u003eReplay\u0026\u0026重播"],"sub_categories":[],"readme":"# Proxay\n\n[![CircleCI](https://circleci.com/gh/airtasker/proxay.svg?style=svg)](https://circleci.com/gh/airtasker/proxay)\n\nProxay (pronounced \"prokseï\") is a proxy server that helps you write faster tests.\n\nUse Proxay as a layer between a client and its backend to record interactions and later replay them on demand.\n\nYou can use Proxay to proxy interactions between:\n- a web frontend and its backend\n- a mobile app and its backend\n- a server and another server (or a set of others, if using multiple Proxay instances)\n\nProxay can operate in several modes:\n- **Record mode**: Proxies requests to the backend and records interactions as \"tapes\" on disk.\n- **Replay mode**: Replays requests from your \"tapes\" on disk (no backend necessary).\n- **Mimic mode**: Records requests the first time it encounters them, then replays them (record then replay).\n- **Passthrough mode**: Proxies requests without persisting them (like a conventional proxy).\n\nProxay is language-agnostic: it's just a server. Your code doesn't need to be written in JavaScript to benefit from using it.\n\n## Installing\n\nMake sure you have [NPM](https://www.npmjs.com) installed, then run:\n```sh\nnpm install --global proxay\n\n# or if you're using Yarn\nyarn global add proxay\n```\n\n## Running\n\n```sh\n# Record mode (proxies requests)\nproxay --mode record --host https://api.website.com --tapes-dir tapes/\n\n# Replay mode (no proxying)\nproxay --mode replay --tapes-dir tapes/\n\n# Passthrough mode (proxies requests without persisting)\nproxay --mode passthrough --host https://api.website.com\n```\n\nYou can also run several instances of Proxay simultaneously on different ports (for example to proxy\nmultiple backends). Just pick a different port (e.g. `--port 3001`).\n\nIf you want proxay to accept incoming requests on HTTPS in addition to HTTP, you can provide the HTTPS key and certificate files in PEM format on the `--https-key` and `--https-cert` arguments respectively. If the HTTPS certificate is self-signed, you probably also want to provide the CA certificate in PEM format on `--https-ca`. See the `key`, `cert`, and `ca` arguments to [`tls.createSecureContext`](https://nodejs.org/api/tls.html#tlscreatesecurecontextoptions) for what these mean.\n\n## Specifying a tape\n\nIf you have several tests, you likely want to save recorded interactions into one tape per test,\nand replay from the correct tape for each test.\n\nYou can do this by sending a `POST` request to `/__proxay/tape` with the following payload:\n```json\n{\n  \"tape\": \"test1/my tape\"\n}\n```\n\nIn record mode, this will create a new file `test1/my tape.yml` within your tapes directory.\nIn replay mode, this same file will be read from your tapes directory.\n\nYou can leverage this by picking a tape based on the current test's name in the `beforeEach`\nblock of your test suite.\n\n## (Some) Options\n\n`--send-proxy-port`: This flag enables the forwarding of the Proxay's local port number to the proxied host in the host header. It is particularly useful for handling redirect issues where the proxied host needs to be aware of the port on which Proxay is running to construct accurate redirect URLs. This is similar to nginx' `proxy_set_header Host $host:$server_port;`.\n\n\n`--ignore-headers \u003cheaders\u003e`: Allows users to specify a list of headers that should be ignored by Proxay's matching algorithm during request comparison. This is useful for bypassing headers that do not influence the behavior of the request but may cause mismatches, such as `x-forwarded-for` or `x-real-ip`. The headers should be provided as a comma-separated list.\n\nNote: there is already a hardcoded list of headers that get ignored:\n`accept`, `accept-encoding`, `age`, `cache-control`, `clear-site-data`, `connection`, `expires`, `from`, `host`, `postman-token`, `pragma`, `referer`, `referer-policy`, `te`, `trailer`, `transfer-encoding`, `user-agent`, `warning`, `x-datadog-trace-id`, `x-datadog-parent-id`, `traceparent`\n\n\n`-r, --redact-headers \u003cheaders\u003e`: This option enables the redaction of specific HTTP header values, which are replaced by `XXXX` to maintain privacy or confidentiality during the recording of network interactions. The headers should be provided as a comma-separated list.\n\n\n`--debug-matcher-fails`: When exact request matching is enabled, this flag provides some debug information on why a request did not match any recorded tape. It is useful for troubleshooting and refining the conditions under which requests are considered equivalent, focusing on differences in headers and query parameters.\n\n\n## Typical use case\n\nLet's say you're writing tests for your client. You want your tests to run as\nfast as possible, but your backend is quite slow. Or worse, you have some tests already,\nbut they're flaky because your backend or one of its dependencies isn't completely\nreliable.\n\nInstead of pointing your client to your backend like you normally would, use Proxay\nas your backend. Tell Proxay to record requests going to the backend and run your tests\nonce. This will create \"tapes\" which are records of each request/response between your\nclient and your backend.\n\nThen, run Proxay in replay mode and run your tests again. Your tests should still work,\nbut you'll notice tests run a lot faster. That's because your backend is not used anymore.\nInstead, Proxay plays back responses from the tapes it had previously recorded.\n\nThis will make your tests faster and more stable. However, because you no longer use a real\nbackend, you should still make sure to run your jobs in \"record\" mode on a regular basis (for\nexample with a cron job on your CI) to test the implicit contract between your client and\nbackend.\n\n---\n\n## Comparison with alternatives\n\n### [`node-replay`](https://github.com/assaf/node-replay)\n\n`node-replay` is an inspiration for Proxay.\n\nHowever, `node-replay` isn't a proxy per se: it simply replaces `require('http').request` in Node\nwith its own method. This means that you can only use `node-replay` when running tests within Node.\n\nProxay is more versatile. It's \"just a server\". You can use it for anything you want, including as\npart of your test infrastructure for your web or mobile applications.\n\n### [`yakbak`](https://github.com/flickr/yakbak)\n\nProxay is very similar to `yakbak`. There are a couple of differences:\n\n- Proxay is purely an HTTP server. You control it through HTTP as well (see [**Specifying a tape**](#specifying-a-tape)).\n- Proxay automatically replaces `host` headers so the backend doesn't reject mismatching requests.\n\n### [`vcr`](https://github.com/vcr/vcr)\n\nVCR is a Ruby gem with a similar approach to `node-replay`. Just like `node-replay`, it cannot be\nused as a general-purpose proxy. It can only be used to test Ruby software.\n\n### [`MockServer`](https://github.com/jamesdbloom/mockserver)\n\nMockServer does a lot more things than Proxay.\n\nIf you need something more elaborate than Proxay, for example the ability to mock out specific URL\npatterns, you may need MockServer.\n\nHowever, if all you need is a simple record/replay proxy layer, you'll probably find that Proxay is\nmuch easier to set up and run.\n\n---\n\n## Releasing a new version of Proxay (for contributors)\n\nTo release a new version of Proxay, follow the following two steps:\n\n### Update the version in `master`\n\n1. Create a new branch.\n2. Update the `version` field in `package.json`.\n3. Send a PR with the changes (commit message `Release [version]`).\n4. Merge the PR into master.\n\n### Create a release on GitHub\n\n1. Visit the [releases page](https://github.com/airtasker/proxay/releases) to see what was last announced.\n2. Draft a new release:\n    - Tag = `v[version]` (e.g. `v2.1.1`). **Do not forget the `v`, which is required to trigger the NPM publish in GitHub Actions.**\n    - Title = `Release v[version]` (e.g. `Release v2.1.1`)\n3. Make sure to announce major changes since the last version in the description.\n4. Once published, [check CircleCI](https://circleci.com/gh/airtasker/proxay) to ensure publication was successful.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fairtasker%2Fproxay","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fairtasker%2Fproxay","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fairtasker%2Fproxay/lists"}