RawHTTP ReqInEdit

Javadocs

The rawhttp-req-in-edit module implements a runner for HTTP files written in the Request In Editor Specification format created by JetBrains to make it easier to execute HTTP requests and test their responses.

HTTP requests are written in a way that’s very close to the HTTP RFC-7230, but with several extensions intended for easier requests composing and editing.

ReqInEdit supports variables, comments, multiple requests in a single file, environments, and response handlers which may assert the contents of HTTP responses and set variables for usage in the next requests.

It is perfect for testing HTTP endpoints.

See the IntelliJ Documentation for the full syntax and examples of writing HTTP files.

The RawHTTP implementation stays as close as possible to the Jetbrains’ specification, but minor variations are unavoidable. Please report any differences you may come across.

Executing HTTP files from the command line

If all you want is to execute HTTP files from the command line or bash scripts, use the RawHTTP CLI, which uses rawhttp-req-in-edit to execute HTTP files.

The rest of this document regards the usage of rawhttp-req-in-edit as a Java library, not as a CLI tool.

Basic Usage

To execute a HTTP file, parse the file with the com.athaydes.rawhttp.reqinedit.ReqInEditParser class, then execute it with com.athaydes.rawhttp.reqinedit.ReqInEditUnit:

var parser = new ReqInEditParser();

try {
    var entries = parser.parse(new File("my.http"));
    var allSuccess = new ReqInEditUnit().run(entries);
    if (allSuccess) {
        System.out.println("All tests passed");
    } else {
        System.out.println("There were test failures");
    }
} catch (IOException e) {
    // handle error
}

Customizing ReqInEditUnit

The ReqInEditUnit class, used to run the parsed entries from a HTTP file as shown above, can be highly customized to modify all behaviour, including the environment, HTTP parser, HTTP client, file reader, response storage and test reporter.

Here’s the full list of parameters in the main constructor:

ReqInEditUnit(HttpEnvironment,
              RawHttp,
              RawHttpClient,
              FileReader,
              ResponseStorage, 
              HttpTestsReporter)

The default HttpEnvironment, com.athaydes.rawhttp.reqinedit.js.JsEnvironment, uses Nashorn to interpret response handlers, and it parses variables using the JavaScript’s Mustache library (obtained in Java via webjars).

Notice that the JsEnvironment can be created with a constructor pointing to the HTTP project’s root dir and with an environment name, so that one can use environments.

The default implementation of ResponseStorage writes any response files found in a HTTP file to an actual file in the working directory.

The following example, when run, will save the HTTP response in the file called response.json in the working directory:

### GET request with parameter
GET https://httpbin.org/get?show_env=1
Accept: application/json

> {%
client.test("Request executed successfully", function() {
  client.assert(response.status === 200, "Response status is not 200");
});
%}
<> response.json

Supported Java versions

RawHTTP modules are still compiled on Java 8 in order to support older code bases, but it’s tested also on Java 11 and Java 17.

When running on Java 17, this module only works since version 0.3.0 due to the removal of Nashorn from the JDK. Since that version, rawhttp-req-in-edit is published as a multi-release jar, which means that:

See the openjdk/nashorn repository for details about using Nashorn as a library. In short, it should work exactly the same as on previous Java versions.