📣 Hurl file style guideline

[jcamiel]

📣 Hurl file guideline feedbacks

We would like to have feebacks on Hurl file format guidelines. Currently, the file format is line oriented, with a lot of freedom on how a Hurl file is formatted. You can put newline, tab and space almost everywhere and still have a valid Hurl file. We have "unofficial" guidelines when writing Hurl snippets on https://hurl.dev:

• If there is no response section, or if the response section is only the version and status code, group everything:

POST https://foo.com

POST https://foo.com
x-bar: 1234
x-baz:1234
{
  "id": "something"
}

POST https://foo.com
x-bar: 1234
x-baz:1234
[BasicAuth]
alice: secret
{
  "id": "something"
}

POST https://foo.com
x-bar: 1234
x-baz:1234
[BasicAuth]
alice: secret
{
  "id": "something"
}

POST https://foo.com
x-bar: 1234
x-baz:1234
[BasicAuth]
alice: secret
{
  "id": "something"
}
HTTP 201

• If there is a response section, put one newline between the request and the response:

POST https://foo.com
x-bar: 1234
x-baz:1234
[BasicAuth]
alice: secret
{
  "id": "something"
}

HTTP 201
[Assert]
header "Content-Type" contains "json"
jsonpath "$.status" == "VERIFIED"

• add two new lines between each entry (an entry = one request + one optional response).

POST https://foo.com
x-bar: 1234
x-baz:1234
{
  "id": "something"
}


POST https://foo.com
x-bar: 1234
x-baz:1234
[BasicAuth]
alice: secret
{
  "id": "something"
}

HTTP 201
[Assert]
header "Content-Type" contains "json"
jsonpath "$.status" == "VERIFIED"

If we look at Hurl files in the wild, there are a lot of varieties and we would like to enforce a particular style (through the documentation and hurlfmt). One style that we like more and more is the "all grouped" ones:

• now new line between request and response
• one line between two entries

POST https://foo.com
x-bar: 1234
x-baz:1234
{
  "id": "something"
}

POST https://foo.com
x-bar: 1234
x-baz:1234
[BasicAuth]
alice: secret
{
  "id": "something"
}
HTTP 201
[Assert]
header "Content-Type" contains "json"
jsonpath "$.status" == "VERIFIED"

For instance here: https://gitlab.com/brie/hurl/-/blob/main/hello.hurl, and here https://github.com/input-output-hk/cicero/blob/68a3b74024d8f63d366a63cfff73d70d7a576c12/packages/cicero/default.nix#L230.
Give us feedbacks or proposition on what is a good style for Hurl !
(and yes, we need to put more work on the syntax coloring story)

Thanks,

[shanepelletier]

Firstly, thanks to all maintainers for the awesome tool!

I just discovered it today (but plan on using it once I'm back at work to write up some quick spot-checks for our APIs), so my feedback should definitely be given less weight than someone who's been using hurl for longer, but I wanted to add my opinion anyway 🙂.

I personally really like seeing the response section separated from the request, as it makes it immediately clear to my untrained eye that the entry contains two parts, and makes it clear which of those two parts corresponds with the request and which corresponds to the response. This may be something that is immediately clear to more experienced users, but at a glance I would have a difficult time figuring out the expected behaviour of an entry without the separation. I would even argue for including a blank line between the request and the simple response section of "HTTP 201" in the fifth example, although I can see that it could make a file a lot longer than necessary if the file just contained entries with such simple responses.

I'm quite easily swayed by good arguments, so I'm curious why you prefer the "all grouped" format. Are there some reasons you can articulate, or is it more just a case of a gut feeling that the format is better based on your experience? Both answers are, of course, completely fine, I just like a good discussion of stylistic things like this 😄.

[jcamiel]

Hi @shanepelletier thanks for the feedback! The style we tend to like for the moment is the style where request and response are grouped together. We initially wrote our own Hurl files by separating the request and the response (like all current snippets in the documentation https://hurl.dev), but we find with experience that the "grouped" style is more appropriate to long files.

For instance in https://github.com/input-output-hk/cicero/blob/main/packages/cicero/default.nix:

GET http://localhost:8080/api/fact/${testData.fooFact.id}
Content-Type: application/json; charset=utf-8
HTTP 200
[Asserts]
jsonpath "$.id" == "${testData.fooFact.id}"
jsonpath "$.value.foo" == "${testData.fooFact.value.foo}"

GET http://localhost:8080/api/fact/${testData.barFact.id}
Content-Type: application/json; charset=utf-8
HTTP 200
[Asserts]
jsonpath "$.id" == "${testData.barFact.id}"
jsonpath "$.value.bar" == "${testData.barFact.value.bar}"

GET http://localhost:8080/api/action
HTTP 200
Content-Type: application/json; charset=utf-8
[Asserts]
jsonpath "$" count == 1
jsonpath "$[0].id" == "${testData.actionId}"
jsonpath "$[0].name" == "${testData.actionName}"
jsonpath "$[0].source" == "${src}"
jsonpath "$[0].created_at" == "${testData.timestamp}"
jsonpath "$[0].meta" == null
jsonpath "$[0].io" != null

GET http://localhost:8080/api/action/${testData.actionId}
HTTP 200
Content-Type: application/json; charset=utf-8
[Asserts]
jsonpath "$.id" == "${testData.actionId}"
jsonpath "$.name" == "${testData.actionName}"
jsonpath "$.source" == "${src}"
jsonpath "$.created_at" == "${testData.timestamp}"
jsonpath "$.meta" == null
jsonpath "$.io" != null

is quite pleasant.

If we have only request, we like also to write:

GET http://localhost:8080/api/fact/${testData.fooFact.id}
GET http://localhost:8080/api/fact/${testData.barFact.id}
GET http://localhost:8080/api/action
GET http://localhost:8080/api/action/${testData.actionId}

(no new lines)

So our pref have changed. Another thing to take account is, for the moment, the IDE support and syntax coloring support is rather poor for Hurl files (it's a big complex feature to address). That's why we want the Hurl syntax to be readable and clean without syntax coloring for the moment, even if syntax coloring and proper tool support will be a big plus. Having a "standard" format will help also.

So, we really want to have an "auto" formatter "à la" rustfmt but, we need to have more input like yours!

[shanepelletier]

Seeing all the single requests laid out together without newlines does look super clean now that I see it, so my preference matches yours in that case!

Looking at the input-output-hk/cicero example a bit more (and absorbing the hurl syntax a bit more), I can see that the style proposed here is probably the way to go for longer files, and works for shorter files too. As I said, I'm fairly easy to sway, so count me as a +1 for the proposed guidelines.