| layout | doc |
|---|---|
| title | Entry |
| section | File Format |
A Hurl file is a list of entries, each entry being a mandatory [request], optionally followed by a [response].
Responses are not mandatory, a Hurl file consisting only of requests is perfectly valid. To sum up, responses can be used to [capture values] to perform subsequent requests, or [add asserts to HTTP responses].
# First, test home title.
GET https://acmecorp.net
HTTP 200
[Asserts]
xpath "normalize-space(//head/title)" == "Hello world!"
# Get some news, response description is optional
GET https://acmecorp.net/news
# Do a POST request without CSRF token and check
# that status code is Forbidden 403
POST https://acmecorp.net/contact
[Form]
default: false
email: john.doe@rookie.org
number: 33611223344
HTTP 403[Options] specified on the command line apply to every entry in an Hurl file. For instance, with [--location option],
every entry of a given file will follow redirection:
$ hurl --location foo.hurlYou can use an [[Options] section][options] to set option only for a specified request. For instance, in this Hurl file,
the second entry will follow location (so we can test the status code to be 200 instead of 301).
GET https://google.fr
HTTP 301
GET https://google.fr
[Options]
location: true
HTTP 200
GET https://google.fr
HTTP 301You can use the [Options] section to log a specific entry:
# ... previous entries
GET https://api.example.org
[Options]
very-verbose: true
HTTP 200
# ... next entriesRequests in the same Hurl file share the cookie storage, enabling, for example, session based scenario.
By default, Hurl doesn't follow redirection. To effectively run a redirection, entries should describe each step of the redirection, allowing insertion of asserts in each response.
# First entry, test the redirection (status code and 'Location' header)
GET https://example.org
HTTP 301
Location: https://www.example.org
# Second entry, the 200 OK response
GET https://www.example.org
HTTP 200Alternatively, one can use [--location] / [--location-trusted] options to force redirection
to be followed. In this case, asserts are executed on the last received response. Optionally, the number of
redirections can be limited with [--max-redirs].
# Running hurl --location foo.hurl
GET https://example.org
HTTP 200Finally, you can force redirection on a particular request with an [[Options] section][options] and the [--location]
/ [--location-trusted] options:
GET https://example.org
[Options]
location-trusted: true
HTTP 200Redirections can be tested either by:
- running and asserting each step of redirection:
GET https://example.org/step1
HTTP 301
[Asserts]
header "Location" == "https://example.org/step2"
GET https://example.org/step2
HTTP 301
[Asserts]
header "Location" == "https://example.org/step3"
GET https://example.org/step3
HTTP 200- using [
--location] / [--location-trusted], testing each step with [redirectsquery]:
GET https://example.org/step1
[Options]
location: true
HTTP 200
[Asserts]
redirects count == 2
redirects nth 0 location == "https://example.org/step2"
redirects nth 1 location == "https://example.org/step3"[url query] can also be used to get the final effective URL:
GET https://example.org/step1
[Options]
location: true
HTTP 200
[Asserts]
url == "https://example.org/step3"Every entry can be retried upon asserts, captures or runtime errors. Retries allow polling scenarios and effective runs
under flaky conditions. Asserts can be explicit (with an [[Asserts] section][asserts]), or implicit (like [headers] or [status code]).
Retries can be set globally for every request (see [--retry] and [--retry-interval]),
or activated on a particular request with an [[Options] section][options].
For example, in this Hurl file, first we create a new job then we poll the new job until it's completed:
{% raw %}
# Create a new job
POST http://api.example.org/jobs
HTTP 201
[Captures]
job_id: jsonpath "$.id"
[Asserts]
jsonpath "$.state" == "RUNNING"
# Pull job status until it is completed
GET http://api.example.org/jobs/{{job_id}}
[Options]
retry: 10 # maximum number of retry, -1 for unlimited
retry-interval: 300ms
HTTP 200
[Asserts]
jsonpath "$.state" == "COMPLETED"{% endraw %}
In [Options] section, skip and repeat can be used to control flow of execution:
skip: true/falseskip this request and execute the next one unconditionally,repeat: Nloop the request N times. If there are assert or runtime errors, the requests execution is stopped.
# This request will be played exactly 3 times
GET https://example.org/foo
[Options]
repeat: 3
HTTP 200
# This request is skipped
GET https://example.org/foo
[Options]
skip: true
HTTP 200Additionally, a delay can be inserted between requests, to add a delay before execution of a request (aka sleep).
# A 5 seconds delayed request
GET https://example.org/foo
[Options]
delay: 5s
HTTP 200[delay] and [repeat] can also be used globally as command line options:
$ hurl --delay 500ms --repeat 3 foo.hurlFor complete reference, below is a diagram for the executed entries.
[request]: {% link _docs/request.md %}
[response]: {% link _docs/response.md %}
[capture values]: {% link _docs/capturing-response.md %}
[add asserts to HTTP responses]: {% link _docs/asserting-response.md %}
[--location]: {% link _docs/manual.md %}#location
[--location option]: {% link _docs/manual.md %}#location
[--location-trusted]: {% link _docs/manual.md %}#location-trusted
[--max-redirs]: {% link _docs/manual.md %}#max-redirs
[Options]: {% link _docs/manual.md %}#options
[options]: {% link _docs/request.md %}#options
[headers]: {% link _docs/response.md %}#headers
[status code]: {% link _docs/response.md %}#version-status
[asserts]: {% link _docs/response.md %}#asserts
[Asserts]: {% link _docs/response.md %}#asserts
[--retry]: {% link _docs/manual.md %}#retry
[--retry-interval]: {% link _docs/manual.md %}#retry-interval
[delay]: {% link _docs/manual.md %}#retry
[repeat]: {% link _docs/manual.md %}#repeat
[redirects query]: {% link _docs/asserting-response.md %}#redirects-assert
[url query]: {% link _docs/asserting-response.md %}#url-assert