apisnap-cli

Record API calls. Generate tests and mocks automatically.

       

No manual test writing • Real production data • Instant mock generation

Documentation • npm • Issues

Why apisnap-cli?

You built an app. It makes 50 API calls. Now you need integration tests, mocks for dev, and API docs. That takes hours of manual work.

# Record your app's traffic
apisnap record

# Use your app (login, browse, checkout...)
# ... 47 API calls captured ...

# Generate everything
apisnap stop
apisnap generate tests    # 47 Jest tests
apisnap generate mocks    # MSW request handlers
apisnap generate docs     # OpenAPI spec

Done in 2 minutes.

---

Table of Contents

• Quick Start
• Features
• Commands
• Generated Output Examples
• Use Cases
• Integration
• Architecture
• Development
• Contributing
• License

---

Quick Start

npm install -g apisnap-cli

apisnap record -n "my-flow"       # Start proxy on :8080
# ... use your app ...
apisnap stop                      # Stop recording
apisnap generate tests            # Generate Jest tests
apisnap generate mocks            # Generate MSW handlers

Set your app's proxy:

export HTTP_PROXY=http://localhost:8080
export HTTPS_PROXY=http://localhost:8080

---

Features

Feature	Description
HTTP Proxy	Intercepts all HTTP/HTTPS traffic transparently
Auto-Capture	Records requests, responses, timing, headers
Test Generation	Jest / Vitest tests from real captured data
Mock Generation	MSW / Nock handlers with actual responses
API Docs	OpenAPI 3.0 specs auto-generated
Session Replay	Reproduce exact API sequences for debugging
Diff Detection	Compare sessions to catch breaking changes
Local Storage	All data in SQLite — nothing leaves your machine

---

Commands

apisnap record — Start recording

apisnap record                           # Default port 8080
apisnap record -n "user-signup" -p 9000  # Named session, custom port

Flag	Description
-n, --name	Session name
-p, --port	Proxy port (default: 8080)
--env	Environment tag (dev, staging, prod)

apisnap stop — Stop and save

apisnap stop
# Recorded 47 API calls in 2m 14s

apisnap generate — Generate artifacts

apisnap generate tests              # Jest test files
apisnap generate tests -f vitest    # Vitest format
apisnap generate mocks              # MSW handlers
apisnap generate mocks -l nock      # Nock format
apisnap generate docs               # OpenAPI 3.0 spec

apisnap list — List sessions

apisnap list
apisnap list -l 50

apisnap replay — Replay a session

apisnap replay 123              # Replay all calls
apisnap replay 123 --delay 500  # With delay between requests

apisnap diff — Compare sessions

apisnap diff 123 456

API Differences:

Added endpoints:
  + POST /api/v2/users
  + GET /api/v2/settings

Removed endpoints:
  - GET /api/v1/legacy

Modified endpoints:
  ~ POST /api/users (response schema changed)

---

Generated Output Examples

Jest Test (generated)

import request from 'supertest';
import app from '../app';

describe('GET /users', () => {
  it('should return 200', async () => {
    const response = await request(app)
      .get('/users')
      .expect(200);

    expect(response.body).toBeDefined();
    expect(Array.isArray(response.body)).toBe(true);
  });
});

MSW Handler (generated)

import { rest } from 'msw';

export const handlers = [
  rest.get('/users', (req, res, ctx) => {
    return res(
      ctx.status(200),
      ctx.json([
        { id: 1, name: "Alice" },
        { id: 2, name: "Bob" }
      ])
    );
  }),

  rest.post('/users', (req, res, ctx) => {
    return res(
      ctx.status(201),
      ctx.json({ id: 3, name: "Charlie" })
    );
  }),
];

---

Use Cases

Integration Testing

# Before: Write tests manually, guess response structures
# After:
apisnap record → use app → apisnap generate tests
# 47 tests with real data in 2 minutes

Frontend Dev with Mocks

# Backend not ready? Record once it is, then work offline
apisnap generate mocks → npm run dev  # Uses generated MSW handlers

API Documentation

# Generate OpenAPI spec from real traffic
apisnap generate docs → import into Swagger UI

Debugging Production Issues

# Replay exact user flow locally
apisnap replay user-session-123

Catch Breaking Changes

apisnap diff pre-deploy post-deploy
# Shows all added/removed/modified endpoints

---

Integration

Works alongside the CLI toolchain:

# Track AI costs while recording
aitoken stats

# Save recording workflows
runbook set record "apisnap record -n test-flow"
runbook set generate "apisnap stop && apisnap generate tests && apisnap generate mocks"

---

Architecture

┌─────────────────────────────────────────────┐
│                apisnap-cli                  │
├──────────────────┬──────────────────────────┤
│   HTTP Proxy     │     Code Generators      │
│  (mitm-proxy)    │  (Jest, MSW, OpenAPI)    │
├──────────────────┴──────────────────────────┤
│         Session Manager & Differ            │
├─────────────────────────────────────────────┤
│             SQLite Database                 │
│        ~/.apisnap/recordings.db             │
└─────────────────────────────────────────────┘

All data stays on your machine. Nothing is sent anywhere.

---

Troubleshooting

Proxy connection issues

curl -x http://localhost:8080 http://example.com
echo $HTTP_PROXY

HTTPS certificate errors

# Dev only
export NODE_TLS_REJECT_UNAUTHORIZED=0

No calls recorded

1. Is your app configured to use the proxy?
2. Is the proxy port correct?
3. Are you making HTTP/HTTPS requests (not WebSockets)?

---

Roadmap

• WebSocket support
• GraphQL query extraction
• Automatic data sanitization
• Response schema validation
• Browser extension

---

Development

git clone https://github.com/brian-mwirigi/apisnap-cli.git
cd apisnap-cli
npm install
npm run build
npm link
apisnap record

Contributing

Contributions welcome! Please open an issue or submit a PR.

License

MIT

---

Built by Brian Munene Mwirigi

npm • Docs • Issues