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

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.