Get started

Yellow Jacket detects unintended HTTP behavior changes before your code is pushed.

It runs declared HTTP requests against your application, compares the responses with a known-good baseline and exits with an error when an unexpected change is detected.

Requirements

• Node.js 24.12+
• Git for hook installation

Install

Install Yellow Jacket as a development dependency:

npm install --save-dev @falche/yellow-jacket

The package exposes the yellow-jacket CLI command.

Verify the installed version with:

yellow-jacket --version

This command does not require a Yellow Jacket configuration.

Initialize a project

Move to the application you want to protect:

cd ~/project/my-app

Initialize Yellow Jacket:

yellow-jacket init

This creates:

yellow-jacket.config.mjs

A minimal configuration looks like this:

import {
  defineConfig
} from '@falche/yellow-jacket';

export default defineConfig({
  baseUrl:
    'http://localhost:3000',

  routes: [
    {
      name:
        'home',

      method:
        'GET',

      path:
        '/',

      expect: {
        status: 200
      }
    }
  ]
});

Create a baseline

Start your application, then run:

yellow-jacket baseline

Yellow Jacket stores the known-good responses in:

.yellow-jacket/snapshots/baseline.json

The baseline can be committed to Git.

Detect regressions

After modifying your application:

yellow-jacket run

A successful run exits with code 0.

An assertion failure or regression exits with code 1.

Install the Git hook

Install the pre-push integration:

yellow-jacket install

A normal:

git push

will then execute Yellow Jacket before the push is allowed to continue.

Mutating requests

POST, PUT, PATCH and DELETE requests are restricted to local targets by default.

Typical safe targets include:

localhost
*.localhost
127.0.0.0/8
::1

To explicitly authorize actions against another target:

yellow-jacket run \
  --allow-actions

The same option can be used when creating a baseline:

yellow-jacket baseline \
  --allow-actions

Use this override only for a target that is intentionally allowed to receive mutating requests.

.local names are not implicitly trusted because mDNS can resolve them to a different machine on the local network.

Redirects are checked before Yellow Jacket forwards a mutating method to their next destination. Use --allow-actions only when the complete redirect chain is intentionally authorized to receive actions.

Next

Continue with Configuration to declare routes, comparison rules and coverage sources.

Remove Yellow Jacket

To remove the integration while preserving configuration and snapshots:

yellow-jacket desetup

For a complete removal:

yellow-jacket desetup --purge

See Desetup / uninstall for the exact cleanup behavior.