mirror of
https://github.com/Orange-OpenSource/hurl.git
synced 2024-12-22 18:41:33 +03:00
398 lines
11 KiB
Groff
398 lines
11 KiB
Groff
.TH hurl 1 "24 Jan 2023" "hurl 2.0.0-SNAPSHOT" " Hurl Manual"
|
|
.SH NAME
|
|
|
|
hurl - run and test HTTP requests.
|
|
|
|
|
|
.SH SYNOPSIS
|
|
|
|
.B hurl
|
|
[options] [FILE...]
|
|
|
|
|
|
.SH DESCRIPTION
|
|
|
|
.B 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 fetching data and testing HTTP sessions: HTML content, REST / SOAP / GraphQL APIs, or any other XML / JSON based APIs.
|
|
|
|
$ hurl session.hurl
|
|
|
|
If no input files are specified, input is read from stdin.
|
|
|
|
$ echo GET http://httpbin.org/get | hurl
|
|
{
|
|
"args": {},
|
|
"headers": {
|
|
"Accept": "*/*",
|
|
"Accept-Encoding": "gzip",
|
|
"Content-Length": "0",
|
|
"Host": "httpbin.org",
|
|
"User-Agent": "hurl/0.99.10",
|
|
"X-Amzn-Trace-Id": "Root=1-5eedf4c7-520814d64e2f9249ea44e0"
|
|
},
|
|
"origin": "1.2.3.4",
|
|
"url": "http://httpbin.org/get"
|
|
}
|
|
|
|
|
|
Output goes to stdout by default. To have output go to a file, use the \fI-o, --output\fP option:
|
|
|
|
$ hurl -o output input.hurl
|
|
|
|
By default, Hurl executes all HTTP requests and outputs the response body of the last HTTP call.
|
|
|
|
To have a test oriented output, you can use \fI--test\fP option:
|
|
|
|
$ hurl --test *.hurl
|
|
|
|
|
|
.SH HURL FILE FORMAT
|
|
|
|
The Hurl file format is fully documented in \fIhttps://hurl.dev/docs/hurl-file.html\fP
|
|
|
|
It consists of one or several HTTP requests
|
|
|
|
GET http:/example.org/endpoint1
|
|
GET http:/example.org/endpoint2
|
|
|
|
|
|
.IP "Capturing values"
|
|
|
|
A value from an HTTP response can be-reused for successive HTTP requests.
|
|
|
|
A typical example occurs with CSRF tokens.
|
|
|
|
GET https://example.org
|
|
HTTP 200
|
|
# Capture the CSRF token value from html body.
|
|
[Captures]
|
|
csrf_token: xpath "normalize-space(//meta[@name='_csrf_token']/@content)"
|
|
|
|
# Do the login !
|
|
POST https://example.org/login?user=toto&password=1234
|
|
X-CSRF-TOKEN: {{csrf_token}}
|
|
|
|
More information on captures can be found here \fIhttps://hurl.dev/docs/capturing-response.html\fP
|
|
|
|
.IP "Asserts"
|
|
|
|
The HTTP response defined in the Hurl file are used to make asserts. Responses are optional.
|
|
|
|
At the minimum, response includes assert on the HTTP status code.
|
|
|
|
GET http:/example.org
|
|
HTTP 301
|
|
|
|
It can also include asserts on the response headers
|
|
|
|
GET http:/example.org
|
|
HTTP 301
|
|
Location: http://www.example.org
|
|
|
|
Explicit asserts can be included by combining a query and a predicate
|
|
|
|
GET http:/example.org
|
|
HTTP 301
|
|
[Asserts]
|
|
xpath "string(//title)" == "301 Moved"
|
|
|
|
With the addition of asserts, Hurl can be used as a testing tool to run scenarios.
|
|
|
|
More information on asserts can be found here \fIhttps://hurl.dev/docs/asserting-response.html\fP
|
|
|
|
.SH OPTIONS
|
|
|
|
Options that exist in curl have exactly the same semantics.
|
|
|
|
Options specified on the command line are defined for every Hurl file's entry.
|
|
|
|
For instance:
|
|
|
|
$ hurl --location foo.hurl
|
|
|
|
will follow redirection for each entry in `foo.hurl`. You can also define an option only for a particular entry with an `[Options]` section. For instance, this Hurl file:
|
|
|
|
GET https://example.org
|
|
HTTP 301
|
|
|
|
GET https://example.org
|
|
[Options]
|
|
location: true
|
|
HTTP 200
|
|
|
|
will follow a redirection only for the second entry.
|
|
|
|
.IP "--cacert <FILE> "
|
|
|
|
Specifies the certificate file for peer verification. The file may contain multiple CA certificates and must be in PEM format.
|
|
Normally Hurl is built to use a default file for this, so this option is typically used to alter that default file.
|
|
|
|
.IP "-E, --cert <CERTIFICATE[:PASSWORD]> "
|
|
|
|
Client certificate file and password.
|
|
|
|
See also \fI--key\fP.
|
|
|
|
.IP "--color "
|
|
|
|
Colorize Output.
|
|
|
|
.IP "--compressed "
|
|
|
|
Request a compressed response using one of the algorithms br, gzip, deflate and automatically decompress the content.
|
|
|
|
.IP "--connect-timeout <SECONDS> "
|
|
|
|
Maximum time in seconds that you allow Hurl's connection to take.
|
|
|
|
See also \fI-m, --max-time\fP.
|
|
|
|
.IP "--connect-to <HOST1:PORT1:HOST2:PORT2> "
|
|
|
|
For a request to the given HOST1:PORT1 pair, connect to HOST2:PORT2 instead. This option can be used several times in a command line.
|
|
|
|
See also \fI--resolve\fP.
|
|
|
|
.IP "-b, --cookie <FILE> "
|
|
|
|
Read cookies from FILE (using the Netscape cookie file format).
|
|
|
|
Combined with \fI-c, --cookie-jar\fP, you can simulate a cookie storage between successive Hurl runs.
|
|
|
|
.IP "-c, --cookie-jar <FILE> "
|
|
|
|
Write cookies to FILE after running the session (only for one session).
|
|
The file will be written using the Netscape cookie file format.
|
|
|
|
Combined with \fI-b, --cookie\fP, you can simulate a cookie storage between successive Hurl runs.
|
|
|
|
.IP "--fail-at-end "
|
|
|
|
Continue executing requests to the end of the Hurl file even when an assert error occurs.
|
|
By default, Hurl exits after an assert error in the HTTP response.
|
|
|
|
Note that this option does not affect the behavior with multiple input Hurl files.
|
|
|
|
All the input files are executed independently. The result of one file does not affect the execution of the other Hurl files.
|
|
|
|
.IP "--file-root <DIR> "
|
|
|
|
Set root file system to import files in Hurl. This is used for both files in multipart form data and request body.
|
|
When this is not explicitly defined, the files are relative to the current directory in which Hurl is running.
|
|
|
|
.IP "-L, --location "
|
|
|
|
Follow redirect. To limit the amount of redirects to follow use the \fI--max-redirs\fP option
|
|
|
|
.IP "--glob <GLOB> "
|
|
|
|
Specify input files that match the given glob pattern.
|
|
|
|
Multiple glob flags may be used. This flag supports common Unix glob patterns like *, ? and [].
|
|
However, to avoid your shell accidentally expanding glob patterns before Hurl handles them, you must use single quotes or double quotes around each pattern.
|
|
|
|
.IP "-i, --include "
|
|
|
|
Include the HTTP headers in the output (last entry).
|
|
|
|
.IP "--ignore-asserts "
|
|
|
|
Ignore all asserts defined in the Hurl file.
|
|
|
|
.IP "-k, --insecure "
|
|
|
|
This option explicitly allows Hurl to perform "insecure" SSL connections and transfers.
|
|
|
|
.IP "--interactive "
|
|
|
|
Stop between requests.
|
|
This is similar to a break point, You can then continue (Press C) or quit (Press Q).
|
|
|
|
.IP "--json "
|
|
|
|
Output each hurl file result to JSON. The format is very closed to HAR format.
|
|
|
|
.IP "--key <KEY> "
|
|
|
|
Private key file name.
|
|
|
|
.IP "--max-redirs <NUM> "
|
|
|
|
Set maximum number of redirection-followings allowed
|
|
By default, the limit is set to 50 redirections. Set this option to -1 to make it unlimited.
|
|
|
|
.IP "-m, --max-time <SECONDS> "
|
|
|
|
Maximum time in seconds that you allow a request/response to take. This is the standard timeout.
|
|
|
|
See also \fI--connect-timeout\fP.
|
|
|
|
.IP "--no-color "
|
|
|
|
Do not colorize output.
|
|
|
|
.IP "--no-output "
|
|
|
|
Suppress output. By default, Hurl outputs the body of the last response.
|
|
|
|
.IP "--noproxy <HOST(S)> "
|
|
|
|
Comma-separated list of hosts which do not use a proxy.
|
|
Override value from Environment variable no_proxy.
|
|
|
|
.IP "-o, --output <FILE> "
|
|
|
|
Write output to FILE instead of stdout.
|
|
|
|
.IP "-x, --proxy <[PROTOCOL://]HOST[:PORT]> "
|
|
|
|
Use the specified proxy.
|
|
|
|
.IP "--report-junit <FILE> "
|
|
|
|
Generate JUnit File.
|
|
|
|
If the FILE report already exists, it will be updated with the new test results.
|
|
|
|
.IP "--report-html <DIR> "
|
|
|
|
Generate HTML report in DIR.
|
|
|
|
If the HTML report already exists, it will be updated with the new test results.
|
|
|
|
.IP "--resolve <HOST:PORT:ADDR> <HOST:PORT:ADDR>"
|
|
|
|
Provide a custom address for a specific host and port pair. Using this, you can make the Hurl requests(s) use a specified address and prevent the otherwise normally resolved address to be used. Consider it a sort of /etc/hosts alternative provided on the command line.
|
|
|
|
.IP "--retry "
|
|
|
|
Retry requests if any error occurs (asserts, captures, runtimes etc...).
|
|
|
|
.IP "--retry-interval <MILLISECONDS> "
|
|
|
|
Duration in milliseconds between each retry. Default is 1000 ms.
|
|
|
|
.IP "--retry-max-count <NUM> "
|
|
|
|
Maximum number of retries. Set this option to -1 to make it unlimited. Default is 10.
|
|
|
|
.IP "--ssl-no-revoke "
|
|
|
|
(Windows) This option tells Hurl to disable certificate revocation checks. WARNING: this option loosens the SSL security, and by using this flag you ask for exactly that.
|
|
|
|
.IP "--test "
|
|
|
|
Activate test mode: with this, the HTTP response is not outputted anymore, progress is reported for each Hurl file tested, and a text summary is displayed when all files have been run.
|
|
|
|
.IP "--to-entry <ENTRY_NUMBER> "
|
|
|
|
Execute Hurl file to ENTRY_NUMBER (starting at 1).
|
|
Ignore the remaining of the file. It is useful for debugging a session.
|
|
|
|
.IP "-u, --user <USER:PASSWORD> "
|
|
|
|
Add basic Authentication header to each request.
|
|
|
|
.IP "-A, --user-agent <NAME> "
|
|
|
|
Specify the User-Agent string to send to the HTTP server.
|
|
|
|
.IP "--variable <NAME=VALUE> "
|
|
|
|
Define variable (name/value) to be used in Hurl templates.
|
|
|
|
.IP "--variables-file <FILE> "
|
|
|
|
Set properties file in which your define your variables.
|
|
|
|
Each variable is defined as name=value exactly as with \fI--variable\fP option.
|
|
|
|
Note that defining a variable twice produces an error.
|
|
|
|
.IP "-v, --verbose "
|
|
|
|
Turn on verbose output on standard error stream.
|
|
Useful for debugging.
|
|
|
|
A line starting with '>' means data sent by Hurl.
|
|
A line staring with '<' means data received by Hurl.
|
|
A line starting with '*' means additional info provided by Hurl.
|
|
|
|
If you only want HTTP headers in the output, \fI-i, --include\fP might be the option you're looking for.
|
|
|
|
.IP "--very-verbose "
|
|
|
|
Turn on more verbose output on standard error stream.
|
|
|
|
In contrast to \fI--verbose\fP option, this option outputs the full HTTP body request and response on standard error. In addition, lines starting with '**' are libcurl debug logs.
|
|
|
|
|
|
.IP "-h, --help "
|
|
|
|
Usage help. This lists all current command line options with a short description.
|
|
|
|
.IP "-V, --version "
|
|
|
|
Prints version information
|
|
|
|
.SH ENVIRONMENT
|
|
|
|
Environment variables can only be specified in lowercase.
|
|
|
|
Using an environment variable to set the proxy has the same effect as using the \fI-x, --proxy\fP option.
|
|
|
|
.IP "http_proxy [protocol://]<host>[:port]"
|
|
|
|
Sets the proxy server to use for HTTP.
|
|
|
|
.IP "https_proxy [protocol://]<host>[:port]"
|
|
|
|
Sets the proxy server to use for HTTPS.
|
|
|
|
.IP "all_proxy [protocol://]<host>[:port]"
|
|
|
|
Sets the proxy server to use if no protocol-specific proxy is set.
|
|
|
|
.IP "no_proxy <comma-separated list of hosts>"
|
|
|
|
List of host names that shouldn't go through any proxy.
|
|
|
|
.IP "HURL_name value"
|
|
|
|
Define variable (name/value) to be used in Hurl templates. This is similar than \fI--variable\fP and \fI--variables-file\fP options.
|
|
|
|
.IP "NO_COLOR"
|
|
|
|
When set to a non-empty string, do not colorize output (see \fI--no-color\fP option).
|
|
|
|
.SH EXIT CODES
|
|
|
|
.IP "1"
|
|
|
|
Failed to parse command-line options.
|
|
|
|
.IP "2"
|
|
|
|
Input File Parsing Error.
|
|
|
|
.IP "3"
|
|
|
|
Runtime error (such as failure to connect to host).
|
|
|
|
.IP "4"
|
|
|
|
Assert Error.
|
|
|
|
.SH WWW
|
|
|
|
\fIhttps://hurl.dev\fP
|
|
|
|
|
|
.SH SEE ALSO
|
|
|
|
curl(1) hurlfmt(1)
|
|
|
|
|