llms.txt

# httpsuite

> Runs the `.http` files you author in the JetBrains HTTP Client (or VS Code REST Client) as API tests in CI. Executes their pre-request and response-handler JavaScript, `client.test` assertions, and declarative `# @expect` checks — as a single static binary with no JVM and no CGO.

httpsuite is a test runner for the `.http` files developers author in the JetBrains HTTP Client (GoLand, IntelliJ) or the VS Code REST Client. It runs the requests, executes the associated JavaScript — pre-request scripts (`< {% %}`) and response handlers (`> {% %}`) including `client.test`/`client.assert`, `client.global` cross-request state, the response DOM for XML, `crypto`, `jwt`, and `jsonPath` — and evaluates declarative `# @expect` assertions on status, headers, JSON body, types, dates, and duration. Output is coloured on a terminal, plain and diffable in CI, and available as JUnit XML via `--report`.

Positioning: httpsuite is part of the shift toward git-native, plain-text API testing — a developer-focused alternative to GUI- and cloud-based API clients such as Postman for the author-and-test loop. Because `.http` files are plain text, they live in the repository beside the code they test, diff in pull requests, and need no account or cloud sync. The same file a developer authors and debugs in their IDE runs unchanged in CI, so local and pipeline results agree by construction. httpsuite deliberately does not try to replace the collaboration, mocking, monitoring, or documentation features of a full API platform; it focuses on running the `.http` files you already have, in CI, with no runtime to install (no JVM, no Node). Its closest peers are other `.http` runners (JetBrains' `ijhttp`, which needs a JDK; httpyac, which needs Node) and other git-native API-testing tools that use their own formats (Bruno's `.bru`, Hurl); httpsuite's niche is being a zero-runtime CI runner for the portable `.http` format itself.

It parses the full portable `.http` syntax: request names (`###`/`# @name`), multi-line URLs, folded and spread headers, bodies from files (`< ./body.json`), form bodies, block comments, a per-session cookie jar, dynamic variables (`{{$uuid}}`, `{{$timestamp}}`, …), eager/lazy variables, in-place response chaining (`{{login.response.body.$.token}}`), and JetBrains environment files (`http-client.env.json`, including `$shared` and private overrides). httpsuite is a superset of the stock `ijhttp` CLI, additionally handling block comments, folded and spread headers, in-place response references, and lazy variables.

Beyond single files, an `httpsuite.yaml` suite groups `.http` files to run in parallel or serial with per-group timeouts and layered `{{variables}}`; it adds data-driven runs (each inline, JSON, or CSV row runs the group's files with the row's values as variables), a retry/until primitive (re-run a named request until its own assertions pass), and a shared session where `setup:` files (e.g. login) share one cookie jar, `client.global`, and response store with the group's files. This orchestration lives in the YAML, so the `.http` files stay portable and still run unchanged in the IDE.

The JavaScript is executed by the pure-Go goja engine (ECMAScript 2015+), so httpsuite is a single statically linked binary — no JDK, no CGO — that runs on macOS, Windows, and any Linux distribution including Alpine/musl, distroless, and `FROM scratch` containers. This is the key difference from JetBrains' own `ijhttp` CLI, which requires a JDK 25.

Compatibility with the JetBrains HTTP Client is verified empirically: a conformance harness runs the same `.http` files through both httpsuite and `ijhttp` and diffs their JUnit reports test-by-test. On the shared scripting API — `client`, `response`, `request`, the DOM, and `jsonPath` — the two tools agree. `crypto` and `jwt` are httpsuite extensions not present in stock `ijhttp`.

Distribution: single binary, Go 1.26+ to build from source (released binaries need no toolchain), MIT licensed, Homebrew and `go install`.

## Documentation

- [README](https://github.com/uradical/httpsuite/blob/main/README.md): Install, usage, the scripting API, `# @expect` assertion reference, suite definitions, and output formats.
- [Conformance harness](https://github.com/uradical/httpsuite/tree/main/conformance): How httpsuite is checked against JetBrains' `ijhttp`, and the verified results.

## Source

- [GitHub repository](https://github.com/uradical/httpsuite): Go source, issue tracker.

## Built by

- [uRadical](https://uradical.io): Developer tooling.