Using Hoppscotch Environment Variables for Dynamic API Testing

The Problem: Hardcoded Values Break Test Portability

When testing APIs across development, staging, and production environments, hardcoding base URLs, authentication tokens, and query parameters into every request creates maintenance overhead. Each environment change requires editing dozens of requests manually. Hoppscotch solves this with workspace‑scoped environment variables that substitute at request time using the {{variableName}} syntax.

Desired Outcome

A single request collection that works across multiple environments by swapping variable values—no request edits required. Define variables once per environment, reference them in requests, and verify substitution works before relying on it in automated flows.

Prerequisites

• Hoppscotch v2.5.0 or later (web app at hoppscotch.io or self‑hosted instance)
• A workspace with at least one saved request
• Permission to create and edit environment variables in the workspace (owner or editor role)

Step 1: Create an Environment and Define Variables

1. Open the workspace sidebar and click Environments (flask icon).
2. Click New Environment, name it (e.g., development), and confirm.
3. Add variables using the Key/Value table:
   • baseUrl → https://api.dev.example.com
   • apiKey → dev-abc123
   • pageSize → 20
4. Click Save. The environment appears in the dropdown at the top of the request pane.

Naming rule: Variable keys must contain only letters, numbers, and underscores. Spaces, hyphens, or special characters (e.g., base-url, api key) prevent placeholder recognition.

Step 2: Reference Variables in a Request

1. Open or create a request in the collection.
2. Set the request URL to {{baseUrl}}/users?limit={{pageSize}}.
3. Add an Authorization header with value Bearer {{apiKey}}.
4. In the request body (JSON), include {\"page\": 1, \"size\": {{pageSize}}}.
5. Select the development environment from the dropdown.

Placeholders can appear anywhere: URL path, query string, header names/values, request body (any content type), and even in pre‑request script logic.

Step 3: Verify Substitution Before Sending

Hoppscotch resolves variables just before the network call. To confirm expansion without sending:

1. Hover over any {{variable}} in the request editor—a tooltip shows the current resolved value.
2. Open the browser DevTools Network tab, send the request, and inspect the outgoing request URL and headers. You should see:
   • Request URL: https://api.dev.example.com/users?limit=20
   • Authorization: Bearer dev-abc123
   • Body: {\"page\": 1, \"size\": 20}

If a variable is undefined (typo or missing from the active environment), Hoppscotch sends the placeholder literally—e.g., {{missingToken}} appears as‑is in the header. This behavior surfaces misconfiguration immediately.

Step 4: Switch Environments at Runtime

1. Create a second environment named staging with:
   • baseUrl → https://api.staging.example.com
   • apiKey → stg-xyz789
   • pageSize → 50
2. Select staging from the environment dropdown.
3. Resend the same request. The Network tab now shows the staging base URL, staging API key, and page size 50—no request changes needed.

Critical timing note: The value used is the one present at the moment you click Send. Changing a variable after the request is in flight does not affect that request.

Step 5: Chain Calls with Pre‑Request Scripts

For workflows where a later request depends on a prior response (e.g., OAuth token refresh), use a pre‑request script to write a variable:

// In the pre‑request script tab of the dependent request
const token = pm.environment.get('authToken');
if (!token || isTokenExpired(token)) {
  // Trigger a token refresh request (pseudo‑code)
  const newToken = await refreshToken();
  pm.environment.set('authToken', newToken);
}

The pm.environment.set() call updates the active environment immediately. Subsequent requests in the same run see the new value. This runs in the Hoppscotch script sandbox (ES2020, limited DOM access).

Expected Checks

Check	How to Verify	Pass Criteria
Variable expands in URL	Network tab → request URL	Full URL matches {{baseUrl}} value + path
Variable expands in header	Network tab → request headers	Header value shows resolved token
Variable expands in body	Network tab → request payload	JSON contains numeric pageSize value
Undefined variable surfaces	Add X-Test: {{undefined}} header, send	Header sent literally as {{undefined}}
Environment switch updates values	Change dropdown, resend, inspect Network	All placeholders reflect new environment

Limitations and Gotchas

• No nested substitution: {{outer_{{inner}}}} does not resolve inner first. Plan flat variable names.
• No default/fallback syntax: Hoppscotch does not support {{var:default}}. Handle missing values in pre‑request scripts.
• Variable scope is workspace‑wide: All collections in the workspace share the same environment set. Use naming prefixes (auth_, db_) to avoid collisions.
• Self‑hosted instances: Environment persistence depends on your storage backend (PostgreSQL, SQLite). Verify backup/restore procedures.
• Script sandbox restrictions: pm.environment.set() only affects the active environment. There is no pm.globals or pm.collectionVariables API as of v2.5.

Practical Verification Checklist

1. Create development and staging environments with identical variable keys, different values.
2. Build one request referencing all three variable positions (URL, header, body).
3. Send against development; confirm Network tab shows dev values.
4. Switch to staging; resend; confirm staging values.
5. Introduce a typo ({{baseUrll}}); send; verify literal placeholder appears.
6. Use a pre‑request script to set a dynamic variable; confirm next request sees it.

If all six checks pass, your collection is environment‑agnostic and ready for CI/CD integration via Hoppscotch CLI or the hoppscotch/collections GitHub Action.