{"id":13450158,"url":"https://github.com/pact-foundation/pact-js","last_synced_at":"2025-05-15T00:03:49.432Z","repository":{"id":38748871,"uuid":"60344592","full_name":"pact-foundation/pact-js","owner":"pact-foundation","description":"JS version of Pact. Pact is a contract testing framework for HTTP APIs and non-HTTP asynchronous messaging systems.","archived":false,"fork":false,"pushed_at":"2025-05-07T22:07:53.000Z","size":39783,"stargazers_count":1682,"open_issues_count":101,"forks_count":354,"subscribers_count":12,"default_branch":"master","last_synced_at":"2025-05-07T23:32:46.191Z","etag":null,"topics":["consumer-driven-contracts","hacktoberfest","mocha","pact","pact-js","smartbear-supported","test-framework"],"latest_commit_sha":null,"homepage":"https://pact.io","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/pact-foundation.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","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,"zenodo":null},"funding":{"open_collective":"pact-foundation","custom":["https://pactflow.io"]}},"created_at":"2016-06-03T12:02:17.000Z","updated_at":"2025-05-07T22:07:18.000Z","dependencies_parsed_at":"2023-09-24T05:24:54.664Z","dependency_job_id":"e8faa005-fb44-4609-8ae5-63ec14c43764","html_url":"https://github.com/pact-foundation/pact-js","commit_stats":{"total_commits":2386,"total_committers":124,"mean_commits":"19.241935483870968","dds":0.672254819782062,"last_synced_commit":"7bf180f4c710a7fd11591e7b7c16971112001b89"},"previous_names":[],"tags_count":260,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pact-foundation%2Fpact-js","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pact-foundation%2Fpact-js/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pact-foundation%2Fpact-js/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pact-foundation%2Fpact-js/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pact-foundation","download_url":"https://codeload.github.com/pact-foundation/pact-js/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253807353,"owners_count":21967344,"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":["consumer-driven-contracts","hacktoberfest","mocha","pact","pact-js","smartbear-supported","test-framework"],"created_at":"2024-07-31T07:00:31.641Z","updated_at":"2025-05-15T00:03:49.372Z","avatar_url":"https://github.com/pact-foundation.png","language":"TypeScript","funding_links":["https://opencollective.com/pact-foundation","https://pactflow.io"],"categories":["JavaScript","Contract Testing","TypeScript"],"sub_categories":[".NET"],"readme":"\u003cspan align=\"center\"\u003e\n\n![logo](https://user-images.githubusercontent.com/53900/121775784-0191d200-cbcd-11eb-83dd-adc001b94519.png)\n\n# Pact JS\n\n\u003c!-- Please use absolute URLs for all links as the content of this page is synced to docs.pact.io --\u003e\n\n[![Build Status](https://github.com/pact-foundation/pact-js/workflows/Build,%20test,%20test%20all%20examples/badge.svg)](https://github.com/pact-foundation/pact-js/actions?query=workflow%3A%22Build%2C+test%2C+test+all+examples%22)\n[![npm](https://img.shields.io/npm/v/@pact-foundation/pact.svg)](https://www.npmjs.com/package/@pact-foundation/pact)\n![Release workflow](https://github.com/pact-foundation/pact-js/workflows/Release%20workflow/badge.svg?branch=feat%2Fv3.0.0)\n[![Coverage Status](https://coveralls.io/repos/github/pact-foundation/pact-js/badge.svg?branch=master)](https://coveralls.io/github/pact-foundation/pact-js?branch=master)\n[![Code Climate](https://codeclimate.com/github/pact-foundation/pact-js/badges/gpa.svg)](https://codeclimate.com/github/pact-foundation/pact-js)\n[![Issue Count](https://codeclimate.com/github/pact-foundation/pact-js/badges/issue_count.svg)](https://codeclimate.com/github/pact-foundation/pact-js)\n[![Known Vulnerabilities](https://snyk.io/test/github/pact-foundation/pact-js/badge.svg?targetFile=package.json)](https://snyk.io/test/github/pact-foundation/pact-js?targetFile=package.json)\n[![license](https://img.shields.io/badge/license-MIT-green.svg)](https://github.com/pact-foundation/pact-js/blob/master/LICENSE)\n[![slack](https://slack.pact.io/badge.svg)](https://slack.pact.io)\n\n#### Fast, easy and reliable testing for your APIs and microservices.\n\n\u003c/span\u003e\n\n\u003cbr /\u003e\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://docs.pact.io\"\u003e\u003cimg src=\"https://user-images.githubusercontent.com/53900/180370118-f11c61f3-4ae0-496f-98fa-052fdfad409e.gif\" alt=\"Pact JS Demo\"/\u003e\u003c/a\u003e\n\u003c/p\u003e\n\u003cbr /\u003e\n\n\u003ctable\u003e\n\u003ctr\u003e\n\u003ctd\u003e\n\n**Pact** is the de-facto API contract testing tool. Replace expensive and brittle end-to-end integration tests with fast, reliable and easy to debug unit tests.\n\n- ⚡ Lightning fast\n- 🎈 Effortless full-stack integration testing - from the front-end to the back-end\n- 🔌 Supports HTTP/REST and event-driven systems\n- 🛠️ Configurable mock server\n- 😌 Powerful matching rules prevents brittle tests\n- 🤝 Integrates with Pact Broker / PactFlow for powerful CI/CD workflows\n- 🔡 Supports 12+ languages\n\n**Why use Pact?**\n\nContract testing with Pact lets you:\n\n- ⚡ Test locally\n- 🚀 Deploy faster\n- ⬇️ Reduce the lead time for change\n- 💰 Reduce the cost of API integration testing\n- 💥 Prevent breaking changes\n- 🔎 Understand your system usage\n- 📃 Document your APIs for free\n- 🗄 Remove the need for complex data fixtures\n- 🤷‍♂️ Reduce the reliance on complex test environments\n\nWatch our [series](https://www.youtube.com/playlist?list=PLwy9Bnco-IpfZ72VQ7hce8GicVZs7nm0i) on the problems with end-to-end integrated tests, and how contract testing can help.\n\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003c/table\u003e\n\n![----------](https://user-images.githubusercontent.com/53900/182992715-aa63e421-170b-41cf-8f95-82fe4b0846c2.png)\n\n## Documentation\n\nThis readme offers a basic introduction to the library. The full documentation for Pact JS and the rest of the framework is available at https://docs.pact.io/.\n\n- [Installation](#installation)\n- [Consumer Testing](/docs/consumer.md)\n  - [Matching](/docs/matching.md)\n- [Provider Testing](/docs/provider.md)\n- [Event Driven Systems](/docs/messages.md)\n- [Plugins](/docs/plugins.md)\n- [GraphQL](/docs/graphql.md)\n- [XML](/docs/xml.md)\n- [Examples](https://github.com/pact-foundation/pact-js/tree/master/examples/)\n- [Migration guide](/MIGRATION.md)\n- [Troubleshooting](/docs/troubleshooting.md)\n\n### Tutorial (60 minutes)\n\nLearn the key Pact JS features in 60 minutes: https://github.com/pact-foundation/pact-workshop-js\n\n## Need Help\n\n- [Join](http://slack.pact.io) our community [slack workspace](http://pact-foundation.slack.com/).\n- Stack Overflow: https://stackoverflow.com/questions/tagged/pact\n- Say 👋 on Twitter: [@pact_up]\n\n## Installation\n\n```shell\nnpm i -S @pact-foundation/pact@latest\n\n# 🚀 now write some tests!\n```\n\nLooking for the previous [stable 9.x.x release](https://github.com/pact-foundation/pact-js/tree/9.x.x)?\n\n### Requirements\n\nNode 16+ as of pact-js v12\n\n1. If using pact-js v11 or lower,\n   1. make sure the `ignore-scripts` option is disabled, pact uses npm scripts to compile native dependencies and won't function without it.\n   2. Pact uses native extensions and installs them via the [`node-gyp`](https://github.com/nodejs/node-gyp) package. This requires a [build chain](https://github.com/nodejs/node-gyp#installation) for a successful installation. See also issue [#899](https://github.com/pact-foundation/pact-js/issues/899). This is now prebuilt in pact-js v12+\n\n### Do Not Track\n\nIn order to get better statistics as to who is using Pact, we have an anonymous tracking event that triggers when Pact installs for the first time. The only things we [track](https://docs.pact.io/metrics) are your type of OS, and the version information for the package being installed. No PII data is sent as part of this request. You can disable tracking by setting the environment variable `PACT_DO_NOT_TRACK=1`:\n\n![----------](https://user-images.githubusercontent.com/53900/182992715-aa63e421-170b-41cf-8f95-82fe4b0846c2.png)\n\n## Usage\n\n### Consumer package\n\nThe main consumer interface are the `PactV3` class and `MatchersV3` exports of the `@pact-foundation/pact` package.\n\n#### Writing a Consumer test\n\nPact is a consumer-driven contract testing tool, which is a fancy way of saying that the API `Consumer` writes a test to set out its assumptions and needs of its API `Provider`(s). By unit testing our API client with Pact, it will produce a `contract` that we can share to our `Provider` to confirm these assumptions and prevent breaking changes.\n\nIn this example, we are going to be testing our User API client, responsible for communicating with the `UserAPI` over HTTP. It currently has a single method `GetUser(id)` that will return a `*User`.\n\nPact tests have a few key properties. We'll demonstrate a common example using the 3A `Arrange/Act/Assert` pattern.\n\n```js\nimport { PactV3, MatchersV3 } from '@pact-foundation/pact';\n\n// Create a 'pact' between the two applications in the integration we are testing\nconst provider = new PactV3({\n  dir: path.resolve(process.cwd(), 'pacts'),\n  consumer: 'MyConsumer',\n  provider: 'MyProvider',\n});\n\n// API Client that will fetch dogs from the Dog API\n// This is the target of our Pact test\npublic getMeDogs = (from: string): AxiosPromise =\u003e {\n  return axios.request({\n    baseURL: this.url,\n    params: { from },\n    headers: { Accept: 'application/json' },\n    method: 'GET',\n    url: '/dogs',\n  });\n};\n\nconst dogExample = { dog: 1 };\nconst EXPECTED_BODY = MatchersV3.eachLike(dogExample);\n\ndescribe('GET /dogs', () =\u003e {\n  it('returns an HTTP 200 and a list of dogs', () =\u003e {\n    // Arrange: Setup our expected interactions\n    //\n    // We use Pact to mock out the backend API\n    provider\n      .given('I have a list of dogs')\n      .uponReceiving('a request for all dogs with the builder pattern')\n      .withRequest({\n        method: 'GET',\n        path: '/dogs',\n        query: { from: 'today' },\n        headers: { Accept: 'application/json' },\n      })\n      .willRespondWith({\n        status: 200,\n        headers: { 'Content-Type': 'application/json' },\n        body: EXPECTED_BODY,\n      });\n\n    return provider.executeTest((mockserver) =\u003e {\n      // Act: test our API client behaves correctly\n      //\n      // Note we configure the DogService API client dynamically to\n      // point to the mock service Pact created for us, instead of\n      // the real one\n      dogService = new DogService(mockserver.url);\n      const response = await dogService.getMeDogs('today')\n\n      // Assert: check the result\n      expect(response.data[0]).to.deep.eq(dogExample);\n    });\n  });\n});\n```\n\nYou can see (and run) the full version of this in `./examples/v3/typescript`, as well as other examples in the parent folder.\n\nTo run the examples\n\n1. Clone the repo `git@github.com:pact-foundation/pact-js.git`\n\nRun a single example\n\n1. Change into the required example folder `cd examples/e2e/v3/typescript`\n2. Install all the examples dependencies `npm install`\n3. Run all the example - `npm run test`\n\nRun all examples\n\n1. Change into the examples folder `cd examples`\n2. Run all examples `./run-all`\n\n![----------](https://user-images.githubusercontent.com/53900/182992715-aa63e421-170b-41cf-8f95-82fe4b0846c2.png)\n\n### Provider package\n\nThe main provider interface is the `Verifier` class of the `@pact-foundation/pact` package.\n\n#### Verifying a Provider\n\nA provider test takes one or more pact files (contracts) as input, and Pact verifies that your provider adheres to the contract. In the simplest case, you can verify a provider as per below using a local pact file, although in practice you would usually use a Pact Broker to manage your contracts and CI/CD workflow.\n\n```js\nconst { Verifier } = require('@pact-foundation/pact');\n\n// (1) Start provider locally. Be sure to stub out any external dependencies\nserver.listen(8081, () =\u003e {\n  importData();\n  console.log('Animal Profile Service listening on http://localhost:8081');\n});\n\n// (2) Verify that the provider meets all consumer expectations\ndescribe('Pact Verification', () =\u003e {\n  it('validates the expectations of Matching Service', () =\u003e {\n    let token = 'INVALID TOKEN';\n\n    return new Verifier({\n      providerBaseUrl: 'http://localhost:8081', // \u003c- location of your running provider\n      pactUrls: [ path.resolve(process.cwd(), \"./pacts/SomeConsumer-SomeProvider.json\") ],\n    })\n      .verifyProvider()\n      .then(() =\u003e {\n        console.log('Pact Verification Complete!');\n      });\n  });\n});\n\n```\n\nIt's best to run Pact verification tests as part of your unit testing suite, so you can readily access stubbing, IaC and other helpful tools.\n\n![----------](https://user-images.githubusercontent.com/53900/182992715-aa63e421-170b-41cf-8f95-82fe4b0846c2.png)\n\n## Compatibility\n\n\u003cdetails\u003e\u003csummary\u003eSpecification Compatibility\u003c/summary\u003e\n\n| Version  | Stable | [Spec] Compatibility | Install            |\n| -------  | ------ | -------------------- | ------------------ |\n| 11.x.x + | Yes    | 2, 3, 4              | See [installation] |\n| 10.x.x   | Yes    | 2, 3, 4              | See [installation] |\n| 9.x.x    | Yes    | 2, 3\\*               | [9xx]              |\n\n_\\*_ v3 support is limited to the subset of functionality required to enable language inter-operable [Message support].\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\u003csummary\u003eSupported Platforms\u003c/summary\u003e\n\n| OS            | Architecture | Supported  | Pact-JS Version  |\n| ------------- | ------------ | ---------  | ---------------- |\n| MacOS         | x86_64       | ✅         | All              |\n| MacOS         | arm64        | ✅         | 9.x +            |\n| Linux (libc)  | x86_64       | ✅         | All              |\n| Linux (libc)  | arm64        | ✅         | 10.x +           |\n| Linux (musl)  | x86_64       | ✅         | 13.x +           |\n| Linux (musl)  | arm64        | ✅         | 13.x +           |\n| Windows       | x86_64       | ✅         | All              |\n| Windows       | x86          | ❌         | 9.x -            |\n| Windows       | arm64        | ❌         | -                |\n\n\u003c/details\u003e\n\n## Roadmap\n\nThe [roadmap](https://docs.pact.io/roadmap/) for Pact and Pact JS is outlined on our main website.\n## Contributing\n\nSee [CONTRIBUTING](CONTRIBUTING.md).\n\n\u003ca href=\"https://github.com/pact-foundation/pact-js/graphs/contributors\"\u003e\n  \u003cimg src=\"https://contrib.rocks/image?repo=pact-foundation/pact-js\" /\u003e\n\u003c/a\u003e\n\u003cbr /\u003e\n\n[spec]: https://github.com/pact-foundation/pact-specification\n[10xx]: https://github.com/pact-foundation/pact-js/tree/10.x.x\n[9xx]: https://github.com/pact-foundation/pact-js/tree/9.x.x\n[pact website]: http://docs.pact.io/\n[@pact_up]: https://twitter.com/pact_up\n[pact specification v2]: https://github.com/pact-foundation/pact-specification/tree/version-2\n[pact specification v3]: https://github.com/pact-foundation/pact-specification/tree/version-3\n[library]: https://github.com/pact-foundation/pact-reference/releases\n[installation]: #installation\n[message support]: https://github.com/pact-foundation/pact-specification/tree/version-3#introduces-messages-for-services-that-communicate-via-event-streams-and-message-queues\n[changelog]: https://github.com/pact-foundation/pact-js/blob/master/CHANGELOG.md\n[pact broker]: https://github.com/pact-foundation/pact_broker\n[pactflow]: https://pactflow.io\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpact-foundation%2Fpact-js","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpact-foundation%2Fpact-js","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpact-foundation%2Fpact-js/lists"}