HTTP Client CLI – Run Requests and Tests on CI
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
