Skip to main content
  • hopp [Experimental]
  • pw [Legacy]
It is not recommended to migrate or reformat your existing scripts to the new scripting APIs at this time. Upcoming updates are expected to introduce breaking changes as we continue to refine and improve the scripting experience.The current rollout is intentionally gradual, allowing us to gather user feedback and iterate based on real-world usage.All further updates to scripting will be scoped to the experimental scripting sandbox, which is the default, and the preference can be updated from Settings → Experiments.Your feedback will be invaluable as we shape the next generation of Hoppscotch scripting.
This new experimental implementation provides a robust foundation for API scripting with enhanced capabilities for environment management, request manipulation, response processing, cookie handling, and comprehensive testing. The new system maintains backwards compatibility while introducing powerful new features for modern API testing workflows.

​
hopp.env Namespace

Environment variable management with scope-specific operations and enhanced functionality.

​
hopp.env.get(key: string)

Retrieves the value of the selected environment’s variable. Accepts an environment variable as an argument.
hopp.env.get("variable");
hopp.env.get("baseURL");

​
hopp.env.getRaw(key: string)

Retrieves the raw value of the selected environment’s variable without variable resolution.
hopp.env.getRaw("variable");

​
hopp.env.set(key: string, value: string)

Sets the value of an environment variable in the selected environment.
hopp.env.set("baseURL", "https://httpbin.org");

​
hopp.env.delete(key: string)

Deletes an environment variable from the selected environment.
hopp.env.delete("baseURL");

​
hopp.env.reset(key: string)

Resets an environment variable to its initial value in the selected environment.
hopp.env.reset("baseURL");

​
hopp.env.getInitialRaw(key: string)

Retrieves the initial raw value of an environment variable.
hopp.env.getInitialRaw("baseURL");

​
hopp.env.setInitial(key: string, value: string)

Sets the initial value of an environment variable.
hopp.env.setInitial("baseURL", "https://httpbin.org");

​
Active Environment Scope

Operations specific to the currently active environment.

​
hopp.env.active.get(key: string)

Retrieves the value of the active environment’s variable.
hopp.env.active.get("variable");

​
hopp.env.active.getRaw(key: string)

Retrieves the raw value of the active environment’s variable.
hopp.env.active.getRaw("variable");

​
hopp.env.active.set(key: string, value: string)

Sets the value of an active environment variable.
hopp.env.active.set("baseURL", "https://httpbin.org");

​
hopp.env.active.delete(key: string)

Deletes a variable from the active environment.
hopp.env.active.delete("baseURL");

​
hopp.env.active.reset(key: string)

Resets a variable in the active environment to its initial value.
hopp.env.active.reset("baseURL");

​
hopp.env.active.getInitialRaw(key: string)

Retrieves the initial raw value of an active environment variable.
hopp.env.active.getInitialRaw("baseURL");

​
hopp.env.active.setInitial(key: string, value: string)

Sets the initial value of an active environment variable.
hopp.env.active.setInitial("baseURL", "https://httpbin.org");

​
Global Environment Scope

Operations specific to the global environment.

​
hopp.env.global.get(key: string)

Retrieves the value of the global environment’s variable.
hopp.env.global.get("variable");

​
hopp.env.global.getRaw(key: string)

Retrieves the raw value of the global environment’s variable.
hopp.env.global.getRaw("variable");

​
hopp.env.global.set(key: string, value: string)

Sets the value of a global environment variable.
hopp.env.global.set("baseURL", "https://httpbin.org");

​
hopp.env.global.delete(key: string)

Deletes a variable from the global environment.
hopp.env.global.delete("baseURL");

​
hopp.env.global.reset(key: string)

Resets a variable in the global environment to its initial value.
hopp.env.global.reset("baseURL");

​
hopp.env.global.getInitialRaw(key: string)

Retrieves the initial raw value of a global environment variable.
hopp.env.global.getInitialRaw("baseURL");

​
hopp.env.global.setInitial(key: string, value: string)

Sets the initial value of a global environment variable.
hopp.env.global.setInitial("baseURL", "https://httpbin.org");

​
The hopp.request Namespace

Request manipulation with immutable properties and dedicated mutation functions.

​
Read-only Properties

​
hopp.request.url

The request URL as a string.
const url = hopp.request.url;

​
hopp.request.method

The HTTP method of the request.
const method = hopp.request.method;

​
hopp.request.params

The query parameters of the request.
const params = hopp.request.params;

​
hopp.request.headers

The headers of the request.
const headers = hopp.request.headers;

​
hopp.request.body

The body of the request.
const body = hopp.request.body;

​
hopp.request.auth

The authentication configuration of the request.
const auth = hopp.request.auth;

​
Mutation Functions (Pre-request Phase Only)

​
hopp.request.setUrl(url: string)

Sets the request URL.
hopp.request.setUrl("https://api.example.com/users");

​
hopp.request.setMethod(method: string)

Sets the HTTP method of the request.
hopp.request.setMethod("POST");

​
hopp.request.setHeader(name: string, value: string)

Sets a header on the request.
hopp.request.setHeader("Authorization", "Bearer token");

​
hopp.request.setHeaders(headers: HoppRESTHeader[])

Sets multiple headers on the request.
hopp.request.setHeaders([{ key: "Content-Type", value: "application/json" }]);

​
hopp.request.removeHeader(name: string)

Removes a header from the request.
hopp.request.removeHeader("Authorization");

​
hopp.request.setParam(name: string, value: string)

Sets a query parameter on the request.
hopp.request.setParam("userId", "123");

​
hopp.request.setParams(params: HoppRESTParam[])

Sets multiple query parameters on the request.
hopp.request.setParams([{ key: "userId", value: "123" }]);

​
hopp.request.removeParam(name: string)

Removes a query parameter from the request.
hopp.request.removeParam("userId");

​
hopp.request.setBody(body: Partial<HoppRESTReqBody>)

Sets the body of the request.
hopp.request.setBody({ content: '{"key": "value"}' });

​
hopp.request.setAuth(auth: Partial<HoppRESTAuth>)

Sets the authentication for the request.
hopp.request.setAuth({ authType: "bearer", token: "token" });

​
Request Variables

​
hopp.request.variables.get(key: string)

Retrieves the value of a request variable.
const value = hopp.request.variables.get("varName");

​
hopp.request.variables.set(key: string, value: string)

Sets the value of a request variable.
hopp.request.variables.set("varName", "value");
Please note that only updates to request variables get persisted and reflected in the UI while the remaining are specific to the session.

​
The hopp.response Namespace

Response access with multiple data formats and comprehensive metadata.

​
Response Metadata

​
hopp.response.statusCode

The HTTP status code of the response.
const status = hopp.response.statusCode;

​
hopp.response.statusText

The status text of the response.
const statusText = hopp.response.statusText;

​
hopp.response.headers

The headers of the response.
const headers = hopp.response.headers;

​
hopp.response.responseTime

The response time in milliseconds.
const time = hopp.response.responseTime;

​
Response Body Access Methods

​
hopp.response.body.asJSON()

Parses the response body as JSON.
const data = hopp.response.body.asJSON();

​
hopp.response.body.asText()

Returns the response body as text.
const text = hopp.response.body.asText();

​
hopp.response.body.bytes()

Returns the response body as a Uint8Array.
const bytes = hopp.response.body.bytes();

​
The hopp.cookies Namespace

Domain-aware cookie management with comprehensive CRUD operations.

​
hopp.cookies.get(domain: string, cookieName: string)

Retrieves a cookie by domain and name.
const cookie = hopp.cookies.get("example.com", "sessionId");
Sets a cookie for a domain.
hopp.cookies.set("example.com", { name: "sessionId", value: "abc123", domain: "example.com" });

​
hopp.cookies.has(domain: string, cookieName: string)

Checks if a cookie exists for a domain.
const exists = hopp.cookies.has("example.com", "sessionId");

​
hopp.cookies.getAll(domain: string)

Retrieves all cookies for a domain.
const cookies = hopp.cookies.getAll("example.com");

​
hopp.cookies.delete(domain: string, cookieName: string)

Deletes a cookie for a domain.
hopp.cookies.delete("example.com", "sessionId");

​
hopp.cookies.clear(domain: string)

Clears all cookies for a domain.
hopp.cookies.clear("example.com");

​
The hopp.test and hopp.expect Testing Framework

Comprehensive testing API with custom assertions for API testing.

​
hopp.test(testName: string, testFunction: () => void)

Creates a group of tests with a name.
hopp.test("API Tests", () => {
  hopp.expect(1).toBe(1);
});

​
hopp.expect(actual: any)

Returns an expectation object for assertions.
hopp.expect(value).toBe(expected);

​
Basic Custom Assertions

​
hopp.expect(value).toBe(expected: any)

Tests for exact equality.
hopp.expect(1).toBe(1);

​
hopp.expect(value).toBeType(type: string)

Tests for type equality.
hopp.expect("hello").toBeType("string");

​
hopp.expect(value).toHaveLength(number: number)

Tests that a value has a specific length.
hopp.expect([1,2,3]).toHaveLength(3);

​
hopp.expect(value).toInclude(item: any)

Tests that a value includes an item.
hopp.expect([1,2,3]).toInclude(2);

​
HTTP Status Code Level Assertions

​
hopp.expect(statusCode).toBeLevel2xx()

Tests that the status code is in the 2xx range.
hopp.expect(200).toBeLevel2xx();

​
hopp.expect(statusCode).toBeLevel3xx()

Tests that the status code is in the 3xx range.
hopp.expect(302).toBeLevel3xx();

​
hopp.expect(statusCode).toBeLevel4xx()

Tests that the status code is in the 4xx range.
hopp.expect(404).toBeLevel4xx();

​
hopp.expect(statusCode).toBeLevel5xx()

Tests that the status code is in the 5xx range.
hopp.expect(500).toBeLevel5xx();

​
Negation Support

All assertions support .not for negation.
hopp.expect(1).not.toBe(2);
hopp.expect("hello").not.toBeType("number");
hopp.expect([1,2]).not.toHaveLength(3);
hopp.expect([1,2]).not.toInclude(3);
hopp.expect(200).not.toBeLevel4xx();

​
The pm Namespace - Postman Compatibility Layer

Postman API compatibility for seamless migration (foundational and expanding):
// Environment and variable management
pm.environment.get(key: string): string | null
pm.environment.set(key: string, value: string): void
pm.environment.unset(key: string): void
pm.environment.has(key: string): boolean

pm.globals.get(key: string): string | null
pm.globals.set(key: string, value: string): void
pm.globals.unset(key: string): void
pm.globals.has(key: string): boolean

pm.variables.get(key: string): string | null
pm.variables.set(key: string, value: string): void
pm.variables.has(key: string): boolean
pm.variables.replaceIn(template: string): string

// Request access (read-only)
pm.request.url: URL-like (toString available; additional properties may be limited initially)
pm.request.method: string
pm.request.headers: HoppRESTHeader[]
pm.request.body: HoppRESTReqBody
pm.request.auth: HoppRESTAuth

// Response access (post-request only)
pm.response.code: number
pm.response.status: string
pm.response.responseTime: number  // ms
pm.response.json(): Record<string, any>
pm.response.text(): string
pm.response.headers.get(name: string): string | null
pm.response.headers.has(name: string): boolean
pm.response.headers.all(): HoppRESTResponseHeader[]
pm.response.stream: Uint8Array  // Raw response bytes

// Testing integration
pm.test(testName: string, testFunction: () => void): void
pm.expect(actual: any): Expectation

// Script context information
pm.info.eventName: string  // "pre-request" or "post-request"
pm.info.requestName: string
pm.info.requestId: string

​
The pw Namespace - Legacy Compatibility

Maintained for backwards compatibility with existing scripts:
// Legacy environment operations
pw.env.get(key: string): string | null
pw.env.getResolve(key: string): string | null
pw.env.set(key: string, value: string): void
pw.env.unset(key: string): void
pw.env.resolve(template: string): string

// Legacy response access
pw.response.status: number
pw.response.body: any
pw.response.headers: HoppRESTResponseHeader[]

// Legacy testing framework
pw.test(testName: string, testFunction: () => void): void
pw.expect(actual: any): Expectation
Cookies are represented as objects with the following properties:
type Cookie = {
  name: string           // Cookie name
  value: string          // Cookie value
  domain: string         // Domain the cookie belongs to
  path: string           // Path scope of the cookie (default: "/")
  expires?: string       // Expiration date in ISO format, null for session cookies
  maxAge?: number        // Maximum age in seconds, null if not set
  httpOnly: boolean      // Whether cookie is HTTP-only
  secure: boolean        // Whether cookie should only be sent over HTTPS
  sameSite: 'None' | 'Lax' | 'Strict'  // SameSite attribute
}

​
Usage Examples

​
Environment Management

// Set and get environment variables
hopp.env.set("api_token", "abc123")
const token = hopp.env.get("api_token")

// Scope-specific operations
hopp.env.global.set("base_url", "https://api.example.com")
hopp.env.active.set("user_id", "12345")

// Reset to initial values
hopp.env.reset("api_token")

​
Request Manipulation

// Modify request before sending
hopp.request.setHeader("Authorization", "Bearer " + hopp.env.get("token"))
hopp.request.setUrl("https://api.example.com/users/" + hopp.env.get("user_id"))
hopp.request.setMethod("POST")

​
Response Testing

hopp.test("API responds successfully", () => {
  hopp.expect(hopp.response.statusCode).toBeLevel2xx()
  hopp.expect(hopp.response.responseTime).toBe(1000)

  const data = hopp.response.body.asJSON()
  hopp.expect(data).toBeType("object")
  hopp.expect(data.users).toHaveLength(10)
})

// Set authentication cookie
hopp.cookies.set("api.example.com", {
  name: "session_id",
  value: "abc123",
  domain: "api.example.com",
  path: "/api",
  httpOnly: true,
  secure: true,
  sameSite: "Lax",
})

// Check if cookie exists
if (hopp.cookies.has("api.example.com", "session_id")) {
  const cookie = hopp.cookies.get("api.example.com", "session_id")
  hopp.env.set("session_token", cookie.value)
}

Scripts

Read about pre-request scripts.

Tests

Read about post-request tests.

Environments

Read about environments.
⌘I