Hoppscotch

REST, GraphQL, WebSocket 및 실시간 API 테스트를 위한 오픈소스 API 개발 생태계이자 Postman의 경량 대안 도구입니다.

설치

웹 및 데스크톱

명령어	설명
hoppscotch.io로 이동	Hoppscotch 웹 앱 열기 (설치 불필요)
hoppscotch.io/download에서 다운로드	데스크톱 앱 설치 (macOS, Windows, Linux)
GitHub, Google 또는 이메일로 로그인	팀 동기화를 위한 계정 생성
브라우저 PWA 설치 옵션	프로그레시브 웹 앱으로 설치

CLI 설치

명령어	설명
npm install -g @hoppscotch/cli	npm으로 CLI 전역 설치
npx @hoppscotch/cli	설치 없이 CLI 실행
hopp --version	CLI 버전 확인
hopp --help	CLI 도움말 표시

셀프 호스팅 설치

명령어	설명
docker pull hoppscotch/hoppscotch	Docker 이미지 가져오기
docker compose up -d	셀프 호스팅 인스턴스 시작

셀프 호스팅 Docker Compose

# 셀프 호스팅 Hoppscotch를 위한 docker-compose.yml
version: "3"
services:
  hoppscotch:
    image: hoppscotch/hoppscotch:latest
    ports:
      - "3000:3000"   # Web UI
      - "3100:3100"   # Admin dashboard
      - "3170:3170"   # Backend API
    environment:
      DATABASE_URL: postgresql://user:pass@db:5432/hoppscotch
      JWT_SECRET: your-jwt-secret-here
      TOKEN_SALT_COMPLEXITY: 10
      MAGIC_LINK_TOKEN_VALIDITY: 3
      REFRESH_TOKEN_VALIDITY: 604800000
      ACCESS_TOKEN_VALIDITY: 86400000
      VITE_ALLOWED_AUTH_PROVIDERS: GITHUB,GOOGLE,EMAIL
    depends_on:
      - db

  db:
    image: postgres:15
    volumes:
      - postgres_data:/var/lib/postgresql/data
    environment:
      POSTGRES_USER: user
      POSTGRES_PASSWORD: pass
      POSTGRES_DB: hoppscotch

volumes:
  postgres_data:

HTTP 요청

요청 보내기

명령어	설명
메서드 선택 (GET, POST, PUT, DELETE, PATCH)	드롭다운에서 HTTP 메서드 선택
주소 표시줄에 URL 입력	요청 엔드포인트 설정
”Send” 클릭	요청 실행
Ctrl + Enter	요청 보내기 (키보드 단축키)
Ctrl + G	요청 보내고 응답 다운로드
Ctrl + K	명령 팔레트 열기

요청 본문

명령어	설명
”Body” 탭 클릭 → 유형 선택	요청 본문 형식 설정
”application/json” 선택	JSON 본문 (가장 일반적)
“multipart/form-data” 선택	파일 업로드
”application/x-www-form-urlencoded” 선택	폼 데이터
”text/plain” 선택	일반 텍스트 본문
”application/xml” 선택	XML 본문
”Binary” 선택	원시 바이너리 데이터

헤더 및 매개변수

명령어	설명
”Headers” 탭 클릭 → 헤더 추가	사용자 정의 요청 헤더 추가
”Parameters” 탭 클릭	URL 쿼리 매개변수 추가
헤더 일괄 편집 모드	여러 헤더를 한 번에 붙여넣기
헤더 활성/비활성 토글	삭제하지 않고 비활성화
값에 <<variable>> 사용	환경 변수 참조

응답 검사

명령어	설명
응답 본문 보기	JSON, HTML, XML, 바이너리, 이미지
응답의 “Headers” 탭 클릭	응답 헤더 검사
상태 코드 및 시간 표시	HTTP 상태, 지연 시간, 크기
응답에서 “Copy” 클릭	응답을 클립보드에 복사
”Download” 클릭	응답을 파일로 다운로드
JSON 응답 자동 포맷	접이식 트리 뷰
”Timeline” 클릭	요청/응답 타임라인 보기

요청 예시

Method:  POST
URL:     https://api.example.com/users
Headers:
  Content-Type: application/json
  Authorization: Bearer <<auth_token>>

Body (JSON):
{
  "name": "Alice Smith",
  "email": "alice@example.com",
  "role": "admin"
}

Response: 201 Created (145ms, 234 B)
{
  "id": 42,
  "name": "Alice Smith",
  "email": "alice@example.com",
  "role": "admin",
  "created_at": "2024-01-15T10:30:00Z"
}

컬렉션

컬렉션 관리

명령어	설명
컬렉션 패널에서 ”+” 클릭	새 컬렉션 생성
컬렉션 우클릭 → “New Request”	컬렉션에 요청 추가
컬렉션 우클릭 → “New Folder”	하위 폴더로 정리
폴더 간 요청 드래그	컬렉션 항목 재정렬
우클릭 → “Duplicate”	컬렉션 복제
우클릭 → “Properties”	컬렉션 설정 편집
우클릭 → “Delete”	컬렉션 삭제
Ctrl + Shift + P	컬렉션 내 검색

가져오기 및 내보내기

명령어	설명
”Import” 클릭 → 파일 선택	컬렉션 가져오기
우클릭 → “Export”	컬렉션을 JSON으로 내보내기
Postman Collection v2에서 가져오기	Postman 호환
OpenAPI/Swagger 스펙에서 가져오기	요청 자동 생성
Insomnia에서 가져오기	Insomnia 호환
cURL에서 가져오기	cURL 명령 붙여넣기
HAR에서 가져오기	HTTP 아카이브 가져오기

가져오기 예시

Supported import formats:
  - Hoppscotch Collection (native JSON)
  - Postman Collection v2
  - OpenAPI 3.0 / Swagger 2.0
  - Insomnia v4
  - cURL commands
  - HAR (HTTP Archive)

Import from cURL:
  Paste a cURL command directly into the URL bar
  Hoppscotch auto-parses method, headers, body, and URL

환경 변수

환경 관리

명령어	설명
사이드바에서 “Environments” 클릭	환경 관리자 열기
”+“를 클릭하여 환경 생성	새 환경 만들기
key: value 쌍 추가	변수 정의
요청에서 <<variable_name>> 사용	모든 필드에서 변수 참조
드롭다운에서 환경 선택	환경 활성화
”Global” 탭 클릭	전역 변수 설정 (항상 활성)
우클릭 → “Export”	환경을 JSON으로 내보내기
우클릭 → “Duplicate”	환경 복제

변수 유형

유형	설명
일반 변수	UI에서 표시, 컬렉션에 내보내기 가능
비밀 변수	UI에서 마스킹, 내보내기 불가
전역 변수	모든 환경에서 사용 가능
환경 변수	환경이 활성화된 경우에만 사용 가능

환경 예시

Environment: "Production"
┌───────────────┬──────────────────────────────┬──────────┐
│ Key           │ Value                        │ Type     │
├───────────────┼──────────────────────────────┼──────────┤
│ base_url      │ https://api.example.com      │ Regular  │
│ api_version   │ v2                           │ Regular  │
│ auth_token    │ eyJhbGciOiJIUzI1NiIsIn...    │ Secret   │
│ timeout       │ 30000                        │ Regular  │
└───────────────┴──────────────────────────────┴──────────┘

Usage in requests:
  URL:    <<base_url>>/<<api_version>>/users
  Header: Authorization: Bearer <<auth_token>>

인증

인증 유형

명령어	설명
”Bearer Token” 선택	Bearer 토큰 인증 추가
”Basic Auth” 선택	사용자 이름/비밀번호 인증
”OAuth 2.0” 선택	OAuth 2.0 흐름 구성
”API Key” 선택	헤더 또는 쿼리 매개변수에 API 키 추가
”AWS Signature” 선택	AWS Signature V4 인증
”Inherit from parent” 선택	컬렉션에서 인증 상속
”None” 선택	인증 제거
토큰 필드에 <<variables>> 지원	인증 토큰에 환경 변수 사용

OAuth 2.0 구성

OAuth 2.0 Configuration:
  Grant Type:       Authorization Code
  Auth URL:         https://auth.example.com/authorize
  Token URL:        https://auth.example.com/token
  Client ID:        <<client_id>>
  Client Secret:    <<client_secret>>
  Scope:            read write
  Redirect URI:     Auto-configured

Supported grant types:
  - Authorization Code (+ PKCE)
  - Client Credentials
  - Implicit
  - Password Credentials

실시간 테스트

WebSocket

명령어	설명
”Realtime” → “WebSocket” 클릭	WebSocket 클라이언트 열기
wss:// URL 입력	WebSocket 엔드포인트 설정
”Connect” 클릭	연결 수립
메시지 입력 → “Send” 클릭	서버로 메시지 전송
로그 패널에서 메시지 보기	수신/발신 모니터링
”Disconnect” 클릭	연결 종료
프로토콜/헤더 추가	연결 매개변수 구성

Server-Sent Events (SSE)

명령어	설명
”Realtime” → “SSE” 클릭	Server-Sent Events 테스트
SSE 엔드포인트 URL 입력	이벤트 스트림 URL 설정
”Connect” 클릭	이벤트 수신 시작
실시간으로 이벤트 기록	이벤트 스트림 모니터링
”Disconnect” 클릭	수신 중지

MQTT

명령어	설명
”Realtime” → “MQTT” 클릭	MQTT 연결 테스트
mqtt:// 또는 wss:// URL 입력	MQTT 브로커 URL 설정
Client ID, 사용자 이름, 비밀번호 설정	자격 증명 구성
토픽 구독	메시지 수신 대기
토픽에 게시	메시지 전송

Socket.IO

명령어	설명
”Realtime” → “Socket.IO” 클릭	Socket.IO 연결 테스트
서버 URL 입력	Socket.IO 엔드포인트 설정
이벤트 수신 대기	명명된 이벤트 구독
데이터와 함께 이벤트 발신	명명된 이벤트 전송
연결 상태 보기	연결/해제 모니터링

GraphQL

GraphQL 테스트

명령어	설명
”GraphQL” 탭 클릭	GraphQL 모드로 전환
GraphQL 엔드포인트 URL 입력	GraphQL 서버 URL 설정
편집기 패널에 쿼리 작성	GraphQL 쿼리 구성
”Schema” 클릭하여 스키마 가져오기	자동 완성을 위한 서버 스키마 로드
Variables 패널에 변수 추가	쿼리 변수를 JSON으로 설정
인증용 헤더 추가	인증 헤더 설정
”Run” 또는 Ctrl + Enter 클릭	쿼리 실행
스키마에서 자동 완성 사용	필드 제안 받기

GraphQL 예시

Endpoint: https://api.example.com/graphql

Query:
  query GetUsers($limit: Int!) {
    users(limit: $limit) {
      id
      name
      email
      posts {
        title
        createdAt
      }
    }
  }

Variables:
  {
    "limit": 10
  }

Headers:
  Authorization: Bearer <<auth_token>>

CLI 사용법

컬렉션 실행

명령어	설명
hopp test collection.json	컬렉션 테스트 실행
hopp test collection.json -e environment.json	환경과 함께 실행
hopp test collection.json --delay 500	요청 간 지연 (ms)
hopp test collection.json --reporter junit	JUnit 테스트 보고서 출력
hopp test collection.json --reporter json	JSON 테스트 보고서 출력
hopp test collection.json --bail	첫 번째 실패 시 중지
hopp test collection.json --env-var KEY=VALUE	환경 변수 덮어쓰기

CLI 예시

# Run collection with environment
hopp test api-tests.json -e production.json

# Run with delay and stop on failure
hopp test api-tests.json --delay 1000 --bail

# Generate JUnit report for CI/CD
hopp test api-tests.json --reporter junit > results.xml

# Override specific variables
hopp test api-tests.json \
  --env-var "base_url=https://staging.example.com" \
  --env-var "auth_token=test-token-123"

# CI/CD pipeline example
hopp test api-tests.json -e staging.json --bail --reporter junit

사전 요청 및 사후 요청 스크립트

스크립팅

명령어	설명
”Pre-request” 탭 클릭	요청 전에 실행할 스크립트 추가
”Tests” 탭 클릭	응답 후에 실행할 스크립트 추가
pw.env.set("key", "value")	환경 변수 설정
pw.env.get("key")	환경 변수 가져오기
pw.expect(response.status).toBe(200)	상태 코드 검증
pw.expect(response.body).toHaveProperty("id")	본문 속성 검증

테스트 스크립트 예시

// Pre-request: Generate timestamp
pw.env.set("timestamp", Date.now().toString());

// Pre-request: Generate random ID
pw.env.set("random_id", Math.random().toString(36).slice(2));

// Test: Check status code
pw.test("Status is 200", () => {
  pw.expect(pw.response.status).toBe(200);
});

// Test: Check response body
pw.test("Response has user data", () => {
  const body = pw.response.body;
  pw.expect(body).toHaveProperty("id");
  pw.expect(body).toHaveProperty("name");
  pw.expect(body.name).toBe("Alice");
});

// Test: Check response time
pw.test("Response is fast", () => {
  pw.expect(pw.response.status).toBeLessThan(500);
});

// Test: Save token for next request
pw.test("Extract auth token", () => {
  const token = pw.response.body.access_token;
  pw.env.set("auth_token", token);
});

키보드 단축키

전역

단축키	설명
Ctrl + Enter	요청 보내기
Ctrl + K	명령 팔레트
Ctrl + S	현재 요청 저장
Ctrl + Shift + P	컬렉션 검색
Ctrl + /	사이드바 토글
Alt + ↑	히스토리의 이전 요청
Alt + ↓	히스토리의 다음 요청
F11	전체 화면 토글

팀 및 협업

명령어	설명
사이드바에서 팀 생성	팀 작업 공간 설정
이메일로 멤버 초대	협업자 추가
공유 컬렉션	팀 전체 요청 라이브러리
공유 환경	팀 전체 변수 세트
실시간 협업	팀 편집 내용 실시간 확인
역할 기반 접근 제어	소유자, 편집자, 뷰어 역할

모범 사례

1. API 도메인별로 컬렉션 정리 — 관련 엔드포인트를 컬렉션에 그룹화하고 리소스 유형(users, orders, products)별 폴더를 사용하여 쉽게 찾을 수 있게 합니다.

2. 스테이징과 프로덕션용 환경 사용 — 개발, 스테이징, 프로덕션을 위한 별도 환경을 같은 변수 이름으로 생성하되 다른 값을 사용합니다. 한 번의 클릭으로 전환합니다.

3. 비밀 변수로 시크릿 저장 — API 키와 토큰을 “secret” 유형으로 표시하여 UI에서 마스킹하고 내보내기에서 제외합니다.

4. 인증에 사전 요청 스크립트 사용 — 타임스탬프 생성, 서명 계산 또는 토큰 갱신을 수동으로 복사하는 대신 각 요청 전에 자동으로 수행합니다.

5. 중요 엔드포인트에 테스트 작성 — 상태 코드, 응답 구조 및 주요 값을 검증하는 테스트 스크립트를 추가합니다. CI/CD 파이프라인에서 CLI로 실행합니다.

6. OpenAPI 스펙에서 가져오기 — 문서화된 API 작업 시 OpenAPI/Swagger 스펙을 가져와 올바른 매개변수로 모든 엔드포인트를 자동 생성합니다.

7. 컬렉션 수준 인증 사용 — 컬렉션 수준에서 인증을 설정하고 개별 요청에서 “Inherit from parent”를 사용하여 인증 구성 중복을 방지합니다.

8. 컬렉션을 버전 관리에 내보내기 — 컬렉션을 JSON으로 내보내고 리포지토리에 커밋하여 버전 관리 및 팀 공유를 합니다.

9. CI/CD에서 CLI 사용 — 파이프라인에 hopp test를 추가하여 모든 배포 시 API 테스트를 실행하여 엔드포인트가 가동 전에 작동하는지 확인합니다.

10. 민감한 API를 위한 셀프 호스팅 — 내부 또는 민감한 API 테스트 시 셀프 호스팅 Docker 버전을 배포하여 모든 데이터를 인프라 내에 유지합니다.