@you54f/pact-cli v13.13.3

Pact CLI Tools

This package wraps the Pact Standalone Tools so that they are available to

• node scripts in package.json
• linked binaries in the standard NPM installation directory (e..g. ./node_modules/.bin)
• Programatic wrapper for use in JavaScript and TypeScript projects.

Supported Platforms

🚧 - Tested under emulation mode x86 / x86_64 in Windows on ARM

Alpine users apk --no-cache add gcompat libc6-compat

Pact Download Location

For those that are behind a corporate firewall or are seeing issues where our package downloads binaries during installation, you can download the binaries directly from our github releases, and specify the location where you want Pact to get the binaries from using the 'config' section in your package.json file:

{
	"name": "some-project",
	...
	"config": {
		"pact_binary_location": "/home/some-user/Downloads"
	},
	...
}

It will accept both a local path or an http(s) url. It must point to the directory containing the binary needed as the binary name is appended to the end of the location. For the example given above, Pact will look for the binary at /home/some-user/Downloads/pact-1.44.0-win32.zip for a Windows system. However, by using this method, you must use the correct Pact version binary associated with this version of Pact-Core. For extra security measurements, checksum validation has been added to prevent tampering with the binaries.

Check which version you require, in the standalone/install.ts file, either in the repository or the published package

If your environment uses self-signed certificates from an internal Certificate Authority (CA), you can configure this using the standard options in an npmrc file as per below:

~/.npmrc:

cafile=/etc/ssl/certs/ca-certificates.crt
strict-ssl=true

Skip Pact binary downloading

You can also force Pact to skip the installation of the binary during npm install by setting PACT_SKIP_BINARY_INSTALL=true. This feature is useful if you want to speed up builds that don't need Pact and don't want to modify your projects dependencies.

Note that pact-core will not be functional without the binary.

PACT_SKIP_BINARY_INSTALL=true npm install

Windows Issues

Enable Long Paths

Windows has a default path length limit of 260 causing issues with projects that are nested deep inside several directory and with how npm handles node_modules directory structures. To fix this issue, please enable Windows Long Paths in the registry by running regedit.exe, find the key HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\FileSystem\LongPathsEnabled and change the value from 0 to 1, then reboot your computer. Pact should now work as it should, if not, please raise an issue on github.

Caveats

The following binaries are superceded by Rust based implementations

• pact-mock-service
  • Recommend use of pact_mock_server
    • README
    • Release
• pact-stub-service
  • Recommend use of pact-stub-server
    • README
    • Release
• pact-provider-verifier
  • Recommend use of pact_verifier_cli
• pact-message
  • Recommend use of pact_mock_server for consumer message pact
    • README
    • Release
  • Recommend use of pact_verifier_cli for provider message pact
    • README
    • Release

Pact CLI Bin Stubs

This package wraps the Pact Standalone Tools so that they are available to node scripts in package.json, and linked binaries in the standard NPM installation directory (e..g. ./node_modules/.bin).

For example:

"scripts": {
  "pactPublish": "pact-broker publish ./pacts --consumer-app-version=$\(git describe\) --broker-base-url=$BROKER_BASE_URL --broker-username=$BROKER_USERNAME --broker-password=BROKER_PASSWORD"`
}

Or:

 
```bash
# Example can-i-deploy check
./node_modules/.bin/pact-broker can-i-deploy --pacticipant "Banana Service" --broker-base-url https://test.pact.dius.com.au --latest --broker-username dXfltyFMgNOFZAxr8io9wJ37iUpY42M --broker-password O5AIZWxelWbLvqMd8PkAVycBJh2Psyg1

Computer says no ¯\_(ツ)_/¯

CONSUMER       | C.VERSION | PROVIDER       | P.VERSION | SUCCESS?
---------------|-----------|----------------|-----------|---------
Banana Service | 1.0.0     | Fofana Service | 1.0.0     | false

The verification between the latest version of Banana Service (1.0.0) and version 1.0.0 of Fofana Service failed

The following are the binaries currently made available:

• pact-mock-service
• pact-broker
• pact-stub-service
• pact-message
• pact-provider-verifier
• pact

Pact CLI JavaScript Wrapper

A wrapper for the Pact CLI Tools.

Usage

Simply require the library and call the create function to start the mock service

var pact = require("@you54f/pact-core");
var server = pact.createServer({ port: 9999 });
server.start().then(function() {
 // Do your testing/development here
});

Or if you're using Typescript instead of plain old Javascript

import pact from "@you54f/pact-core";
const server = pact.createServer({ port: 9999 });
server.start().then(() => {
 // Do your testing/development here
});

Or you can also use the CLI

$# pact mock --port 9999

To see the list commands possible with the CLI, simply ask for help $# pact --help

Documentation

Set Log Level

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

or you can set it via an environment variable

LOG_LEVEL=debug

Mock Servers

Mock servers are used by Pact to record interactions and create pact contracts.

Create Mock Server

var pact = require('@you54f/pact-core');
var server = pact.createServer({
 ...
});

Options:

List Mock Servers

If you ever need to see which servers are currently created.

var pact = require("@you54f/pact-core");
var servers = pact.listServers();
console.log(JSON.stringify(servers));

Remove All Mock Servers

Remove all servers once you're done with them in one fell swoop.

var pact = require("@you54f/pact-core");
pact.removeAllServers();

Start a Mock Server

Start the current server.

var pact = require("@you54f/pact-core");
pact.createServer()
 .start()
 .then(function() {
  // Do something after it started
 });

Stop a Mock server

Stop the current server.

var pact = require("@you54f/pact-core");
pact.createServer()
 .stop()
 .then(function() {
  // Do something after it stopped
 });

Delete a Mock server

Stop the current server and deletes it from the list.

var pact = require("@you54f/pact-core");
pact.createServer()
 .delete()
 .then(function() {
  // Do something after it was killed
 });

Check if a Mock server is running

var pact = require("@you54f/pact-core");
pact.createServer().running;

Mock Server Events

There's 3 different events available, 'start', 'stop' and 'delete'. They can be listened to the same way as an EventEmitter.

var pact = require("@you54f/pact-core");
var server = pact.createServer();
server.on("start", function() {
 console.log("started");
});
server.on("stop", function() {
 console.log("stopped");
});
server.on("delete", function() {
 console.log("deleted");
});

Provider Verification

Read more about Verify Pacts.

var pact = require('@you54f/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 | @@ -303,204 +130,26 @@ | 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.

Pact Broker Publishing

var pact = require('@you54f/pact-core');
var opts = {
 ...
};

pact.publishPacts(opts).then(function () {
 // do something
});

Options:

Pact Broker Deployment Check

var pact = require('@you54f/pact-core');
var opts = {
 ...
};

pact.canDeploy(opts)
 .then(function (result) {
  // You can deploy this
    // If output is not specified or is json, result describes the result of the check.
    // If outout is 'table', it is the human readable string returned by the check
 })
 .catch(function(error) {
  // You can't deploy this
    // if output is not specified, or is json, error will be an object describing
    // the result of the check (if the check failed),
    // if output is 'table', then the error will be a string describing the output from the binary,

    // In both cases, `error` will be an Error object if something went wrong during the check.
 });

Options:

Stub Servers

Stub servers create runnable APIs from existing pact files.

The interface is comparable to the Mock Server API.

Create Stub Server

var pact = require('@you54f/pact-core');
var server = pact.createStub({
 ...
});

Options:

Message Pacts

Create Message Pacts

var pact = require('@you54f/pact-core');
var message = pact.createMessage({
 ...
});

Options:

Example

const messageFactory = messageFactory({
 consumer: "consumer",
 provider: "provider",
 dir: dirname(`${__filename}/pacts`),
 content: `{
  "description": "a test mesage",
  "content": {
   "name": "Mary"
  }
 }`
});

messageFactory.createMessage();

Questions?

Please search for potential answers or post questions on the Pact slack channel.