meshtest is a CLI that turns any OpenAPI 3.x spec or Postman v2.1 collection into runnable, source-controlled regression tests against a live API. It auto-detects auth, generates CRUD chains with capture variables, and snapshots responses as baselines so you can diff against future runs.

If you want AI agents (Claude Desktop, Cursor, etc.) to drive this same engine over the Model Context Protocol, install @meshtest/server alongside it.

Install

# global (use the meshtest binary anywhere)
npm install -g @meshtest/cli

# project-local
npm install --save-dev @meshtest/cli
pnpm add -D @meshtest/cli

Node 18+ required.

Quickstart

# 1. Scaffold config, .env.example, and meshtest.auth.yaml
meshtest init

# 2. Import an OpenAPI spec or Postman collection into a runnable manifest
meshtest generate --from openapi ./openapi.yaml -o meshtest.yaml

# 3. Run live tests against your staging API
meshtest run --env staging

# 4. Record a baseline and diff future runs against it
meshtest diff --record
meshtest diff             # next time, fails if responses drifted

What you get

• Auto-imports — OpenAPI 3.x + Postman v2.1 → ready-to-run YAML manifest
• Auth auto-detection — bearer, api_key, basic, header, and OAuth2 client-credentials flows extracted from the source spec
• CRUD capture chains — POST → capture id → use in subsequent GET/PATCH/DELETE
• Setup/teardown hooks — seed and clean up test data per suite
• Built-in template vars — run_id, timestamp, iso_date, random_int, random_string
• Drift detection — store response snapshots, diff future runs, fail CI on unexpected changes
• Sensitive-data stripping — baseline.strip_on_record redacts secrets before they're written to disk
• Auto-discovery — --all finds every *.meshtest.yaml across configured registries

Example manifest

service:
  name: petstore
  base_url: https://api.petstore.example.com
  auth:
    type: bearer
    token: "${PETSTORE_TOKEN}"

vars:
  user_id: "${USER_ID}"

tests:
  - suite: Pet lifecycle
    tests:
      - name: Create a pet
        method: POST
        path: /pets
        body:
          name: "test-{{ vars.run_id }}"
        expect: { status: 201 }
        capture:
          pet_id: "$.id"

      - name: Get the created pet
        method: GET
        path: /pets/{{ captured.pet_id }}
        expect: { status: 200 }

      - name: Delete the pet
        method: DELETE
        path: /pets/{{ captured.pet_id }}
        expect: { status: 204 }

Anonymous telemetry

@meshtest/cli sends anonymous usage data to help us prioritise work. We collect command name, CLI/Node/OS version, and pass/fail counts — never service names, URLs, request/response bodies, or credentials. You are identified by a random UUID stored in ~/.meshtest/telemetry.json and nothing else.

Opt out any of these ways:

meshtest telemetry disable       # persists across runs
export DO_NOT_TRACK=1            # cross-tool standard
export MESHTEST_DISABLE_TELEMETRY=1

CI=true and NODE_ENV=test are honoured automatically. Set MESHTEST_TELEMETRY_DEBUG=1 to print the exact payload to stderr so you can verify what's being sent before you decide. Full details: Telemetry docs.

Documentation

Full reference, guides, and recipes: meshtest.dev/docs

Quick links:

• Quickstart — 60-second walkthrough
• CLI reference — every command and flag
• Manifest schema — every YAML field
• Authentication guide — bearer, api-key, OAuth2, profiles
• Test data management — capture chains, setup/teardown, built-in vars
• Baselines & drift — record, diff, strip-on-record
• Telemetry — what we collect, how to opt out

Bugs & feature requests

File issues at meshtest-issues-tracker. The main repo is private; this tracker is the public inbox for both @meshtest/cli and @meshtest/server. Include your OS, Node version (node -v), CLI version (meshtest --version), and a minimal manifest that reproduces the issue when possible.

License

See the LICENSE file included with this package. Free for personal, commercial, and internal business use. Source is not redistributed.

— Mukul Kumar · github.com/developerKumar