Scripts

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

The pw object

The pw,* object provides access to request and response data and variables in the 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 variables definition

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

pw.env.get("variable")

Retrieves the value of the selected environment's variable. Accepts a 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 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 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 an 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.