Quick Start

Enabling the feature

This feature is disabled by default on all organizations. To enable the feature:

1. In the UI, navigate to "Settings" -> "Preferences" -> "System Preferences".
2. Check the "AI Test Generation" checkbox.
3. Save the settings.

note

You must be an Administrator or a user with the system_preference:manage:* permission to perform this action.

Installation

Option 1: MCP Server (Recommended)

The Model Context Protocol (MCP) is the recommended way to use PactFlow AI. It provides seamless integration with IDEs and modern developer environments.

MCP Server exposes PactFlow AI as a local endpoint and works with tools like VS Code, IntelliJ, Cursor, and other MCP-compatible agents.

Follow the official MCP Server documentation to perform the following steps:

• Install the MCP Server.
• Configure and start the local service.
• Connect with MCP clients.

This option is ideal for teams working with AI copilots or looking to automate testing workflows.

Option 2: CLI

You can also use PactFlow AI using the CLI. It supports test generation and review from the terminal. For *nix users (including Windows users running WSL/msys2/mingw), use the following command to download and install:

curl https://download.pactflow.io/ai/get.sh | sh

For Windows PowerShell users, use the following command to download and install:

Invoke-WebRequest -Uri https://download.pactflow.io/ai/get.ps1 | Invoke-Expression

Installation Options

There are some options which you can set during installation.

For a full list, see the --help/-h command

curl https://download.pactflow.io/ai/get.sh | sh -s -- -h

• --verbose / -v / PACTFLOW_AI_VERBOSE: Enable verbose output.
• --quiet / -q / PACTFLOW_AI_QUIET: Disable progress output.
• --yes / -y / PACTFLOW_AI_YES: Disable confirmation prompt and assume 'yes'.
• --destination / -d / PACTFLOW_AI_DESTINATION: Specify the directory to install the binary.
• --default-host / PACTFLOW_AI_DEFAULT_HOST: Choose a default host triple rather than autodetecting.
• --no-modify-path / PACTFLOW_AI_NO_MODIFY_PATH: Don't configure the PATH environment variable.

Verify the installation by running pactflow-ai to ensure it executes successfully.

Manual installation

Alternatively, download the latest version for your OS and architecture from the table below. Be sure to add it to your environment's PATH:

OS	Architecture	Link
Apple Darwin	aarch64
Apple Darwin	x86_64
Windows MSVC	x86_64
Windows MSVC	aarch64
Linux GNU	x86_64
Linux MUSL	x86_64
Linux GNU	aarch64
Linux MUSL	aarch64

note

Linux GNU users will require glibc version 2.23 or later.

Environments which do not use glibc, or use a version of glibc prior to 2.23, should instead use the musl variant.

Getting Started

note

Running pactflow-ai --help will show detailed usage for any subcommands.

Authenticating to PactFlow

Authentication requires valid PactFlow API Tokens, which can be obtained from the Settings > Tokens page of your PactFlow organization.

Set the following environment variables, and the CLI will use them to communicate with PactFlow:

export PACT_BROKER_BASE_URL="https://YOUR_ORG.pactflow.io"
export PACT_BROKER_TOKEN="YOUR_TOKEN"

Learn more about other ways of configuring PactFlow AI.

Generating Pact Tests

To generate Pact tests we will use the pactflow-ai generate subcommand. There are 3 sources that may be used for generation, including openapi, code and request-response.

Let's assume we have a simple Product API for which we would like to create Pact tests, described by the following OpenAPI description:

products.yml

openapi: 3.0.1
info:
  title: Product API
  description: Pactflow Product API demo
  version: 1.0.0
paths:
  /product/{id}:
    get:
      summary: Find product by ID
      description: Returns a single product
      operationId: getProductByID
      parameters:
      - name: id
        in: path
        description: Product ID
        schema:
          type: string
        required: true
      responses:
        "200":
          description: successful operation
          content:
            "application/json; charset=utf-8":
              schema:
                $ref: '#/components/schemas/Product'
        "404":
          description: Product not found
          content: {}
components:
  schemas:
    Product:
      type: object
      required:
        - id
        - name
        - price
      properties:
        id:
          type: string
        type:
          type: string
        name:
          type: string
        version:
          type: string
        price:
          type: number

1. Download and save this file as /tmp/products.yml.
2. Generate a Pact test for the HTTP 200 use case (default) using the following command:

pactflow-ai generate \
  --openapi  /tmp/products.yml \
  --endpoint "/product/{id}" \
  --output   /tmp/api.pact.spec.ts \
  --language typescript

Be sure to update the paths as necessary. Executing the command should produce something like this:

// Generated by PactFlow
// Timestamp: 2025-02-11T00:34:14.067426+00:00
// Reference: 06TzSdaSlI4iKH1zIdgh

import { PactV3, MatchersV3 } from "@pact-foundation/pact";
import { API } from "./src/api";

describe('Consumer Pact with Product Service', () => {
  const provider = new PactV3({
    consumer: 'ProductConsumer',
    provider: 'ProductService',
  });

  describe('Pact for getProductByID', () => {
    it('returns a product by ID', () => {
      provider
        .given('a product with ID exists')
        .uponReceiving('a request to get a product by ID')
        .withRequest({
          method: 'GET',
          path: MatchersV3.regex('/product/[a-zA-Z0-9]+', '/product/123'),
          headers: {
            'Authorization': MatchersV3.regex('Bearer [a-zA-Z0-9]+', 'Bearer token123'),
            'Content-Type': 'application/json; charset=utf-8'
          }
        })
        .willRespondWith({
          status: 200,
          headers: {
            'Content-Type': 'application/json; charset=utf-8'
          },
          body: MatchersV3.like({
            id: MatchersV3.string('123'),
            name: MatchersV3.string('Product Name'),
            price: MatchersV3.number(99.99),
            type: MatchersV3.string('Product Type'),
            version: MatchersV3.string('1.0')
          })
        });

      return provider.executeTest(async (mockserver) => {
        const api = new API(mockserver.url);
        const product = await api.getProduct('123');
        expect(product).to.deep.equal({
          id: '123',
          name: 'Product Name',
          price: 99.99,
          type: 'Product Type',
          version: '1.0'
        });
      });
    });
  });
});

And that's it! Of course, this test won't work without being a part of a real project, but hopefully you can see how you can quickly generate Pact tests using PactFlow AI, saving time and improving accuracy.