RFC: Updated Scripting System (revised)

Preface

Hoppscotch's scripting system has remained relatively dormant for a long time now. With the increased adoption and requirement for more capabilities, it is long overdue for a revamped scripting system that evolves with the times and takes into account the capabilities important for script implementations these days.

We had a previous proposed RFC defined in #2292. This RFC supersedes the previous one and reconsiders certain decisions described in it. This will serve as a living document of the implementation and will be updated to reflect any changes in decisions.

Authors

• Original Author: @AndrewBastin
• Extended by: @jamesgeorge007

Goals

The goals of the updated scripting APIs are as follows:

• Backwards Compatible: The updated scripting system shouldn't break any existing scripts and SHOULD strive 100% backwards compatibility. Any fundamental changes should have automatic (defined as zero user input) migration pathways.
• Future Proof: The new system should strive towards being easy to add to later on without introducing breaking changes to provide guarantees to people who built stuff on top of the scripting system that this is a solid foundation that they can rely on and won't break.
• Powerful: The new scripting system should provide power to the users to extend and bring in features, and also provide more capabilities to interface with the rest of the Hoppscotch app.
• Safety: All of this should be implemented with a rigorous understanding of possible vulnerabilities and security concerns. Scripting code can be deemed relatively safe and vetted in the implementation details, but efforts should still be taken to ensure we keep the scripting system resilient to sandbox escapes or privilege escalation attacks. Any such possible instances should be well documented and explained.

JavaScript Implementation

The implementation comprises the following set of features:

Deprecation of the pw namespace

We will be deprecating the legacy pw namespace from Hoppscotch with the advent of the new scripting system. We will not be backporting any of the new features to it, and any improvements we will be making won't be available here. There is no specific timeline at which the functionality will be fully removed yet (probably we will keep it for a long time), but we will start showing deprecation warnings when it is used. The pw API will be superseded by the hopp API.

Introduction of the hopp namespace

The hopp namespace is where the new set of scripting APIs and features will be landing. The reason for this shift is so we can break and change certain behaviour that people expect from the pw API. Hence, the shift from the hopp API to pw, although they will look similar, may introduce behaviour changes. Each section of the API will be defined in its section below.

Single script for each request

We propose moving away from the traditional separate pre-request and post-response scripts to a unified script approach. Instead of having two separate script tabs, users will write a single script that defines callbacks for different phases of the request lifecycle.

The script execution model works as follows:

1. The script runs once when the request is initiated
2. Users can define hopp.onBeforeRequest(callback) to specify code that runs before the request is sent
3. Users can define hopp.onResponse(callback) to specify code that runs after the response is received
4. Both callback functions take no parameters - all request/response data is accessed through the hopp namespace objects
5. Variables and state can be shared between the two phases using regular JavaScript variables in the script scope

Example usage:

// Script-level variables are shared between phases
let extractedToken = null;

// Code that runs before request
hopp.onBeforeRequest(() => {
    hopp.request.setHeader('Authorization', 'Bearer ' + hopp.env.get('token'));
    console.log('Request is about to be sent');
});

// Code that runs after response
hopp.onResponse(() => {
    if (hopp.response.statusCode === 200) {
        extractedToken = hopp.response.body.asJSON().access_token;
        hopp.env.set('new_token', extractedToken);
    }

    hopp.test('Response is successful', () => {
        hopp.expect(hopp.response.statusCode).to.equal(200);
    });
});

This approach eliminates the need for a separate shared API since variables can be naturally shared within the same script scope.

TypeScript Language Server and Type Validation

We propose implementing comprehensive TypeScript-based code completion, linting, and type validation to significantly improve the developer experience. While scripts will continue to be written in JavaScript (no TypeScript-specific syntax required), the intelligence and validation will be powered by the TypeScript language service.

Implementation Details

• TypeScript Language Service Integration: We plan to leverage the TypeScript language service infrastructure to provide intelligent code analysis and suggestions in our code editor
• JSDoc Support: Users can enhance type checking by using JSDoc type annotations in their JavaScript code, similar to how TypeScript processes JavaScript files
• Real-time Validation: Syntax errors, type mismatches, and API usage errors will be highlighted in real-time as users type

Type Definitions

We will provide comprehensive TypeScript type definitions for:

• All hopp.* namespace APIs and their methods
• Request/Response object structures
• Environment and request variable APIs
• Cookie object interfaces
• Testing and assertion APIs
• All available global objects and functions (crypto, console, etc.)

Benefits

• Improved Developer Experience: Intelligent autocomplete suggestions with parameter hints and documentation
• Early Error Detection: Catch common mistakes before script execution
• Better Documentation: Inline type hints and method signatures serve as built-in documentation
• IDE-Quality Experience: Professional development experience within the browser
• Reduced Learning Curve: Type hints help users discover available APIs and their correct usage

The type validation will be non-blocking - scripts with type errors can still be executed, but users will receive clear warnings about potential issues.

ESM Module Loading

We propose introducing support for ECMAScript Module (ESM) imports, allowing users to leverage external libraries and modules within their scripts. This significantly expands the capabilities of scripts by enabling access to the vast JavaScript ecosystem.

Remote Module Imports

Users can import modules directly from CDN sources using standard ESM import syntax:

import lodash from 'https://esm.sh/lodash@4.17.21';
import axios from 'https://esm.sh/axios@1.6.0';
import { format } from 'https://esm.sh/date-fns@2.30.0';

hopp.onResponse(() => {
    const data = hopp.response.body.asJSON();
    const processedData = lodash.pick(data, ['id', 'name', 'email']);
    console.log('Formatted date:', format(new Date(), 'yyyy-MM-dd'));
});

Supported CDN Sources

We plan to support importing from popular CDN services that provide ESM-compatible modules:

• esm.sh - Automatically converts npm packages to ESM format with TypeScript support
• Skypack - Optimized ESM packages with browser compatibility
• JSR (JavaScript Registry) - Modern JavaScript package registry with native TypeScript support
• Any CDN serving valid ESM modules

Automatic TypeScript Type Support

Following the Deno-style type import mechanism, we propose implementing automatic TypeScript type definitions when available:

• X-TypeScript-Types Header: CDNs like esm.sh automatically provide TypeScript type definitions via the X-TypeScript-Types HTTP header
• Automatic Type Resolution: When importing a module, if type definitions are available, they will be automatically loaded and used by the TypeScript language service
• Opt-out Mechanism: Users can disable automatic type loading by appending ?no-dts to import URLs if the provided types are incorrect:

import lodash from 'https://esm.sh/lodash@4.17.21?no-dts';

Security and Limitations

• User Responsibility: Users are responsible for verifying the trustworthiness and compatibility of external modules
• Sandbox Compatibility: Modules must be compatible with the browser sandbox environment (no Node.js-specific APIs unless polyfilled)
• No File System Access: Modules requiring file system access or other restricted APIs will not function
• Version Management: Users should be aware of version compatibility and potential breaking changes in external dependencies

Example Usage Patterns

import { v4 as uuidv4 } from 'https://esm.sh/uuid@9.0.0';
import CryptoJS from 'https://esm.sh/crypto-js@4.1.1';
import dayjs from 'https://esm.sh/dayjs@1.11.10';

hopp.onBeforeRequest(() => {
    // Generate unique request ID
    const requestId = uuidv4();
    hopp.request.setHeader('X-Request-ID', requestId);

    // Add timestamp
    hopp.request.setHeader('X-Timestamp', dayjs().toISOString());
});

hopp.onResponse(() => {
    const responseData = hopp.response.body.asJSON();

    // Hash sensitive data for logging
    const hashedEmail = CryptoJS.SHA256(responseData.email).toString();
    console.log('User email hash:', hashedEmail);

    // Store processed timestamp
    hopp.env.set('last_request_time', dayjs().format('YYYY-MM-DD HH:mm:ss'));
});

This ESM support will bring the Hoppscotch scripting environment closer to modern JavaScript development practices while maintaining security and sandbox isolation.

hopp.env namespace

We propose that the hopp.env namespace will replace pw.env and provide a lot more features and fine-grained control around environments in the app.

The main changes around it are as follows:

Ability to specify target environment for operations

The env API will now feature hopp.env.active and hopp.env.global namespaces, which will have operations within them that will allow you to query specifically within the selected and the global environments (eg, hopp.env.active.get("username") will give you the value within the selected environment and ignore the global environment.). The previous way of doing hopp.env.get and so on will still maintain the current behaviour and still look at both global and selected together.

• When it comes to the CLI, hopp.env.global will be empty while hopp.env.active would hold the environment variables.

Ability to delete environment variables

hopp.env.delete operation can be used to delete an environment variable. If multiple declarations are present, the highest precedence version of the variable will be deleted. hopp.env.active and hopp.env.global namespaces also have a version of this function that will target the deletion to specific cases.

Recursive Resolution by default

Environment Variables have an ability to be templates and have parts of it be derived from other environment variables (e.g., I have a variable "x" with the value "hello", I can create a variable "y" with the value "<> world", when Hoppscotch uses the environment variable "y", it will resolve and substitute <<x>> with its value at that point). These are currently available to scripts with pw.env.getResolve and friends. In hopp.env, hopp.env.get by default will do recursive resolution, to opt out of this, we will be introducing hopp.env.getRaw, which will returnthe environment variable value as is.

Manage initial values

Environment variables have initial and current values present with them. The current values will be available to you through the standard operations (pw.env.get / pw.env.set). With the new API, we are introducing a couple of new functions:

• hopp.env.reset(key: string): void - Resets an environment variable back to the initial value (current value will be set to the initial value of the environment variable). This function also has the focused active and global counterparts (hopp.env.active.reset and hopp.env.global.reset)
• hopp.env.getInitialRaw(key: string): string | null - Returns the initial value of an environment variable, returns null if it can't find it. This function also has the focused active and global counterparts (hopp.env.active.getInitialRaw and hopp.env.global.getInitialRaw). Note that there is no hopp.env.getInitial function, as getInitialRaw doesn't resolve recursively and just returns the value as is.
• hopp.env.setInitial(key: string, value: string): void - Updates the initial value of the environment variable of the given key with value. This function also has the focused active and global counterparts (hopp.env.active.setInitial and hopp.env.global.setInitial).

Full API

So the full API under the hopp.env looks as follows:

hopp.env.get(key: string): string | null
hopp.env.getRaw(key: string): string | null
hopp.env.set(key: string, value: string): void
hopp.env.delete(key: string): void
hopp.env.reset(key: string): void
hopp.env.getInitialRaw(key: string): string | null
hopp.env.setInitial(key: string, value: string): void

hopp.env.active.get(key: string): string | null
hopp.env.active.getRaw(key: string): string | null
hopp.env.active.set(key: string, value: string): void
hopp.env.active.delete(key: string): void
hopp.env.active.reset(key: string): void
hopp.env.active.getInitialRaw(key: string): string | null
hopp.env.active.setInitial(key: string, value: string): void

hopp.env.global.get(key: string): string | null
hopp.env.global.getRaw(key: string): string | null
hopp.env.global.set(key: string, value: string): void
hopp.env.global.delete(key: string): void
hopp.env.global.reset(key: string): void
hopp.env.global.getInitialRaw(key: string): string | null
hopp.env.global.setInitial(key: string, value: string): void

Request Variables, although similar to environment variables, are still considered separate. Their access will still be provided through hopp.request.variables API.

• The ability to handle secret environment variables isn’t scoped in as of now, but could be evaluated and considered as the implementation proceeds.

hopp.request namespace

We propose that the hopp.request namespace will provide access to the current request data and allow modification of the request before it is sent. The design follows an immutable property pattern with dedicated mutation functions.

Immutable Properties

All request properties will be read-only and cannot be directly modified:

• hopp.request.url: string - The complete request URL
• hopp.request.method: string - The HTTP method (GET, POST, etc.)
• hopp.request.params: object - Request params as key-value pairs
• hopp.request.headers: object - Request headers as key-value pairs
• hopp.request.body: any - The request body data
• hopp.request.auth: object - Authentication configuration

Mutation Functions

Request modification will be performed through dedicated setter functions. These functions will only be available in the hopp.onBeforeRequest context and will throw an error if called within hopp.onResponse:

• hopp.request.setUrl(url: string): void - Update the request URL
• hopp.request.setMethod(method: string): void - Update the HTTP method
• hopp.request.setHeader(name: string, value: string): void - Set a single header
• hopp.request.setHeaders(headers: object): void - Replace all headers
• hopp.request.removeHeader(name: string): void - Remove a specific header
• hopp.request.setParam(name: string, value: string): void - Set a single param
• hopp.request.setParams(params: object): void - Replace all params
• hopp.request.removeParam(name: string): void - Remove a specific param
• hopp.request.setBody(body: any): void - Update the request body
• hopp.request.setAuth(auth: object): void - Update authentication configuration

Request Variables

Request Variables are a Hoppscotch-specific feature that allows variables scoped to individual requests. These are particularly useful for URL path variables or request-specific templating.

We propose that the API will provide:

• hopp.request.variables.get(key: string): string | null - Get a request variable value
• hopp.request.variables.set(key: string, value: string): void - Set a request variable (only in hopp.onBeforeRequest)

Request variables will follow the same scoping rules as other Hoppscotch variables and will be resolved using the <<variable>> syntax within request configurations.

Example usage

hopp.onBeforeRequest(() => {
    // Modify request before sending
    hopp.request.setHeader('User-Agent', 'Hoppscotch/2.0');
    hopp.request.variables.set('userId', '12345');

    if (hopp.env.get('environment') === 'production') {
        hopp.request.setUrl(hopp.request.url.replace('staging', 'api'));
    }
});

hopp.onResponse(() => {
    // These would throw errors:
    // hopp.request.setHeader('X-Test', 'value'); // Error!
    // hopp.request.variables.set('key', 'value'); // Error!

    // But reading is always allowed:
    console.log('Request was sent to:', hopp.request.url);
});

hopp.response namespace

We propose that the hopp.response namespace will provide read-only access to the response data returned by the server. This namespace will only be available within the hopp.onResponse callback context.

Response Properties

• hopp.response.statusCode: number - The HTTP status code (e.g., 200, 404, 500)
• hopp.response.statusText: string - The HTTP status text (e.g., "OK", "Not Found", "Internal Server Error")
• hopp.response.headers: object - Response headers as key-value pairs
• hopp.response.responseTime: number - Time taken for the request to complete in milliseconds

Response Body Access

We propose that the response body will be accessed through the hopp.response.body object, which will provide multiple ways to parse and access the response data:

• hopp.response.body.asJSON(): any - Parse the response body as JSON. Throws an error if the response is not valid JSON
• hopp.response.body.asText(): string - Get the response body as a plain text string
• hopp.response.body.bytes(): Uint8Array - Get the raw response body as a Uint8Array for binary data handling

Usage Examples

hopp.onResponse(() => {
    console.log(`Response received with status ${hopp.response.statusCode} in ${hopp.response.responseTime}ms`);

    if (hopp.response.statusCode === 200) {
        try {
            const data = hopp.response.body.asJSON();
            console.log('Response data:', data);

            // Extract token for future requests
            if (data.access_token) {
                hopp.env.set('auth_token', data.access_token);
            }
        } catch (error) {
            console.log('Response is not JSON, getting as text:', hopp.response.body.asText());
        }
    }

    // Check response headers
    const contentType = hopp.response.headers['content-type'];
    if (contentType && contentType.includes('application/json')) {
        // Handle JSON response
    }
});

All hopp.response properties and methods will be read-only, and attempting to modify them will result in an error. The response object will only be available during the hopp.onResponse callback execution.

Context Restrictions

We propose that the hopp.response namespace will only be accessible within the hopp.onResponse callback. Outside of this context:

• All properties return null: hopp.response.statusCode, hopp.response.statusText, hopp.response.headers, and hopp.response.responseTime will all return null
• Body methods throw errors: Calling hopp.response.body.asJSON(), hopp.response.body.asText(), or hopp.response.body.bytes() will throw an error with a descriptive message like "Response body is not available outside of onResponse callback"
• No silent failures: The system will actively prevent usage outside the correct context rather than silently returning undefined values

This design ensures that response data is only accessed when it's actually available and prevents common errors from accessing response data at inappropriate times.

// ❌ This will not work
console.log(hopp.response.statusCode); // Returns null
hopp.response.body.asJSON(); // Throws error

hopp.onBeforeRequest(() => {
    // ❌ This will not work inside onBeforeRequest
    console.log(hopp.response.statusCode); // Returns null
    const data = hopp.response.body.asJSON(); // Throws error
});

hopp.onResponse(() => {
    // ✅ This works correctly
    console.log(hopp.response.statusCode); // Returns actual status code
    const data = hopp.response.body.asJSON(); // Returns parsed JSON
});

hopp.cookies namespace

We propose that the hopp.cookies namespace will provide comprehensive cookie management capabilities for handling HTTP cookies associated with different domains. Unlike Postman's callback-based approach, all cookie operations in Hoppscotch will be synchronous.

Cookie Object Structure

We propose that cookies in Hoppscotch will be 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 (not accessible via JavaScript)
    secure: boolean;        // Whether cookie should only be sent over HTTPS
    sameSite: 'None' | 'Lax' | 'Strict'; // SameSite attribute for CSRF protection
}

Cookie Management API

All cookie operations will require specifying the domain as the first parameter:

• hopp.cookies.get(domain: string, cookieName: string): Cookie | null - Get a specific cookie object, returns null if not found
• hopp.cookies.set(domain: string, cookie: Cookie): void - Set a cookie (create or update)
• hopp.cookies.has(domain: string, cookieName: string): boolean - Check if a cookie exists for the given domain
• hopp.cookies.getAll(domain: string): Cookie[] - Get all cookies for a specific domain
• hopp.cookies.delete(domain: string, cookieName: string): void - Delete a specific cookie
• hopp.cookies.clear(domain: string): void - Delete all cookies for a specific domain

Usage Examples

hopp.onBeforeRequest(() => {
    // Set an 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',
        maxAge: 3600 // 1 hour
    });

    // Check if a cookie exists
    if (hopp.cookies.has('api.example.com', 'auth_token')) {
        console.log('Authentication cookie is present');
    }
});

hopp.onResponse(() => {
    // Extract cookies from response for future use
    const allCookies = hopp.cookies.getAll('api.example.com');
    console.log(`Domain has ${allCookies.length} cookies`);

    // Get a specific cookie value
    const sessionCookie = hopp.cookies.get('api.example.com', 'session_id');
    if (sessionCookie) {
        console.log('Session cookie expires:', sessionCookie.expires);
        // Store in environment for future requests
        hopp.env.set('session_id', sessionCookie.value);
    }

    // Clean up expired or unwanted cookies
    hopp.cookies.delete('api.example.com', 'temp_token');
});

Cookie mutation operations (set, delete, clear) will be available in both hopp.onBeforeRequest and hopp.onResponse contexts, allowing for cookie management throughout the request lifecycle.

In the initial iteration, we’re thinking of keeping the hopp.cookie namespace support exclusive to the Desktop App.

Testing API

We propose implementing a robust testing framework for writing assertions and test cases within scripts. The API will be designed to be familiar to users coming from other testing frameworks while providing deep integration with Hoppscotch's request/response data.

Test Structure

Tests will be organized using the hopp.test() function, which will group related assertions under a descriptive name:

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

Assertion Library

We propose that the hopp.expect() function will be powered by the Chai assertion library, providing access to all of Chai's built-in assertions and matchers:

hopp.expect(actual: any): ChaiExpectation

This will give users access to the full range of Chai's BDD assertion style, including:

• Equality assertions: .equal(), .eql(), .deep.equal()
• Type checking: .be.a(), .be.an()
• Property assertions: .have.property(), .have.own.property()
• Length assertions: .have.length(), .have.lengthOf()
• Inclusion assertions: .include(), .contain()
• Comparison assertions: .be.above(), .be.below(), .be.within()
• Boolean assertions: .be.true, .be.false, .be.ok
• Negation: .not modifier
• And many more

Hoppscotch Custom Assertions

In addition to the full Chai assertion library, we propose providing several custom assertion methods specifically designed for API testing:

Basic Custom Assertions

• hopp.expect(value).toBe(expected) - Exact equality using strict comparison (===), recommended for primitive types
• hopp.expect(value).toBeType(type) - Type checking where type is one of: "string", "number", "boolean", "object", "undefined", "bigint", "symbol", "function"
• hopp.expect(value).toHaveLength(number) - Check that an object has a .length property set to a specific numeric value
• hopp.expect(value).toInclude(item) - Check that a string or array contains a specific value

HTTP Status Code Level Assertions

We propose providing convenient matchers for HTTP status code ranges:

• hopp.expect(statusCode).toBeLevel2xx() - Status code between 200-299 (success)
• hopp.expect(statusCode).toBeLevel3xx() - Status code between 300-399 (redirection)
• hopp.expect(statusCode).toBeLevel4xx() - Status code between 400-499 (client error)
• hopp.expect(statusCode).toBeLevel5xx() - Status code between 500-599 (server error)

Negation Support

All custom assertions will support negation using the .not modifier:

hopp.expect(value).not.toBe(unexpected)
hopp.expect(value).not.toBeType("string")
hopp.expect(response.statusCode).not.toBeLevel4xx()

Common Testing Patterns

hopp.onResponse(() => {
    // Status code testing with custom assertions
    hopp.test('Response status is successful', () => {
        hopp.expect(hopp.response.statusCode).toBe(200);
        // Or using level assertions
        hopp.expect(hopp.response.statusCode).toBeLevel2xx();
    });

    // JSON response testing with custom type checking
    hopp.test('Response contains expected data', () => {
        const data = hopp.response.body.asJSON();
        hopp.expect(data).to.be.an('object');
        hopp.expect(data).to.have.property('id');
        hopp.expect(data.name).toBeType('string');
        hopp.expect(data.age).toBeType('number');
        hopp.expect(data.age).to.be.above(0);
    });

    // Header testing
    hopp.test('Response has correct headers', () => {
        hopp.expect(hopp.response.headers).to.have.property('content-type');
        hopp.expect(hopp.response.headers['content-type']).toInclude('application/json');
    });

    // Response time testing
    hopp.test('Response time is acceptable', () => {
        hopp.expect(hopp.response.responseTime).to.be.below(1000);
    });

    // Array and length testing with custom assertions
    hopp.test('Response array has expected structure', () => {
        const items = hopp.response.body.asJSON().items;
        hopp.expect(items).toBeType('object'); // Array is type 'object' in JavaScript
        hopp.expect(items).toHaveLength(10);
        hopp.expect(items).not.toHaveLength(0);
    });

    // String inclusion testing
    hopp.test('Response message contains expected text', () => {
        const message = hopp.response.body.asJSON().message;
        hopp.expect(message).toInclude('success');
        hopp.expect(message).not.toInclude('error');
    });

    // Error status code testing
    hopp.test('Error responses are handled correctly', () => {
        if (hopp.response.statusCode >= 400) {
            hopp.expect(hopp.response.statusCode).toBeLevel4xx(); // Client error
            const errorData = hopp.response.body.asJSON();
            hopp.expect(errorData).to.have.property('error');
            hopp.expect(errorData.error).toBeType('string');
        }
    });

    // Complex object assertions
    hopp.test('User object has expected structure', () => {
        const user = hopp.response.body.asJSON().user;
        hopp.expect(user).to.deep.include({
            role: 'admin',
            active: true
        });
        hopp.expect(user.permissions).to.be.an('array').that.includes('read');
    });

    // Multiple related assertions
    hopp.test('API pagination works correctly', () => {
        const data = hopp.response.body.asJSON();
        hopp.expect(data.page).toBe(1);
        hopp.expect(data.total).toBeType('number');
        hopp.expect(data.total).to.be.above(0);
        hopp.expect(data.items).to.be.an('array');
        hopp.expect(data.items).to.have.length.within(1, 50);
    });
});

Test Execution and Reporting

• Tests will execute in the order they are defined within the script
• Each test will be isolated - failures in one test will not affect others
• Test results will be displayed in Hoppscotch's test results panel
• Failed assertions will show detailed error messages indicating expected vs actual values
• Test statistics (passed/failed counts) will be tracked and displayed

Error Handling

If an assertion fails, the test framework will:

• Mark the specific test as failed
• Continue executing remaining tests
• Provide detailed error messages with expected and actual values
• Show the assertion chain that failed for debugging

The testing API will only be meaningful within the hopp.onResponse context, as it typically validates response data, though environment and request data can also be tested.

Postman Compatibility Layer

To ease migration from Postman and support existing workflows, we propose providing a comprehensive pm API compatibility layer. This layer will implement Postman's scripting API as best-faith wrappers on top of the native hopp API implementations.

Implementation Strategy

We propose that the pm API will follow a dual approach for compatibility:

Supported Features: All commonly used Postman APIs will be implemented as wrappers around the corresponding hopp APIs, maintaining the same interface and behaviour patterns that Postman users expect.

Unsupported Features: Features that don't exist in Hoppscotch (such as collection runner-specific features, Postman Vault, etc.) will be present with proper TypeScript type definitions but will throw a descriptive error when called: "Not supported by Hoppscotch".

HTTP Requests with hopp.fetch

We propose that the foundation for HTTP requests in the new system will be hopp.fetch, which will implement the standard Fetch API while routing requests through Hoppscotch's interceptor system.

hopp.fetch(url: string | Request, options?: RequestInit): Promise<Response>

Key Features:

• Standard Fetch API: Compatible with browser fetch() specification
• Interceptor Integration: Routes through Hoppscotch's interceptor system to handle CORS, proxy settings, and authentication
• Global Availability: A global fetch function will also be available and work identically to hopp.fetch

hopp.onResponse(() => {
  // Using hopp.fetch
  const response = await hopp.fetch('https://api.example.com/data', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ key: 'value' })
  });

  const data = await response.json();
  console.log('External API response:', data);
});

Postman API Mappings

We propose that the pm API will provide familiar Postman interfaces mapped to Hoppscotch functionality:

Environment and Variable Management

// pm.environment → hopp.env.active
pm.environment.get(key) // → hopp.env.active.get(key)
pm.environment.set(key, value) // → hopp.env.active.set(key, value)
pm.environment.unset(key) // → hopp.env.active.delete(key)

// pm.globals → hopp.env.global
pm.globals.get(key) // → hopp.env.global.get(key)
pm.globals.set(key, value) // → hopp.env.global.set(key, value)
pm.globals.unset(key) // → hopp.env.global.delete(key)

// pm.variables → combined scope with precedence
pm.variables.get(key) // → hopp.env.get(key) (follows precedence rules)
pm.variables.set(key, value) // → creates local variable for current script execution

Request and Response Objects

// pm.request → hopp.request (with Postman-style properties)
pm.request.url // → hopp.request.url
pm.request.method // → hopp.request.method
pm.request.headers // → hopp.request.headers

// pm.response → hopp.response (with Postman-style properties)
pm.response.code // → hopp.response.statusCode
pm.response.status // → hopp.response.statusText
pm.response.json() // → hopp.response.body.asJSON()
pm.response.text() // → hopp.response.body.asText()

Testing API

// pm.test → hopp.test (only available in hopp.onResponse context)
pm.test('Status is 200', () => {
  pm.expect(pm.response.code).to.equal(200);
});

// pm.expect → hopp.expect (with full Chai + Hoppscotch custom assertions)
pm.expect(value).to.equal(expected);
pm.expect(pm.response.code).to.be.oneOf([200, 201, 202]);

Script Context Information

// pm.info provides context about script execution
pm.info.eventName // Returns "pre-request" or "post-request" based on current context
pm.info.requestName // → Name of current request
pm.info.requestId // → Unique identifier for current request

HTTP Requests (pm.sendRequest)

// pm.sendRequest → wrapper around hopp.fetch with callback-style API
pm.sendRequest('https://api.example.com/data', (error, response) => {
  if (error) {
    console.error('Request failed:', error);
    return;
  }
  console.log('Status:', response.code);
  console.log('Body:', response.json());
});

// With full request object
const requestObject = {
  url: 'https://api.example.com/users',
  method: 'POST',
  header: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer ' + pm.environment.get('token')
  },
  body: {
    mode: 'raw',
    raw: JSON.stringify({ name: 'John Doe' })
  }
};

pm.sendRequest(requestObject, (error, response) => {
  if (!error) {
    pm.environment.set('userId', response.json().id);
  }
});

Unsupported Features

We propose that the following Postman features will be present in the API with proper TypeScript types but will throw "Not supported by Hoppscotch" errors when called:

// Collection Runner features
pm.info.iteration // Throws error
pm.info.iterationCount // Throws error
pm.iterationData.get() // Throws error

// Postman Vault
pm.vault.get() // Throws error
pm.vault.set() // Throws error

// Collection Variables (use request variables or environment variables instead - to be enabled when the support is brought)
pm.collectionVariables.get() // Throws error
pm.collectionVariables.set() // Throws error

// Advanced Collection Features
pm.execution.setNextRequest() // Throws error

Migration Example

// Traditional Postman script
pm.test("Response is successful", () => {
  pm.expect(pm.response.code).to.be.oneOf([200, 201]);
  const jsonData = pm.response.json();
  pm.expect(jsonData).to.have.property('id');

  // Store data for next request
  pm.environment.set('userId', jsonData.id);
});

// Send follow-up request
pm.sendRequest(`https://api.example.com/users/${pm.environment.get('userId')}/profile`,
  (error, response) => {
    if (!error) {
      pm.test("Profile fetch successful", () => {
        pm.expect(response.code).to.equal(200);
      });
    }
  }
);

This script will work unchanged in Hoppscotch within the hopp.onResponse() context, providing seamless migration from Postman while users can gradually adopt the more powerful hopp APIs when needed.

TypeScript Support

We propose providing full TypeScript type definitions for all pm APIs, including:

• Complete interface definitions matching Postman's API surface
• Proper error types for unsupported features
• Integration with Hoppscotch's TypeScript language service
• Intellisense and autocomplete support for seamless migration

This compatibility layer will ensure that existing Postman users can migrate their scripts with minimal changes while providing a pathway to adopt Hoppscotch's enhanced scripting capabilities over time.

Planned Future Extensions

This RFC defines the core updated scripting system. However, we acknowledge that future iterations may expand scripting support and variable scoping to include:

• Collection-level Variables: The ability to define variables that apply to entire request collections via a proposedhopp.collection.variables API co-existing alongside hopp.env.global and hopp.env.active with clear precedence rules.
• Collection-level Scripting: The ability to run pre-request or post-response scripts at the collection level, with full lifecycle integration.
• Advanced Cookie Management: Potential for deeper integration to support cookie persistence and domain scoping across CLI and web contexts.

Status: These features are not covered in this RFC version but are acknowledged design goals. They may be proposed in separate RFCs or revisions to this document.

Final Notes

This implementation will be a gradual process that unfolds over the next few months, and some of the improvements outlined above may be postponed or omitted altogether if we face technical challenges or other constraints along the way.

As mentioned earlier, we're keen to foster an open conversation around enhancing the scripting experience. If you have any suggestions or pain points we haven’t covered, please feel free to share your thoughts in the discussion below.