Hoppscotch API Testing: Open-Source, Self-Hosted, and WebSocket-Ready

Hoppscotch API Testing: Open-Source, Self-Hosted, and WebSocket-Ready

Hoppscotch started as "Postwoman" — a browser-based Postman alternative — and has grown into a full-featured API development platform with a distinctive focus on openness: open-source codebase, self-hosting support, and support for protocols beyond REST that most tools treat as afterthoughts.

If your stack includes WebSockets, Server-Sent Events, MQTT, Socket.IO, or GraphQL subscriptions alongside regular REST endpoints, Hoppscotch handles all of them from a single interface. That's unusual and genuinely useful.

What Sets Hoppscotch Apart

Most API testing tools are REST-first and bolt on other protocols later. Hoppscotch was built with protocol diversity in mind from the beginning:

  • REST — full HTTP support with all methods, headers, auth schemes
  • GraphQL — query editor with schema introspection, subscriptions, variables
  • WebSocket — connect, send frames, receive messages, all in one view
  • Socket.IO — connect to Socket.IO servers and exchange events
  • SSE — Server-Sent Events listener
  • MQTT — connect to MQTT brokers and subscribe to topics

For teams building real-time features, this eliminates the need for separate tools for different connection types.

Installation Options

Use the Hosted Version

The quickest path is hoppscotch.io — no install required. Sign in with Google or GitHub and you have team workspaces and sync immediately.

Self-Host with Docker

For teams with data privacy requirements or air-gapped environments, Hoppscotch provides official Docker images:

# Clone the repo
git clone https://github.com/hoppscotch/hoppscotch
cd hoppscotch

# Copy and configure environment
cp .env.example .env
# Edit .env — set DATABASE_URL, SMTP settings, OAuth credentials

# Start all services
docker compose up -d

The self-hosted stack includes:

  • hoppscotch-app — the web frontend
  • hoppscotch-backend — the API server (NestJS)
  • hoppscotch-admin — admin dashboard
  • PostgreSQL — persistence
  • (optional) nginx reverse proxy

After starting, access the app at http://localhost:3000 and the admin panel at http://localhost:3100.

Environment Configuration

Key settings in .env:

# Database
DATABASE_URL=postgresql://postgres:postgres@hoppscotch-db:5432/hoppscotch

# JWT secrets (generate with: openssl rand -hex 32)
JWT_SECRET=<your-secret>
SESSION_SECRET=<your-secret>

# OAuth providers (at least one required)
GOOGLE_CLIENT_ID=<your-id>
GOOGLE_CLIENT_SECRET=<your-secret>

# Email (for magic link auth)
MAILER_SMTP_URL=smtps://user:pass@smtp.example.com

# App URLs
VITE_BASE_URL=https://api.yourdomain.com
VITE_SHORTCODE_BASE_URL=https://hoppscotch.yourdomain.com
VITE_ADMIN_URL=https://admin.yourdomain.com

Making REST Requests

The REST interface is straightforward. What's notable is the organization of the request builder:

Method + URL
├── Query Params    (key-value table, supports variables)
├── Headers         (pre-populated with common headers)
├── Body            (JSON, Form, Multipart, Raw, Binary)
├── Auth            (None, Basic, Bearer, OAuth 2.0, API Key, AWS Sig v4)
├── Pre-Request Script
├── Tests
└── Response

Test scripts use JavaScript with a Chai-like assertion API:

// In the Tests tab
pw.test("Status is 200", () => {
  pw.expect(pw.response.status).toBe(200);
});

pw.test("Response has required fields", () => {
  const body = pw.response.body;
  pw.expect(body).toHaveProperty("id");
  pw.expect(body).toHaveProperty("created_at");
  pw.expect(typeof body.id).toBe("string");
});

pw.test("Response time under 1s", () => {
  pw.expect(pw.response.responseTime).toBeLessThan(1000);
});

// Store value for downstream requests
pw.env.set("userId", pw.response.body.id);

Pre-request scripts run before the request is sent:

// Pre-request script
const timestamp = Date.now();
pw.env.set("requestTimestamp", timestamp.toString());
pw.env.set("signature", btoa(`${timestamp}:${pw.env.get("apiSecret")}`));

GraphQL Testing

The GraphQL client is a first-class feature, not an afterthought. It includes:

  • Schema browser — fetches and displays your schema from any introspection endpoint
  • Query editor — syntax highlighting, autocomplete from schema
  • Variables panel — JSON editor for query variables
  • Headers — custom headers including auth
  • Subscriptions — real-time subscription support over WebSocket

Example interaction with a GraphQL endpoint:

# Query with variables
query GetUserOrders($userId: ID!, $status: OrderStatus) {
  user(id: $userId) {
    id
    email
    orders(status: $status) {
      id
      total
      createdAt
      items {
        product {
          name
          sku
        }
        quantity
        unitPrice
      }
    }
  }
}

Variables:

{
  "userId": "{{userId}}",
  "status": "PENDING"
}

Hoppscotch will introspect the schema, validate your query against it, and flag type errors before you even send the request.

WebSocket Testing

Testing WebSocket APIs is where Hoppscotch genuinely earns its keep. The WebSocket client:

  1. Connects to any ws:// or wss:// URL
  2. Shows the connection state (connecting, connected, disconnected)
  3. Lets you send text frames manually
  4. Displays incoming messages with timestamps in a log
  5. Supports custom headers for the initial handshake

Example connection flow for a real-time chat API:

Connect to: wss://api.example.com/ws?token={{authToken}}

Headers:
  Sec-WebSocket-Protocol: chat-v1

// Once connected, send:
{
  "type": "subscribe",
  "channel": "user.notifications",
  "userId": "{{userId}}"
}

// Observe incoming frames:
{"type": "notification", "message": "Order shipped", "timestamp": 1685000000}
{"type": "ping", "timestamp": 1685000001}

This is dramatically more convenient than writing a quick WebSocket test script just to verify a connection handshake during development.

Team Workspaces

Hoppscotch's workspace model is similar to Postman's — collections, environments, and history are shared within a workspace, and access is controlled by role.

Workspace roles:

  • Owner — full access, can invite/remove members, manage billing
  • Editor — create and modify collections, environments
  • Viewer — read-only access to all collections

Sharing collections:

Collections can be shared as a link (shortcode) without requiring the recipient to have a Hoppscotch account. This is useful for sharing a specific request with a stakeholder or API consumer.

In the self-hosted version, all workspace data stays on your infrastructure. The sync backend is open source and you control the database.

Variables and Environments

Environment variables in Hoppscotch follow a three-tier model:

  1. Global variables — available across all environments
  2. Environment variables — scoped to a specific environment (Dev, Staging, Production)
  3. Request-local variables — set by pre-request scripts, scoped to the request
Global:
  apiVersion: v2

Environment (staging):
  baseUrl: https://api.staging.example.com
  authToken: <staging token>

Environment (production):
  baseUrl: https://api.example.com
  authToken: <prod token>

In requests, variables are referenced with double braces: {{baseUrl}}/{{apiVersion}}/users

Hoppscotch also supports secret variables — values marked as secret are stored encrypted and not visible in the UI after saving.

Collections and Runner

Collections organize requests into folders, and the Collection Runner executes them in sequence:

Collection structure:

E-commerce API
├── Authentication
│   ├── Login
│   ├── Refresh Token
│   └── Logout
├── Products
│   ├── List Products
│   ├── Get Product
│   └── Search Products
└── Orders
    ├── Create Order
    ├── Get Order
    └── Cancel Order

The Collection Runner lets you:

  • Run the entire collection or a selected folder
  • Set iteration count for load-like testing
  • Inject environment variables
  • View per-request pass/fail results
  • Export results

CLI Integration (Hopp CLI)

For CI/CD pipelines, Hoppscotch provides @hoppscotch/cli:

npm install -g @hoppscotch/cli

# Run a collection exported from Hoppscotch
hopp test collection.json --env environment.json

# Run with specific reporter
hopp test collection.json --env environment.json --reporter-junit results.xml

Export your collection and environment from the Hoppscotch UI, then use them in CI:

GitLab CI Example

api-tests:
  image: node:20-alpine
  stage: test
  before_script:
    - npm install -g @hoppscotch/cli
  script:
    - hopp test collections/api-tests.json 
        --env environments/staging.json 
        --reporter-junit results/api-tests.xml
  artifacts:
    reports:
      junit: results/api-tests.xml
    when: always

GitHub Actions Example

name: API Tests
on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'

      - name: Install Hopp CLI
        run: npm install -g @hoppscotch/cli

      - name: Run API tests
        env:
          API_BASE_URL: ${{ vars.STAGING_URL }}
          AUTH_TOKEN: ${{ secrets.STAGING_TOKEN }}
        run: |
          # Inject secrets into environment file
          envsubst < environments/staging.template.json > environments/staging.json
          hopp test collections/regression.json \
            --env environments/staging.json \
            --reporter-junit test-results.xml

      - name: Upload results
        uses: actions/upload-artifact@v4
        if: always()
        with:
          name: api-test-results
          path: test-results.xml

Comparison: Hoppscotch vs. Alternatives

Capability Hoppscotch Postman Insomnia Bruno
WebSocket support First-class Limited Plugin No
GraphQL subscriptions Yes Limited Yes No
MQTT / SSE Yes No No No
Self-hosting Full stack No Partial N/A (desktop)
Open source Yes No Partial Yes
Browser-based Yes Desktop/web Desktop Desktop only
Git-native format No No No Yes
CLI for CI Yes (hopp) Yes (newman) Yes (inso) Yes (bru)

Practical Tips

Use request descriptions liberally. Hoppscotch supports markdown in request descriptions. Document the expected behavior, auth requirements, and example payloads inline — your teammates will thank you.

Pin environment before running collections. Accidentally running a destructive test suite against production because the wrong environment was active is a rite of passage. Hoppscotch's environment selector is visible but easy to overlook — build a habit of checking before running.

Export collections regularly for backup. Even in self-hosted mode, export your collections to JSON and commit them to your repository. This serves as a backup and makes the collection available to the CLI without hitting your Hoppscotch server.

Use the interceptor for authenticated browser sessions. Hoppscotch offers a browser extension interceptor that forwards cookies from your active browser session to API requests, eliminating the need to copy auth tokens manually during development.

Summary

Hoppscotch earns its place if your stack involves real-time protocols, you want a self-hosted solution for data sovereignty, or you need a browser-based tool that doesn't require desktop installation. The GraphQL, WebSocket, and SSE support is genuinely mature, not just a checkbox.

The main limitation is the CLI tooling is less mature than Postman's newman — the Hopp CLI is functional but lacks some of the reporting and retry options. For pure REST API testing, Bruno or Postman may offer a smoother CI experience, but for polyglot protocol testing, Hoppscotch is hard to beat.

Read more

Start now free