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 -dThe self-hosted stack includes:
hoppscotch-app— the web frontendhoppscotch-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.comMaking 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
└── ResponseTest 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:
- Connects to any
ws://orwss://URL - Shows the connection state (connecting, connected, disconnected)
- Lets you send text frames manually
- Displays incoming messages with timestamps in a log
- 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:
- Global variables — available across all environments
- Environment variables — scoped to a specific environment (Dev, Staging, Production)
- 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 OrderThe 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.xmlExport 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: alwaysGitHub 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.xmlComparison: 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.