Writing Tests

Automated API testing ensures endpoints function as expected. Requestly allows you to write tests using JavaScript with the rq object enabling validations, schema checks, and automated workflows. Common testing approaches include:

Contract Testing: Validate responses against JSON schemas.
Unit Testing: Test individual endpoints in isolation.
Error Handling: Verify API behavior for invalid inputs.

You can execute tests using either Pre-request scripts (run before a request is sent) or Post-response scripts (run after a response is received).

The Pre-request and Post-response tabs provide a scripting environment that allows dynamic behavior for API requests.

The Scripts → Pre-request tab enables processing before sending a request, such as setting variable values or modifying headers.
The Scripts → Post-response tab runs after receiving the response and allows for test assertions, logging, and response validation. This tab includes the Chai.js library, supporting behavior-driven development (BDD) syntax for test assertions.

Scripting Environment

Requestly provides a JavaScript runtime with built-in utilities. Here’s a quick reference table for key methods:

Method/Interface	Description
`rq.test`	Define a test with a name and callback for assertions.
`rq.expect`	Use Chai.js BDD style assertions to compare values.
`rq.environment`	Access and manage environment variables.
`rq.globals`	Access and manage global variables.
`rq.response`	Access response details (status, body, headers, etc.).
`rq.request`	Access request details (method, headers, body, URL, etc.).

To create a test, use the following syntax:

Requestly tests use Chai.js for assertions. For more details and examples, visit the official Chai.js documentation.

rq.test("Test name", () => {
  rq.expect(actualValue).to.equal(expectedValue);
  });

Example Tests

Status Code Check

rq.test("Status is 200", () => {
  rq.response.to.have.status(200);
});

JSON Body Validation

rq.test("User exists", () => {
  rq.response.to.have.jsonBody("user.name", "John");
});

Header Check

rq.test("Has auth header", () => {
  rq.response.to.have.header("Authorization");
});

Schema Validation

rq.test("Valid schema", () => {
  rq.response.to.have.jsonSchema({
    type: "object",
    required: ["id"],
    properties: { id: { type: "number" } }
  });
});

Skipping Tests

rq.test.skip("Temporarily disabled test", () => {
  // This test won't run
});

Response specific assertions

rq.response.to is rq.expect(rq.response).to, and rq.request.to is rq.expect(rq.request).to. They take every assertion rq.expect takes, plus the request and response assertions below. rq.expect also takes these assertions on a response from rq.sendRequest. Status code assertions

// Success responses
rq.response.to.be.ok             // 200 with the reason phrase OK
rq.response.to.be.success        // 2XX
rq.response.to.be.accepted       // 202
rq.response.to.be.withoutContent // 204

// Client error responses
rq.response.to.be.badRequest    // 400
rq.response.to.be.unauthorized  // 401
rq.response.to.be.forbidden     // 403
rq.response.to.be.notFound      // 404
rq.response.to.be.notAcceptable // 406
rq.response.to.be.rateLimited   // 429
rq.response.to.be.clientError   // 4XX

// Server error responses
rq.response.to.be.serverError // 5XX

// Other status categories
rq.response.to.be.error       // 4XX or 5XX
rq.response.to.be.info        // 1XX
rq.response.to.be.redirection // 3XX

// Any hundred
rq.response.to.have.statusCodeClass(2) // 2XX

The named statuses (ok, accepted, notFound and the rest) check the reason phrase as well as the code. Use success for any 2XX code, for example a 201 Created or a 204 No Content. .to.have assertions

// A number checks the status code. A string checks the reason phrase exactly,
// case included.
rq.response.to.have.status(200);
rq.response.to.have.status("OK");
rq.response.to.have.statusCode(200);
rq.response.to.have.statusReason("OK");

// Checks if response has the specified header. The header name is matched
// case-insensitively.
rq.response.to.have.header("Content-Type");

// With a second argument, also checks the header's value. The value must match
// exactly: the comparison is case-sensitive and whitespace is not trimmed.
rq.response.to.have.header("Content-Type", "application/json");

// Checks the body. A string must equal the body exactly. A regular expression
// must match it. An object must equal the parsed JSON body. With no argument,
// checks that the body is not empty.
rq.response.to.have.body("pong");
rq.response.to.have.body(/"status":\s*"active"/);
rq.response.to.have.body({ status: "active" });

// Checks that the body has content, or that it is valid JSON.
rq.response.to.be.withBody;
rq.response.to.be.json;

// Validates that response body is valid JSON.
rq.response.to.have.jsonBody();

// Checks if a path exists in the response.
rq.response.to.have.jsonBody("user.name");

// Checks if a JSON path has a specific value.
rq.response.to.have.jsonBody("user.name", "John");

// Checks the response time or the response size (headers and body, in bytes).
// Chain a numeric assertion after either one.
rq.response.to.have.responseTime.below(500);
rq.response.to.have.responseSize.below(10240);

// Validates the response body against a JSON schema. Accepts optional Ajv configuration.
rq.response.to.have.jsonSchema({
  type: "object",
  required: ["id", "name"],
  properties: {
    id: { type: "number" },
    name: { type: "string" },
    email: { type: "string", format: "email" }
  }
}, { allErrors: true });

// Any other value is validated as it is.
rq.expect({ id: 1 }).to.have.jsonSchema({ required: ["id"] });

Negation with .to.not All the above assertions can be negated by inserting .not after .to:

rq.response.to.not.be.error;
rq.response.to.not.have.header("X-Custom");
rq.response.to.not.have.jsonBody("error");

.not.have.header() checks only that the header is absent. If you pass a value as the second argument it is ignored, so rq.response.to.not.have.header("Content-Type", "text/html") fails whenever the header is present, whatever its value. To assert that a header exists but holds a different value, compare it directly: rq.expect(rq.response.headers.get("Content-Type")).to.not.equal("text/html").

Getting Started

API Design

Mock Server

Collaboration & Projects

Account & Administration

Writing Tests

Scripting Environment

Writing Tests

Example Tests

Status Code Check

JSON Body Validation

Header Check

Schema Validation

Skipping Tests

Response specific assertions

​Scripting Environment

​Writing Tests

​Example Tests

​Status Code Check

​JSON Body Validation

​Header Check

​Schema Validation

​Skipping Tests

​Response specific assertions

Scripting Environment

Writing Tests

Example Tests

Status Code Check

JSON Body Validation

Header Check

Schema Validation

Skipping Tests

Response specific assertions