Scripts

Hoppscotch provides ECMAScript APIs that can be used in writing pre-request scripts and building tests. You can enter your ECMAScript code and run the necessary scripts.

​

The pw object

The pw object provides access to request and response data and variables in your Hoppscotch instance.

The pw object houses the following methods:

​

pw.env.set("variable", "value")

pw.env.set() can be used directly for quick and convenient environment variable definition.

pw.env.set("baseURL", "https://httpbin.org");

​

pw.env.unset("variable)

pw.env.unset() can be used to remove the value of the variable present in the current active environment

pw.env.unset("baseURL");

​

pw.env.get("variable")

Retrieves the value of the selected environment’s variable. Accepts an environment variable as an argument.

pw.env.get("variable");
pw.env.get("baseURL");

​

pw.env.getResolve("variable")

Retrieves the value of the selected environment’s variable recursively. Accepts an environment variable as an argument.

pw.env.getResolve("variable");
pw.env.getResolve("baseURL");

​

pw.env.resolve("variable")

Retrieves the value of the selected environment’s variable recursively. Accepts an environment variable string as an argument.

pw.env.resolve("<<variable_1>><<variable_2>>");
pw.env.resolve("<<baseURL>><<basePath>>");

​

pw.expect(value)

The expect method returns an expectation object, on which you can call matcher functions.

The example below calls the matcher function toBe on the expectation object that is returned by calling pw.expect with the response id, pw.response.body.id as an argument.

Use pw.expect directly for quick and convenient testing. Every pw.expect statement will generate a line on the test report.

// This test will pass
pw.expect(1).toBe(1);

// This test will fail
pw.expect(2).not.toBe(2);

​

pw.test(name, function)

To create a group of tests, with the name as a string and fn as a callback function to write tests associated with the group. The test results will include the given name for better organization.

Let’s wrap expect statements with pw.test to the group and describe related statements.

// This will return 4 lines on the test report, grouped under "Arithmetic operations"
pw.test("Arithmetic operations", () => {
  const size = 500 + 500;
  pw.expect(size).toBe(1000);
  pw.expect(size - 500).toBe(500);
  pw.expect(size * 4).toBe(4000);
  pw.expect(size / 4).toBe(250);
});

If neither a pw.expect nor a pw.test statement is present, no test reports will be generated.

// This will not generate any test reports
(99 + 1).toBe(100);

​

pw.toBe(value)

Test for exact equality using toBe.

pw.expect(pw.response.body.category).toBe("Sneakers");

toBe uses strict equality and is recommended for primitive data types.

// These tests will fail
pw.expect("hello").toBe("Hello");
pw.expect(5).toBe("5");
pw.expect([]).toBe([]);

​

pw.not()

Test for negation by adding .not before calling the matcher function.

// These tests will pass
pw.expect(true).not.toBe(false);
pw.expect(200).not.toBeLevel3xx();

​

pw.toBeLevelxxx()

There are four different matcher functions for quick and convenient testing of the http status code that is returned:

• toBeLevel2xx()
• toBeLevel3xx()
• toBeLevel4xx()
• toBeLevel5xx()

For example, an argument passed to expect must be within 200 and 299 inclusive to pass toBeLevel2xx().

// These tests will pass
pw.expect(204).toBeLevel2xx();
pw.expect(308).toBeLevel3xx();
pw.expect(404).toBeLevel4xx();
pw.expect(503).toBeLevel5xx();

If the argument passed to expect() is a non-numeric value, it is first parsed with parseInt().

// This test will pass
pw.expect("404").toBeLevel4xx();

​

pw.toBeType(type)

Use .toBeType(type) for type checking. The argument for this method should be either of the following string, boolean, number, object, undefined, bigint, symbol, or function.

// These tests will pass
pw.expect(5).toBeType("number");
pw.expect("Hello, world!").toBeType("string");

pw.expect(5).not.toBeType("string");
pw.expect("Hello, world!").not.toBeType("number");

​

pw.toHaveLength(number)

Use .toHaveLength(number) to check that an object has a .length property and it is set to a certain numeric value.

// These expectations will pass
pw.expect("hoppscotch").toHaveLength(10);
pw.expect("hoppscotch").not.toHaveLength(9);

pw.expect(["apple", "banana", "coconut"]).toHaveLength(3);
pw.expect(["apple", "banana", "coconut"]).not.toHaveLength(4);

​

pw.toInclude(value)

Use .toInclude(value) to check that a string/array has a value entry.

// These expectations will pass
pw.expect("hoppscotch").toInclude("hopp");
pw.expect("hoppscotch").not.toInclude("scotch");

pw.expect(["apple", "banana", "coconut"]).toInclude("banana");
pw.expect(["apple", "banana", "coconut"]).not.toInclude("grape");

​

pw.response

Assert response data by accessing the pw.response object.

// This test will pass
pw.test("Response is ok", () => {
  pw.expect(pw.response.status).toBe(200);
});

Currently supports the following response values:

• status: -number- The status code as an integer.
• headers: -object- The response headers.
• body: -object- the data in the response. In many requests, this is the JSON sent by the server.

​

Setting Environment Variables from API Responses

By following these steps, you can store data from one API response and access it later using Environment Variables, making it available for use in subsequent API calls.

Assume in this example that the payload returns access_token and id_token as part of a JSON response.

1. Create Environment Variables without setting their values initially. For example:

   • idToken
   • accessToken

2. In the “Tests” tab of the first API request (that returns the tokens), add the following code:

const jsonData = pw.response.body; // Save the JSON payload response

pw.env.set("accessToken", jsonData.access_token); // Set "accessToken" to the value of "access_token" in the response

pw.env.set("idToken", jsonData.id_token); // Set "idToken" to the value of "id_token" in the response

3. Use these Environment Variables in subsequent API calls within the same collection using the <<variableName>> syntax as usual.