README.md

ℹ️ Usage notice
This is a core library, designed for use in the bowels of another package. Unless you are wanting to develop tools for the pact ecosystem, you almost certainly want to install @pact-foundation/pact instead

Pact-JS Core

A wrapper for the Pact Reference Core Library.

• Pact-JS Core
  • Installation
    • Do Not Track
  • Which Library/Package should I use?
  • Documentation
    • Set Log Level
    • Provider Verification
  • Contributing
  • Testing
  • Questions?

Installation

npm install @pact-foundation/pact-core --save-dev

Do Not Track

In 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. To respect your privacy, anyone can turn it off by simply adding a 'do not track' flag within their package.json file:

{
 "name": "some-project",
 ...
 "config": {
  "pact_do_not_track": true
 },
 ...
}

Which Library/Package should I use?

TL;DR - you almost always want Pact JS.

Purpose	Library	Comments
Synchronous / HTTP APIs	Pact JS
Asynchronous APIs	Pact JS
Node.js	Pact JS
Browser testing	Pact Web	You probably still want Pact JS. See Using Pact in non-Node environments *
Isomorphic testing	Pact Web	You probably still want Pact JS. See Using Pact in non-Node environments *
Publishing to Pact Broker	Pact CLI

* The "I need to run it in the browser" question comes up occasionally. The question is this - for your JS code to be able to make a call to another API, is this dependent on browser-specific code? In most cases, people use tools like React/Angular which have libraries that work on the server and client side, in which case, these tests don't need to run in a browser and could instead be executed in a Node.js environment.

Documentation

Set Log Level

var pact = require("@pact-foundation/pact-core");
pact.logLevel("debug");

Provider Verification

Read more about Verify Pacts.

var pact = require('@pact-foundation/pact-core');

pact.verifyPacts({
 ...
});

Options:

Parameter	Required?	Type	Description
providerBaseUrl	true	string	Running API provider host endpoint.
pactBrokerUrl	false	string	Base URL of the Pact Broker from which to retrieve the pacts. Required if pactUrls not given.
provider	false	string	Name of the provider if fetching from a Broker
consumerVersionSelectors	false	ConsumerVersionSelector|array	Use Selectors to is a way we specify which pacticipants and versions we want to use when configuring verifications.
consumerVersionTags	false	string|array	Retrieve the latest pacts with given tag(s)
providerVersionTags	false	string|array	Tag(s) to apply to the provider application
includeWipPactsSince	false	string	Includes pact marked as WIP since this date. String in the format %Y-%m-%d or %Y-%m-%dT%H:%M:%S.000%:z
pactUrls	false	array	Array of local pact file paths or HTTP-based URLs. Required if not using a Pact Broker.
providerStatesSetupUrl	false	string	URL to send PUT requests to setup a given provider state
pactBrokerUsername	false	string	Username for Pact Broker basic authentication
pactBrokerPassword	false	string	Password for Pact Broker basic authentication
pactBrokerToken	false	string	Bearer token for Pact Broker authentication
publishVerificationResult	false	boolean	Publish verification result to Broker (NOTE: you should only enable this during CI builds)
providerVersion	false	string	Provider version, required to publish verification result to Broker. Optional otherwise.
enablePending	false	boolean	Enable the pending pacts feature.
timeout	false	number	The duration in ms we should wait to confirm verification process was successful. Defaults to 30000.
logLevel	false	LogLevel (string)	Log level. One of "TRACE", "DEBUG", "ERROR", "WARN", "INFO", can be set by LOG_LEVEL env var

The consumer version selector looks like this:

ConsumerVersionSelector {
  tag?: string;
  latest?: boolean;
  consumer?: string;
  deployedOrReleased?: boolean;
  deployed?: boolean; 
  released?: boolean; 
  environment?: string;
  fallbackTag?: string;
  branch?: string;
  mainBranch?: boolean;
  matchingBranch?: boolean;
}

See the Pact Broker documentation on selectors for more information.

Contributing

To develop this project, simply install the dependencies with npm install --ignore-scripts, and run npm run watch to for continual development, linting and testing when a source file changes.

Testing

Running npm test will execute the tests that has the *.spec.js pattern.

Questions?

Please search for potential answers or post question on our official Pact StackOverflow.