api Spector

Local-first API testing tool. Inspect, test and mock APIs. Secrets stay on your machine.

• GUI built with Electron + React
• CLI for running tests and mock servers in CI/CD pipelines
• Robot Framework & Playwright code generation
• AES-256-GCM encrypted secrets, never stored in plain text

Install

npm install -g @testsmith/api-spector

Usage

GUI

api-spector ui

Opens the desktop app. On first launch you'll be prompted to open or create a workspace.

Run tests

api-spector run --workspace ./my-workspace.spector [options]

| Option | Description | |---|---| | --workspace <path> | Path to .spector workspace file (required) | | --env <name> | Environment name to activate | | --collection <name> | Limit to a specific collection | | --tags <a,b> | Comma-separated tag filter | | --output <path> | Write results to file (.json or .xml) | | --format json\|junit | Output format (inferred from --output extension) | | --verbose | Print per-request console output and test details | | --bail | Stop after first failure |

Exit code 0 = all passed, 1 = failures/errors.

Start mock servers

api-spector mock --workspace ./my-workspace.spector [options]

| Option | Description | |---|---| | --workspace <path> | Path to .spector workspace file (required) | | --name <name> | Start only the named server (repeat for multiple) |

Keeps running until Ctrl+C.

Workspaces

A workspace is a .spector file that references your collections, environments and mock servers. Safe to commit to Git. Secrets are encrypted, not stored in plain text.

my-project/
├── my-workspace.spector
├── collections/
│   └── my-api.spector
└── environments/
    ├── dev.env.json
    └── prod.env.json

Encrypted secrets

Secret variables are encrypted with AES-256-GCM using a master password. Set API_SPECTOR_MASTER_KEY in your shell profile to avoid being prompted each session:

macOS / Linux (~/.zshrc or ~/.bashrc):

export API_SPECTOR_MASTER_KEY="your-password"

Windows (PowerShell profile):

$env:API_SPECTOR_MASTER_KEY = "your-password"

Windows (Command Prompt, permanent):

setx API_SPECTOR_MASTER_KEY "your-password"

CI/CD

Set API_SPECTOR_MASTER_KEY as a secret in your pipeline:

# GitHub Actions
env:
  API_SPECTOR_MASTER_KEY: ${{ secrets.API_SPECTOR_MASTER_KEY }}

If the key is not set, encrypted secrets will not be resolved and a warning will appear in the console output.

Development

# Install dependencies
npm install

# Start in dev mode (hot reload)
npm run dev

# Build
npm run build

# Package as native app (macOS / Windows / Linux)
npm run package

License

MIT