Hurl: Run and test HTTP requests with plain text

[dm03514]

I just started using hurl a couple months ago.

For my uses it's great that it has both test suite mode and individual invocation mode. I use it to execute a test suite of HTTP requests against a service in CI.

I'm not a super big fan of the configuration language, the blocks are not intuitive and I found some lacking in the documentation assertions that are supported.

Overall the tool has been great, and has been extremely valuable.

I started using interface testing when working on POCs. I found this helps with LLM-assisted development. Tests are written to directly exercise the HTTP methods, it allows for fluidity and evolution of the implementations as the project is evolving.

I also found the separation of testing very helpful, and it further enforces the separation between interface and implementation. Before hurl, the tests I wrote would be written in the test framework of the language the service is written in. The hurl-based tests really help to enforce the "client" perspective. There is no backdoor data access or anything, just strict separation betwen interface, tests and implementation :)

[jicea]

Maintainer here, thanks for the feedbacks. 6-7 years ago, when we started working on Hurl, we started with a JSON then a YAML file format. We gradually convinced ourself to write a new file format and I completely understand that it might feel weird. We tried (maybe not succeeded!) to have something simple for the simple case...

I'm really interested by issues with the documentation: it can always be improved and any issues is welcome!

[1a527dd5]

Yeah love Hurl, we stared using it back in 2023-09.

We had a test suite using Runscope, I hated that changes weren't versioned controlled. Took a little grunt work and I converted them in Hurl (where were you AI?) and got rid of Runscope.

Now we can see who made what change when and why. It's great.

[johns]

I also hated that Runscope changes weren't version controlled :) We had started work on that but then things went sideways.

[jicea]

Hi Hurl maintainer here, happy to answer any question and get feedbacks!

[gavinray]

So, myself and many folks I know have taken to writing tests in the form of ".http" files that can be executed by IDE extensions in VS Code/IDEA.

Those basically go in the form

   POST http://localhost:8080/api/foo
   Content-Type: application/json

   { "some": "body" }

And then we have a 1-to-1 mapping of "expected.json" outputs for integration tests.

We use a bespoke bash script to run these .http file with cURL, and then compare the outputs with jq, log success/failure to console, and write "actual.json"

Can I use HURL in a similar way? Essentially an IDE-runnable example HTTP request that references a JSON file as the expected output?

And then run HURL over a directory of these files?

[hiddew]

Hurl is underappreciated for writing nice and maintainable HTTP-level test suites. Thanks for the tool!

[LadyCailin]

Can you organize with the VSCode rest client folk(s?) to come up with a standard for http files?

[airstrike]

Arguably off-topic but I just want to say few naming choices give me more satisfaction than Hurl

[jiehong]

Thanks a lot for maintaining it!

Where do you see hurl in the next 2 years?

[nikeee]

I use Hurl for some time now and even contributed. What are the current chances for getting some form of includes?

[perrygeo]

Hurl is awesome. A while back I ported a small web service from Python to Rust. Having rigorous tests of the public API is amazing; a language-independent integration test! I was able to swap it out with no changes to the public API or website.

Worth mentioning that using Hurl in Rust specifically gives you a nice bonus feature: integration with cargo test tooling. Since Hurl is written in Rust, you can hook into hurl-the-library and reuse your .hurl files directly in your test suite. Demo: https://github.com/perrygeo/axum-hurl-test

[hliyan]

I must say, the sample section[1] does an excellent job of making a case for the tool, especially to people who are inclined to make a snap judgement about the usefulness of the tool within the first 5 minutes (I'm sometimes guilty of this).

[1] https://github.com/Orange-OpenSource/hurl?tab=readme-ov-file...

[twodave]

I took a lot of inspiration from this project when designing my own HTTP testing tool[0]. We needed to be able to run hundreds of tests quickly, and in parallel. If that is something you need and you like Hurl, then you might like Nap also.

[0] https://naprun.dev

[bitpush]

Is the config same/different/similar than hurl? Do you have a page that outlines the differences, if any?

[chvid]

Looks a bit like this:

https://marketplace.visualstudio.com/items?itemName=humao.re...

Which is a banger VS Code extension for all sorts of http xyz testing.

[krisgenre]

IntelliJ has one too https://www.jetbrains.com/help/idea/http-client-in-product-c...

[jiehong]

Yep, just editor independent which is a huge deal IMO

[mcescalante]

yep, I've played with Hurl and find it nice but recently have been leaning into the .http stuff more. IntelliJ has it built in, there's the plugin you linked, and then for CLI i've used httpYac. No "vendor lock in", really easy to share with copy & paste or source control.

[3eb7988a1663]

I think the idea is nice, but I am struggling for why I should use it. I write using Django, which has plenty of hooks for testing within the framework. Why switch to a tool which is blind to my backend and is going to create more work to keep in sync? At minimum, I lose the ability to easily drop into my debugger to inspect why a result went wrong.

There is probably something to be said for keeping a hard boundary between the backend and testing code, but this would require more effort to create and maintain. I would still need to run the native test suite, so reaching out to an external tool feels a little weird. Unless it was just to ensure an API was fully generic enough for people to run their own clients against it.

[thiht]

> Why switch to a tool which is blind to my backend and is going to create more work to keep in sync? At minimum, I lose the ability to easily drop into my debugger to inspect why a result went wrong.

I don't use hurl but I've used other tools to write language agnostic API tests (and I'm currently working on a new one) so here's what I like about these kinds of tests:

- they're blind to the implementation, and that's actually a pro in my opinion. It makes sure you don't rely on internals, you just get the input and the output

- they can easily serve as documentation because they're language agnostic and relatively easy to share. They're great for sharing between teams in addition to or instead of an OpenAPI spec

- they actually test a contract, and can be reused in case of a migration. I've worked on a huge migration of a public API from Perl to Go and we wanted to keep relatively the same contracts (since the API was public). So we wrote tests for the existing Perl API as a non-regression harness, and could keep the exact same tests for the Go API since they were independent from the language. Keeping the same tests gave us greater confidence than if we had to rewrite tests and it was easy to add more during the double-run/A-B test period

- as a developer, writing these forces you to switch context and become a consumer of the API you just wrote, I've found it easier to write good quality tests with this method

[sorashi]

It's just an alternative to Postman and similar so you don't have to start a whole damn electron window just to test a few http requests. It's somewhere between a curl script and Postman, so it hits the right spot for many.

[jicea]

We used Hurl to go from a ktor web server to a spring boot rewrite (Java/Kotlin stack). It was a breeze to have a kind of specifications test suite independent of the server stack and helped us a lot in the transition.

Another benefit is we built a Docker image for production and wanted to have something light and not tight to the implementation for integration tests.

[CoolCold]

There is no obligation on you to use it, especially if you have better tooling for the tasks.

For my team needs, I see benefits of using self-contained tool which doesn't require any extra modules to be installed and venv-like activated (this is a great barrier when ensuring others can use it too). Not even mention it will run fast.

Testing headers is particularly nice, so can test configuration of webservers and LBs/CDNs.

[kalli]

This looks interesting. Longtime user of the Vscode-restclient, but have been moving over to httpyac lately for the scripting and cli use. Will take a look to see if hurl is a good fit.

One annoying thing I've found in testing these tools is that a standard hasn't emerged for using the results of one request as input for another in the syntax of `.http` files. These three tools for instance have three different ways of doing it:

* hurl uses `[Captures]`

* Vscode-restclient does it by referencing request names in a variable declaration (like: `@token = {{loginAPI.response.body.token}}`).

* While httpyac uses `@ref` syntax.

From a quick round of testing it seems like using the syntax for one might break the other tools.

[1]: https://hurl.dev/docs/capturing-response.html

[2]: https://github.com/Huachao/vscode-restclient

[3]: https://httpyac.github.io/guide/metaData.html#ref-and-forcer...

[jicea]

Guilty to have created yet-another-format for HTTP client! To "mitigate" this issue, you can use `hurlfmt` (distributed along `hurl`) that would allow you to export a Hurl file to JSON. You could then go from this JSON to another... It's not magic but it can help if you're going to change from Hurl to another thing.

[jiggawatts]

What's really special is that Visual Studio Code and Visual Studio both have .HTTP files... which are incompatible with each other.

Conway's Law in action, ladies and gentlemen.

[a57721]

In the JVM projects, I use Karate for integration tests: https://github.com/karatelabs/karate

It gives you full control of constructing requests and assertions because test scenarios may include arbitrary JavaScript.

[the_arun]

Isn't this similar to HTTP Client tool available for IntelliJ? - https://www.jetbrains.com/help/idea/http-client-in-product-c...

[resonious]

Similar perhaps but not an IDE plugin.

[mdtrooper]

I love this kind of tools (easy, simple and cli). I remember that https://httpie.io/cli or https://jqlang.org/ .

[manithree]

With nice editor integration (especially emacs), hurl is a good postman replacement.

Kinda niche, but I wrapped libhurl to make it really easy to make an AWS Lambda availability monitor out of a hurl file https://gitlab.com/manithree/hurl_lambda

[Thaxll]

It looks interesting, I had a look a the dependencies, 1.5k lines for a cli tool to test http calls ( and more ), is it the norm in Rust?

https://github.com/Orange-OpenSource/hurl/blob/master/Cargo....

[ewpratten]

You should probably be looking at the Cargo.toml file(s) (for direct dependencies at least) instead of the lock file as the lock file will include dependencies used for dev/testing.

[laerus]

What's missing from Hurl is snapshot testing. After using `insta` for testing APIs, I cannot go back.

[porker]

Is this https://insta.rs/? What are the benefits you've found with snapshot testing?

[whilenot-dev]

What's your value proposition for snapshots and why can't that already be fulfilled with full body checks? https://github.com/Orange-OpenSource/hurl?tab=readme-ov-file...

[CommonGuy]

We are working on snapshot testing for Kreya, expected to come in August. You might want to check it out :)

[yoavm]

The one thing I never understood about the Hurl format is why the response status code assertion happens at the request section and not under the `[Asserts]` section. I wonder what the rationale behind that is.

[jicea]

A simple GET with a status code is just

  GET http://foo.com
  HTTP 200

You could write also

  GET http://foo.com
  HTTP *
  [Asserts]
  status == 200

HTTP serves as a marker of the response section

[infogulch]

Hurl has been great for testing in my RAD templating web server project. Like dm03514 says itt, 'The hurl-based tests really help to enforce the "client" perspective.' It's packaged for 3 application environments including a docker image (x2 archs, x3 oses) and with Hurl its easy to ensure the tests pass at the client level in all three environments.

It would be nice to have fancy-regex; today I tried to write a regex to match a case like this ~ <link href="/assets/reset.css\\?hash=(.*)" integrity="\\1" rel="stylesheet"> ~ but the regex crate (and thus hurl asserts) can't do backreferences so I guess I'll just live without checking that these two substrings match.

I wish there was some way to test streamed updates / SSE. Basically, open a connection and wait, then run some other http requests, then assert the accumulated stream from the original connection. https://github.com/Orange-OpenSource/hurl/discussions/2636

[lelanthran]

For automated testing I use hurl, but my personal dev roadmap is to create another tool.

The deficiencies in huel with client state management is not easy to fix.

What I'd like is full client state control with better variable management and use.

For my last project I used Python to write the tests, which appears to work well initially. Dunno how well it will hold up for ongoing maintenance.

[zoidb]

This looks great, would definitely use it for testing if websocket support ever gets added https://github.com/Orange-OpenSource/hurl/issues/1096

[mikmoila]

Very interesting tool; I've done something quite similar by implementing a CLI-mode interpreter to VS Code Rest-client (https://marketplace.visualstudio.com/items?itemName=humao.re...) files, with a support of executing a test-code (Javascript) against the result of http operations. The idea was to have a tool which could run .http files in batch mode, and also to execute the selected set of http operations concurrently.