Claude Code for Hoppscotch — Workflow Guide

Written by Michael Lip · Solo founder of Zovo · $400K+ on Upwork · 100% JSS Join 50+ builders · More at zovo.one

The Setup

You are using Hoppscotch as your API testing platform — the open-source Postman alternative. Claude Code can generate API requests, collections, and test scripts for Hoppscotch, but it formats output for Postman or cURL instead of Hoppscotch’s collection format and misses Hoppscotch-specific features like environments and pre-request scripts.

What Claude Code Gets Wrong By Default

  1. Generates Postman collection JSON format. Claude exports API collections in Postman’s v2.1 format. Hoppscotch uses its own JSON format for collections and cannot directly import Postman files without conversion.

  2. Uses Postman’s pm.* scripting API. Claude writes pre-request and test scripts with pm.environment.set() and pm.response.json(). Hoppscotch uses a different scripting API with pw.* functions.

  3. Ignores Hoppscotch’s environment variable syntax. Claude uses {{variable}} which looks correct but Hoppscotch processes variables differently in headers vs body. Claude does not distinguish between these contexts.

  4. Creates separate cURL commands instead of collections. Claude generates individual cURL commands for testing. Hoppscotch organizes requests into collections with shared auth, environments, and test flows.

The CLAUDE.md Configuration


# Hoppscotch API Testing

## Tool
- API Client: Hoppscotch (self-hosted or hoppscotch.io)
- Collections: JSON format in .hoppscotch/ directory
- CLI: @hoppscotch/cli for CI/CD API testing
- Environments: dev, staging, prod variable sets

## Hoppscotch Rules
- Use Hoppscotch collection format, NOT Postman format
- Pre-request scripts use pw.* API (pw.env.set, pw.env.get)
- Test scripts use pw.expect() assertions
- Variables use <<variable>> in some contexts
- Auth tokens stored in environment variables, not hardcoded
- Collections exported as JSON for version control

## Conventions
- Collections in .hoppscotch/collections/ directory
- Environments in .hoppscotch/environments/ directory
- Base URL in environment variable: {{baseUrl}}
- Auth token in environment: {{authToken}}
- Run CI tests: hopp test -e environment.json collection.json
- One collection per API domain (users, projects, billing)

Workflow Example

You want to create API tests for a new endpoint. Prompt Claude Code:

“Create a Hoppscotch collection for the /api/projects CRUD endpoints. Include environment variables for the base URL and auth token, add pre-request scripts to set the auth header, and write test assertions for status codes and response shapes.”

Claude Code should produce a Hoppscotch-format JSON collection with GET, POST, PUT, DELETE requests, environment files with baseUrl and authToken variables, pre-request scripts using pw.env.get("authToken") to set the Authorization header, and test scripts using pw.expect() assertions.

Common Pitfalls

  1. CLI collection format mismatch. Claude generates collection JSON that works in the Hoppscotch web UI but fails with @hoppscotch/cli. The CLI expects exported collection format — re-export from the UI or ensure the JSON matches the CLI schema.

  2. Environment variable scoping. Claude sets variables in pre-request scripts expecting them to persist across requests. Hoppscotch environment variables set via pw.env.set() persist for the session but may not save to the environment file. Use global environments for persistent values.

  3. Self-hosted auth configuration. Claude configures Hoppscotch requests against a self-hosted instance but forgets that self-hosted Hoppscotch may need CORS headers from your API. Add your Hoppscotch instance origin to the API’s allowed origins list.