What's Hurl?

Hurl is a command line tool that runs HTTP requests defined in a simple plain text format.

It can chain requests, capture values and evaluate queries on headers and body response. Hurl is very versatile: it can be used for both fetching data and testing HTTP sessions.

Hurl makes it easy to work with HTML content, REST / SOAP / GraphQL APIs, or any other XML / JSON based APIs.

# Get home:
GET https://example.org
HTTP 200
[Captures]
csrf_token: xpath "string(//meta[@name='_csrf_token']/@content)"


# Do login!
POST https://example.org/login?user=toto&password=1234
X-CSRF-TOKEN: {{csrf_token}}
HTTP 302

Chaining multiple requests is easy:

GET https://example.org/api/health
GET https://example.org/api/step1
GET https://example.org/api/step2
GET https://example.org/api/step3

Also an HTTP Test Tool

Hurl can run HTTP requests but can also be used to test HTTP responses. Different types of queries and predicates are supported, from [XPath] and [JSONPath] on body response, to assert on status code and response headers.

It is well adapted for REST / JSON APIs

POST https://example.org/api/tests
{
    "id": "4568",
    "evaluate": true
}
HTTP 200
[Asserts]
header "X-Frame-Options" == "SAMEORIGIN"
jsonpath "$.status" == "RUNNING"    # Check the status code
jsonpath "$.tests" count == 25      # Check the number of items
jsonpath "$.id" matches /\d{4}/     # Check the format of the id

HTML content

GET https://example.org
HTTP 200
[Asserts]
xpath "normalize-space(//head/title)" == "Hello world!"

GraphQL

POST https://example.org/graphql
```graphql
{
  human(id: "1000") {
    name
    height(unit: FOOT)
  }
}
```
HTTP 200

and even SOAP APIs

POST https://example.org/InStock
Content-Type: application/soap+xml; charset=utf-8
SOAPAction: "http://www.w3.org/2003/05/soap-envelope"
<?xml version="1.0" encoding="UTF-8"?>
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope" xmlns:m="https://example.org">
  <soap:Header></soap:Header>
  <soap:Body>
    <m:GetStockPrice>
      <m:StockName>GOOG</m:StockName>
    </m:GetStockPrice>
  </soap:Body>
</soap:Envelope>
HTTP 200

Hurl can also be used to test the performance of HTTP endpoints

GET https://example.org/api/v1/pets
HTTP 200
[Asserts]
duration < 1000  # Duration in ms

And check response bytes

GET https://example.org/data.tar.gz
HTTP 200
[Asserts]
sha256 == hex,039058c6f2c0cb492c533b0a4d14ef77cc0f78abccced5287d84a1a2011cfb81;

Finally, Hurl is easy to integrate in CI/CD, with text, JUnit, TAP and HTML reports

Why Hurl?

<ul class="showcase-container"> <li>Text Format: for both devops and developers</li> <li>Fast CLI: a command line for local dev and continuous integration</li> <li>Single Binary: easy to install, with no runtime required</li> </ul>

Powered by curl

Hurl is a lightweight binary written in [Rust]. Under the hood, Hurl HTTP engine is powered by [libcurl], one of the most powerful and reliable file transfer libraries. With its text file format, Hurl adds syntactic sugar to run and test HTTP requests, but it's still the [curl] that we love: fast, efficient and HTTP/3 ready.

Feedbacks

To support its development, [star Hurl on GitHub]!

[Feedback, suggestion, bugs or improvements] are welcome.

POST https://hurl.dev/api/feedback
{
  "name": "John Doe",
  "feedback": "Hurl is awesome!"
}
HTTP 200

Resources

[License]

[Blog]

[Tutorial]

[Documentation]

[GitHub]

Samples
Manual
- Name
- Synopsis
- Description
- Hurl File Format
  - Capturing values
  - Asserts
- Options
- Environment
- Exit Codes
- WWW
- See Also
Installation
- Binaries Installation
  - Linux
  - macOS
    - Homebrew
    - MacPorts
  - FreeBSD
  - Windows
  - Cargo
  - conda-forge
  - Docker
  - npm
- Building From Sources

Samples

To run a sample, edit a file with the sample content, and run Hurl:

$ vi sample.hurl

GET https://example.org

$ hurl sample.hurl

By default, Hurl behaves like [curl] and outputs the last HTTP response's [entry]. To have a test oriented output, you can use [--test option]:

$ hurl --test sample.hurl

A particular response can be saved with [[Options] section][option]:

GET https://example.ord/cats/123
[Options]
output: cat123.txt    # use - to output to stdout
HTTP 200

GET https://example.ord/dogs/567
HTTP 200

You can check [Hurl tests suite] for more samples.

Getting Data

A simple GET:

GET https://example.org

Requests can be chained:

GET https://example.org/a
GET https://example.org/b
HEAD https://example.org/c
GET https://example.org/c

Doc

HTTP Headers

A simple GET with headers:

GET https://example.org/news
User-Agent: Mozilla/5.0 
Accept: */*
Accept-Language: en-US,en;q=0.5
Accept-Encoding: gzip, deflate, br
Connection: keep-alive

Doc

Query Params

GET https://example.org/news
[QueryStringParams]
order: newest
search: something to search
count: 100

Or:

GET https://example.org/news?order=newest&search=something%20to%20search&count=100

With [QueryStringParams] section, params don't need to be URL escaped.

Doc

Basic Authentication

GET https://example.org/protected
[BasicAuth]
bob: secret

Doc

This is equivalent to construct the request with a [Authorization] header:

# Authorization header value can be computed with `echo -n 'bob:secret' | base64`
GET https://example.org/protected
Authorization: Basic Ym9iOnNlY3JldA==

Basic authentication section allows per request authentication. If you want to add basic authentication to all the requests of a Hurl file you could use [-u/--user option]:

$ hurl --user bob:secret login.hurl

[--user] option can also be set per request:

GET https://example.org/login
[Options]
user: bob:secret
HTTP 200

GET https://example.org/login
[Options]
user: alice:secret
HTTP 200

Passing Data between Requests

[Captures] can be used to pass data from one request to another:

POST https://sample.org/orders
HTTP 201
[Captures]
order_id: jsonpath "$.order.id"

GET https://sample.org/orders/{{order_id}}
HTTP 200

Doc

Sending Data

Sending HTML Form Data

POST https://example.org/contact
[FormParams]
default: false
token: {{token}}
email: john.doe@rookie.org
number: 33611223344

Doc

Sending Multipart Form Data

POST https://example.org/upload
[MultipartFormData]
field1: value1
field2: file,example.txt;
# One can specify the file content type:
field3: file,example.zip; application/zip

Doc

Multipart forms can also be sent with a [multiline string body]:

POST https://example.org/upload
Content-Type: multipart/form-data; boundary="boundary"
```
--boundary
Content-Disposition: form-data; name="key1"

value1
--boundary
Content-Disposition: form-data; name="upload1"; filename="data.txt"
Content-Type: text/plain

Hello World!
--boundary
Content-Disposition: form-data; name="upload2"; filename="data.html"
Content-Type: text/html

<div>Hello <b>World</b>!</div>
--boundary--
```

In that case, files have to be inlined in the Hurl file.

Doc

Posting a JSON Body

With an inline JSON:

POST https://example.org/api/tests
{
    "id": "456",
    "evaluate": true
}

Doc

With a local file:

POST https://example.org/api/tests
Content-Type: application/json
file,data.json;

Doc

Templating a JSON Body

PUT https://example.org/api/hits
Content-Type: application/json
{
    "key0": "{{a_string}}",
    "key1": {{a_bool}},
    "key2": {{a_null}},
    "key3": {{a_number}}
}

Variables can be initialized via command line:

$ hurl --variable a_string=apple \
       --variable a_bool=true \
       --variable a_null=null \
       --variable a_number=42 \
       test.hurl

Resulting in a PUT request with the following JSON body:

{
    "key0": "apple",
    "key1": true,
    "key2": null,
    "key3": 42
}

Doc

Templating a XML Body

Using templates with [XML body] is not currently supported in Hurl. You can use templates in [XML multiline string body] with variables to send a variable XML body:

POST https://example.org/echo/post/xml
```xml
<?xml version="1.0" encoding="utf-8"?>
<Request>
    <Login>{{login}}</Login>
    <Password>{{password}}</Password>
</Request>
```

Doc

Using GraphQL Query

A simple GraphQL query:

POST https://example.org/starwars/graphql
```graphql
{
  human(id: "1000") {
    name
    height(unit: FOOT)
  }
}
```

A GraphQL query with variables:

POST https://example.org/starwars/graphql
```graphql
query Hero($episode: Episode, $withFriends: Boolean!) {
  hero(episode: $episode) {
    name
    friends @include(if: $withFriends) {
      name
    }
  }
}

variables {
  "episode": "JEDI",
  "withFriends": false
}
```

GraphQL queries can also use [Hurl