docs: rework examples

Replace the per-version examples with a single suite of examples, all
using `Pact` (i.e., `PactV4`).

Signed-off-by: JP-Ellis <josh@jpellis.me>

Author: JP-Ellis

.github/workflows/test.yml

@@ -86,23 +86,6 @@ jobs:
       - name: Format
         run: npm run format
 
-  build:
-    name: Package Pact JS
-    runs-on: ubuntu-latest
-
-    steps:
-      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
-      - uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6
-        with:
-          node-version: ${{ env.STABLE_NODE_VERSION }}
-          cache: npm
-      - run: npm ci
-      - run: npm run dist
-      - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
-        with:
-          name: dist
-          path: dist
-
   regression:
     name: Run regression suite
     runs-on: ubuntu-latest
@@ -246,68 +229,41 @@ jobs:
             sh -c "npm ci && npm test"
 
   examples:
-    name: >-
-      Test Examples
-
+    name: Test Examples
     runs-on: ubuntu-latest
-    needs:
-      - build
-
-    strategy:
-      fail-fast: false
-      matrix:
-        d:
-          - v2/e2e
-          - v2/graphql
-          - v2/jest
-          - v2/messages
-          - v2/mocha
-          - v2/serverless
-          - v2/typescript
-          - v3/e2e
-          - v3/graphql
-          - v3/provider-state-injected
-          - v3/run-specific-verifications
-          - v3/multipart
-          - v3/with-matching-rules
-          - v3/todo-consumer
-          - v3/typescript
-          - v4/graphql
-          - v4/matchers
-          - v4/plugins
-          - v4/messages
-          - v4/multipart
-          - v4/typescript
-          - v4/with-matching-rules
 
     steps:
-      - name: Checkout
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
-
-      - name: Setup Node.js ${{ env.STABLE_NODE_VERSION }}
-        uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
+      - uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6
         with:
           node-version: ${{ env.STABLE_NODE_VERSION }}
           cache: npm
-
-      # Temporary fix for lodash issue. This step should be removed eventually
-      # once a better solution is found.
-      - name: Install dependencies
-        run: npm ci
-
-      - name: Install plugins
-        run: npm run install-plugins
-
-      - name: Download dist folder
-        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8
-        with:
-          name: dist
-          path: dist
-
-      - name: Install dependencies
-        working-directory: examples/${{ matrix.d }}
-        run: npm ci
-
-      - name: Run tests
-        working-directory: examples/${{ matrix.d }}
-        run: npm run test
+      - run: npm ci
+      - run: npm run install-plugins
+      - name: Install and test examples
+        run: |
+          error_file=$(mktemp)
+          find examples \
+            -maxdepth 2 \
+            -name package.json \
+            -not -path '*/node_modules/*' \
+            -print0 | while IFS= read -r -d '' dir; do
+            pushd "$(dirname "$dir")" > /dev/null
+            echo "::group::$PWD"
+            if ! npm ci; then
+              echo "npm ci failed in $PWD" >> "$error_file"
+            fi
+            if ! npm run test; then
+              echo "npm run test failed in $PWD" >> "$error_file"
+            fi
+            echo "::endgroup::"
+            popd > /dev/null
+          done
+          if [ -s "$error_file" ]; then
+            echo "::error::Examples test failures occurred"
+            while IFS= read -r line; do
+              echo "::error::$line"
+            done < "$error_file"
+            rm "$error_file"
+            exit 1
+          fi

examples/README.md

@@ -0,0 +1,47 @@
+# pact-js Examples
+
+This directory contains educational examples for [pact-js](https://github.com/pact-foundation/pact-js), demonstrating consumer-driven contract testing with [Pact](https://docs.pact.io).
+
+**New to Pact? Start with [`http/`](./http/).**
+
+## The Pact Workflow
+
+```mermaid
+graph LR
+    A["Consumer test<br/>Define what you<br/>expect to receive"] -->|Pact file<br/>Written to disk<br/>by consumer test| B["Provider verification<br/>Provider proves it behaves<br/>as the consumer expects"]
+```
+
+1. The **consumer** writes a test that defines the interactions it needs. Pact generates a **pact file** (JSON) describing those interactions. In these examples, pact files are written to disk for simplicity.
+2. The **provider** runs the pact file against its real implementation, verifying each interaction in isolation.
+3. If the provider passes, both sides can deploy independently — neither will break the other.
+
+For team workflows, pact files are published to a Pact Broker (such as [PactFlow.io](https://pactflow.io) or the open source [Pact Broker](https://docs.pact.io/pact_broker)) to enable proper deployment checks like `can-i-deploy`.
+
+## Examples
+
+| Example                                | What it demonstrates                                             |
+| -------------------------------------- | ---------------------------------------------------------------- |
+| [`http/`](./http/)                     | **Start here.** Canonical HTTP consumer/provider                 |
+| [`matchers/`](./matchers/)             | Pact matcher library (`like`, `regex`, `eachLike`, etc.)         |
+| [`graphql/`](./graphql/)               | GraphQL over HTTP using `addGraphQLInteraction()`                |
+| [`messages/`](./messages/)             | Async/event-driven messaging with `addAsynchronousInteraction()` |
+| [`multipart/`](./multipart/)           | File upload and multipart form data                              |
+| [`plugins/`](./plugins/)               | Plugin system for custom protocols (gRPC, MATT, etc.)            |
+| [`provider-state/`](./provider-state/) | Provider states, parameterised states, and `fromProviderState()` |
+| [`xml/`](./xml/)                       | XML response matching with `XmlBuilder`                          |
+
+## Running an Example
+
+Each example is a standalone npm project:
+
+```bash
+cd examples/http
+npm install
+npm test          # runs consumer then provider
+npm run test:consumer   # generate pact file only
+npm run test:provider   # verify pact file only
+```
+
+## Historical Reference
+
+The previous `v2/`, `v3/`, and `v4/` examples are available in [git history](https://github.com/pact-foundation/pact-js/tree/3e1755a60934b366c2da95b998777c15f0236661/examples) for reference. The regression test suite covering the v2/v3 API surfaces lives in `regression/` at the repository root.

examples/graphql/README.md

@@ -0,0 +1,28 @@
+# GraphQL Example
+
+This example shows how to use Pact for GraphQL APIs. Pact treats GraphQL as a specialised form of HTTP. The contract captures the exact operation, variables, and response shape expected by the consumer.
+
+## What You'll Learn
+
+- Using `addGraphQLInteraction()` to define a GraphQL contract
+- How Pact normalises query whitespace so minor formatting changes don't break contracts
+- Provider verification works the same as HTTP — no special GraphQL tools needed
+
+## Running the Example
+
+```bash
+npm install
+npm test
+```
+
+## How It Works
+
+**Consumer** sends a `HelloQuery` operation as a POST to `/graphql`. Pact's `addGraphQLInteraction()` parses the query, records the operation name and variables, and normalises whitespace before matching. This means you can reformat your query string without breaking the contract.
+
+**Provider** implements the GraphQL schema using the `graphql` package and handles requests at `POST /graphql`. The Verifier replays the consumer's POST request and checks that the response matches.
+
+Pact verifies the *contract* between consumer and provider: whether the provider returns the right shape. Testing GraphQL query logic (resolvers, filters, pagination) belongs in the provider's own test suite.
+
+## Further Reading
+
+- [Pact GraphQL support](https://docs.pact.io/implementation_guides/javascript/docs/graphql)

examples/graphql/consumer.test.ts

@@ -0,0 +1,60 @@
+import path from 'node:path';
+import {
+  type LogLevel,
+  Matchers,
+  Pact,
+  SpecificationVersion,
+} from '@pact-foundation/pact';
+import { describe, expect, it } from 'vitest';
+import { fetchHello } from './consumer';
+
+const { like } = Matchers;
+
+/**
+ * Consumer Pact tests for the GraphQL Hello service.
+ *
+ * Pact treats GraphQL as a specialised form of HTTP: the interaction is still
+ * a POST request, but `addGraphQLInteraction()` parses the query body and
+ * normalises whitespace and field ordering when matching. You define the exact
+ * GraphQL operation, variables, and expected response shape.
+ *
+ * Important: Pact verifies the GraphQL *contract* (request shape + response
+ * shape), not the query logic. Use your GraphQL server's own tests for logic.
+ */
+describe('fetchHello — GraphQL consumer', () => {
+  const pact = new Pact({
+    consumer: 'GraphQLConsumer',
+    provider: 'GraphQLProvider',
+    spec: SpecificationVersion.SPECIFICATION_VERSION_V4,
+    dir: path.resolve(process.cwd(), 'pacts'),
+    logLevel: (process.env.LOG_LEVEL as LogLevel) ?? 'warn',
+  });
+
+  it('sends a HelloQuery and receives a greeting', async () => {
+    await pact
+      .addGraphQLInteraction()
+      .given('the hello service is available')
+      .uponReceiving('a HelloQuery request')
+      // addGraphQLInteraction() wraps the operation details and generates
+      // the correct POST body matcher automatically.
+      .withOperation('HelloQuery')
+      .withVariables({ name: 'World' })
+      .withRequest('POST', '/graphql')
+      .withQuery(`
+        query HelloQuery {
+          hello
+        }
+      `)
+      .willRespondWith(200, (builder) => {
+        builder.headers({ 'Content-Type': 'application/json; charset=utf-8' });
+        // like() on the greeting string: the provider may return any greeting,
+        // not specifically "Hello, World!". The contract only requires it to be
+        // a string at data.hello.
+        builder.jsonBody({ data: { hello: like('Hello, World!') } });
+      })
+      .executeTest(async (mockserver) => {
+        const greeting = await fetchHello(mockserver.url);
+        expect(greeting).toBe('Hello, World!');
+      });
+  });
+});

examples/graphql/consumer.ts

@@ -0,0 +1,41 @@
+import axios, { type AxiosResponse } from 'axios';
+
+/** The result of the HelloQuery operation. */
+export interface HelloQueryResult {
+  data: {
+    hello: string;
+  };
+}
+
+/**
+ * GraphQL client for the Hello service.
+ *
+ * GraphQL queries are sent as HTTP POST requests with a JSON body containing
+ * `query`, `operationName`, and `variables`. This is a plain HTTP call — no
+ * GraphQL client library is required for Pact testing.
+ *
+ * Pact's `addGraphQLInteraction()` understands the query structure and can
+ * normalise whitespace and field ordering when matching, which means minor
+ * formatting differences between consumer and provider don't break the contract.
+ */
+export async function fetchHello(baseUrl: string): Promise<string> {
+  const { data }: AxiosResponse<HelloQueryResult> = await axios.post(
+    `${baseUrl}/graphql`,
+    {
+      operationName: 'HelloQuery',
+      query: `
+        query HelloQuery {
+          hello
+        }
+      `,
+      variables: { name: 'World' },
+    },
+    {
+      headers: {
+        'Content-Type': 'application/json',
+        Accept: 'application/json',
+      },
+    },
+  );
+  return data.data.hello;
+}