HTTP Client CLI – Run Requests and Tests on CI

Yuriy Artamonov

The HTTP Client is a tool built into JetBrains IDEs that helps you test HTTP requests. We’ve been developing this tool for many years, and it now supports not only HTTP but also many other popular protocols, including gRPC, GraphQL, and WebSocket. It even allows you to write tests and run them as a test suite.

Until recently, this tool has only been available inside our IDEs. This limitation is now a thing of the past, as our new product, the HTTP Client CLI, makes it possible to run HTTP requests and tests from a terminal or on a continuous integration server without an IDE.

Our community has helped us immensely, with users of JetBrains IDEs creating several implementations of similar tools. We would like to thank them for all their work. We have been inspired by their features and approaches to building a CLI for the .http format. The main advantage of our implementation of the HTTP Client CLI is that its parser and execution subsystems directly reuse the code of the IntelliJ IDEA HTTP Client, so your .http files running in the IDE will be always supported by our CLI distribution.

Distribution

You can download the HTTP Client CLI either as a ZIP archive or as a Docker image. The ZIP distribution currently requires JDK 17 to run, but we already have plans to provide platform-dependent builds for each OS in the future.

You can use this line to get it from a terminal:

curl -f -L -o ijhttp.zip "https://jb.gg/ijhttp/latest"

This is an early preview version of the HTTP Client CLI, which means that this version may not be reliable, may not work as intended, and may contain errors. Please help us test it so we can polish it and make the final product as stable as possible.

At the moment, the CLI only supports HTTP requests, though we plan to add support for other protocols in the future.

Running requests from the terminal

Running the HTTP Client from the command line is easy. Just start the ijhttp process by supplying .http files to run and any necessary environment files via arguments:

As you can see, the requests run one by one, and the output shows whether they succeeded or not. Failed requests or failed test asserts result in a “RUN FAILED” message at the end of the output.

In non-interactive environments such as CI servers, the CLI will use a simplified output format that does not include interactive progress.

The CLI supports 3 levels of logging: BASIC, HEADERS, and VERBOSE. Use a --log-level or -L argument to specify the desired level of log output:

There are two ways to supply environment information to the CLI:

• With an .env file:

ijhttp run.http --env-file my.env.json --env dev

• Or via arguments:

ijhttp run.http -V SERVER_HOST=http://staging-server:8080

The CLI also supports private environment variables, whose values will not appear in VERBOSE log outputs:

ijhttp run.http -P PRIVATE_PATH=super-secure-parameter -L VERBOSE

Command line options

In addition to options for files, environments, and logging, the CLI supports additional arguments that are helpful for CI and tests, such as ones to set timeouts and allow insecure SSL connections.

Test results

To see how test failures appear in the output, let’s write a simple test in an .http file:

# Check response status is 200
GET https://httpbin.org/status/404

> {%
  client.test("Request #3 is 200", function() {
    client.assert(response.status === 200, "Response status is not 200");
  });
%}

Here we have a test called “Request #3 is 200”, and this exact name will appear in the output if the test fails:

Test reports

For test automation, the HTTP Client provides output in the JUnit XML format, which is primarily used for visualizing test results on a CI server. This format can be enabled with the –report argument:

ijhttp run.http --report

The resulting report.xml file will appear in the reports folder in the current directory:

Running tests on CI

Like many continuous integration servers, TeamCity supports the JUnit XML report format out of the box and can show such a report in a dedicated Tests view. Check out the TeamCity documentation for details. Here’s how a JUnit XML report generated by the HTTP Client may look in the TeamCity UI:

Docker

It is also possible to use the HTTP Client CLI as a Docker container.

docker run --rm -i -t -v $PWD:/workdir jetbrains/intellij-http-client -e dev -v env.json -p private.env.json -D run.http

Here we add a volume for /workdir. The HTTP Client will automatically use paths relative to this directory, as it is currently the directory set by default when the HTTP Client’s container starts. After providing the volume, the container can be used as if it were locally installed. Just pass the arguments and run the command!

Running requests inside a Docker container can be tricky, especially if the .http file contains requests with localhost URLs. But what does localhost mean inside a container? Does it refer to the localhost of the container or the localhost of the host? In order to resolve this ambiguity, we can use the -D option to give the HTTP Client CLI a hint. With the -D option, the HTTP Client sends all requests with localhost to the localhost of the host machine. In this setup, the HTTP Client CLI resolves localhost to docker.host.internal.

What’s next

We are going to release the HTTP Client CLI as a free product. It will not require a license key, and you should be able to adopt it on your CI servers easily and without any obstacles.

We would like to continue working on the HTTP Client CLI, and we are already planning to add support for the gRPC, WebSocket, and GraphQL protocols.

Please give this EAP version a try and help us build a stable and powerful product! Please post any feedback you have or any issues you encounter to our issue tracker.

Subscribe to IntelliJ IDEA Blog updates

Subscribe form

By submitting this form, I agree to the JetBrains Privacy Policy Notification icon

By submitting this form, I agree that JetBrains s.r.o. ("JetBrains") may use my name, email address, and location data to send me newsletters, including commercial communications, and to process my personal data for this purpose. I agree that JetBrains may process said data using third-party services for this purpose in accordance with the JetBrains Privacy Policy. I understand that I can revoke this consent at any time in my profile. In addition, an unsubscribe link is included in each email.

Submit

Thanks, we've got you!