diff --git a/sites/hurl.dev/_data/docs.yml b/sites/hurl.dev/_data/docs.yml index 1d1d855..e7ba820 100644 --- a/sites/hurl.dev/_data/docs.yml +++ b/sites/hurl.dev/_data/docs.yml @@ -76,6 +76,13 @@ - title: Testing Set-Cookie Attributes - title: Testing Bytes Content - title: SSL Certificate + - title: Checking Full Body + - title: Reports + items: + - title: HTML Report + - title: JUnit Report + - title: TAP Report + - title: JSON Output - title: Others items: - title: HTTP Version diff --git a/sites/hurl.dev/_docs/asserting-response.md b/sites/hurl.dev/_docs/asserting-response.md index 5bc1c99..dbd874f 100644 --- a/sites/hurl.dev/_docs/asserting-response.md +++ b/sites/hurl.dev/_docs/asserting-response.md @@ -10,13 +10,13 @@ section: File Format Asserts are used to test various properties of an HTTP response. Asserts can be implicits (such as version, status, headers) or explicit within an `[Asserts]` section. The delimiter of the request / response is `HTTP `: -after this delimiter, you'll find the implicit asserts, then an `[Asserts]` section with all the explicits checks. +after this delimiter, you'll find the implicit asserts, then an `[Asserts]` section with all the explicit checks. ```hurl GET https://api/example.org/cats HTTP 200 -Content-Type: application/json; charset=utf-8 # Implicit assert on Content-Type Hedaer +Content-Type: application/json; charset=utf-8 # Implicit assert on Content-Type Header [Asserts] # Explicit asserts section bytes count == 120 header "Content-Type" contains "utf-8" @@ -174,7 +174,7 @@ Predicates consist of a predicate function and a predicate value. Predicate func | Predicate | Description | Example | |--------------------|-------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------| -| __`==`__ | Query and predicate value are equals | `jsonpath "$.book" == "Dune"` | +| __`==`__ | Query and predicate value are equal | `jsonpath "$.book" == "Dune"` | | __`!=`__ | Query and predicate value are different | `jsonpath "$.color" != "red"` | | __`>`__ | Query number is greater than predicate value | `jsonpath "$.year" > 1978` | | __`>=`__ | Query number is greater than or equal to the predicate value | `jsonpath "$.year" >= 1978` | @@ -188,10 +188,11 @@ Predicates consist of a predicate function and a predicate value. Predicate func | __`exists`__ | Query returns a value | `jsonpath "$.book" exists` | | __`isBoolean`__ | Query returns a boolean | `jsonpath "$.succeeded" isBoolean` | | __`isCollection`__ | Query returns a collection | `jsonpath "$.books" isCollection` | -| __`isDate`__ | Query returns a date | `jsonpath "$.publication_date" isDate` | | __`isEmpty`__ | Query returns an empty collection | `jsonpath "$.movies" isEmpty` | | __`isFloat`__ | Query returns a float | `jsonpath "$.height" isFloat` | | __`isInteger`__ | Query returns an integer | `jsonpath "$.count" isInteger` | +| __`isIsoDate`__ | Query string returns a [RFC 3339] date (`YYYY-MM-DDTHH:mm:ss.sssZ`) | `jsonpath "$.publication_date" isIsoDate` | +| __`isNumber`__ | Query returns an integer or a float | `jsonpath "$.count" isNumber` | | __`isString`__ | Query returns a string | `jsonpath "$.name" isString` | @@ -373,7 +374,7 @@ cookie "LSID[Domain]" not exists cookie "LSID[Path]" == "/accounts" cookie "LSID[Secure]" exists cookie "LSID[HttpOnly]" exists -cookie "LSID[SameSite]" equals "Lax" +cookie "LSID[SameSite]" == "Lax" ``` > `Secure` and `HttpOnly` attributes can only be tested with `exists` or `not exists` predicates @@ -663,7 +664,7 @@ certificate "Serial-Number" matches "[0-9af]+" ## Body Optional assertion on the received HTTP response body. Body section can be seen -as syntactic sugar over [body asserts] (with `equals` predicate function). If the +as syntactic sugar over [body asserts] (with `==` predicate). If the body of the response is a [JSON] string or a [XML] string, the body assertion can be directly inserted without any modification. For a text based body that is neither JSON nor XML, one can use multiline string that starts with ``` and ends @@ -840,3 +841,4 @@ of all file nodes. [count]: {% link _docs/filters.md %}#count [`decode` filter]: {% link _docs/filters.md %}#decode [headers implicit asserts]: #headers +[RFC 3339]: https://www.rfc-editor.org/rfc/rfc3339 diff --git a/sites/hurl.dev/_docs/filters.md b/sites/hurl.dev/_docs/filters.md index 75ef99b..21c0859 100644 --- a/sites/hurl.dev/_docs/filters.md +++ b/sites/hurl.dev/_docs/filters.md @@ -9,7 +9,7 @@ section: File Format ## Definition [Captures] and [asserts] share a common structure: query. A query is used to extract data from an HTTP response; this data -can come from the HTTP response body, the HTTP response headers or from the HTTP meta-informations (like `duration` for instance)... +can come from the HTTP response body, the HTTP response headers or from the HTTP meta-information (like `duration` for instance)... In this example, the query __`jsonpath "$.books[0].name"`__ is used in a capture to save data and in an assert to test the HTTP response body. diff --git a/sites/hurl.dev/_docs/frequently-asked-questions.md b/sites/hurl.dev/_docs/frequently-asked-questions.md index 89bc1fa..f78656d 100644 --- a/sites/hurl.dev/_docs/frequently-asked-questions.md +++ b/sites/hurl.dev/_docs/frequently-asked-questions.md @@ -191,10 +191,9 @@ For example, the Hurl file ```hurl GET https://example.org/api/users/1 User-Agent: Custom - -HTTP/1.1 200 +HTTP 200 [Asserts] -jsonpath "$.name" equals "Bob" +jsonpath "$.name" == "Bob" ``` will be converted to JSON with the following command: @@ -215,7 +214,7 @@ $ hurlfmt test.hurl --out json | jq ] }, "response": { - "version": "HTTP/1.1", + "version": "HTTP", "status": 200, "asserts": [ { @@ -224,7 +223,7 @@ $ hurlfmt test.hurl --out json | jq "expr": "$.name" }, "predicate": { - "type": "equal", + "type": "==", "value": "Bob" } } diff --git a/sites/hurl.dev/_docs/grammar.md b/sites/hurl.dev/_docs/grammar.md index c33b76b..1a5ee19 100644 --- a/sites/hurl.dev/_docs/grammar.md +++ b/sites/hurl.dev/_docs/grammar.md @@ -84,10 +84,10 @@ Short description:
assert(used by asserts-section)
lt*
query (sp filter)* sp predicate lt
option(used by options-section)
lt*
-(aws-sigv4-option|ca-certificate-option|client-certificate-option|client-key-option|compressed-option|connect-to-option|delay-option|follow-redirect-option|follow-redirect-trusted-option|http10-option|http11-option|http2-option|http3-option|insecure-option|ipv4-option|ipv6-option|max-redirs-option|netrc-option|netrc-file-option|netrc-optional-option|output-option|path-as-is-option|proxy-option|resolve-option|retry-option|retry-interval-option|skip-option|unix-socket-option|variable-option|verbose-option|very-verbose-option)
+(aws-sigv4-option|ca-certificate-option|client-certificate-option|client-key-option|compressed-option|connect-to-option|delay-option|follow-redirect-option|follow-redirect-trusted-option|http10-option|http11-option|http2-option|http3-option|insecure-option|ipv4-option|ipv6-option|max-redirs-option|netrc-option|netrc-file-option|netrc-optional-option|output-option|path-as-is-option|proxy-option|resolve-option|retry-option|retry-interval-option|skip-option|unix-socket-option|user-option|variable-option|verbose-option|very-verbose-option)
aws-sigv4-option(used by option)
aws-sigv4 : value-string lt
ca-certificate-option(used by option)
cacert : filename lt
-
client-certificate-option(used by option)
cert : value-string lt
+
client-certificate-option(used by option)
cert : filename-password lt
client-key-option(used by option)
key : value-string lt
compressed-option(used by option)
compressed : boolean-option lt
connect-to-option(used by option)
connect-to : value-string lt
@@ -113,6 +113,7 @@ Short description:
retry-interval-option(used by option)
retry-interval : integer-option lt
skip-option(used by option)
skip : boolean-option lt
unix-socket-option(used by option)
unix-socket : value-string lt
+
user-option(used by option)
user : value-string lt
variable-option(used by option)
variable : variable-definition lt
verbose-option(used by option)
verbose : boolean-option lt
very-verbose-option(used by option)
very-verbose : boolean-option lt
@@ -172,13 +173,14 @@ Short description: |boolean-predicate
|string-predicate
|collection-predicate
-|date-predicate -
equal-predicate(used by predicate-func)
(equals|==) sp predicate-value
-
not-equal-predicate(used by predicate-func)
(notEquals|!=) sp predicate-value
-
greater-predicate(used by predicate-func)
(greaterThan|>) sp (number|quoted-string)
-
greater-or-equal-predicate(used by predicate-func)
(greaterThanOrEquals|>=) sp sp* (number|quoted-string)
-
less-predicate(used by predicate-func)
(lessThan|<) sp (number|quoted-string)
-
less-or-equal-predicate(used by predicate-func)
(lessThanOrEquals|<=) sp (number|quoted-string)
+|date-predicate
+|iso-date-predicate +
equal-predicate(used by predicate-func)
== sp predicate-value
+
not-equal-predicate(used by predicate-func)
!= sp predicate-value
+
greater-predicate(used by predicate-func)
> sp (number|quoted-string)
+
greater-or-equal-predicate(used by predicate-func)
>= sp sp* (number|quoted-string)
+
less-predicate(used by predicate-func)
< sp (number|quoted-string)
+
less-or-equal-predicate(used by predicate-func)
<= sp (number|quoted-string)
start-with-predicate(used by predicate-func)
startsWith sp (quoted-string|oneline-hex|oneline-base64)
end-with-predicate(used by predicate-func)
endsWith sp (quoted-string|oneline-hex|oneline-base64)
contain-predicate(used by predicate-func)
contains sp quoted-string
@@ -192,6 +194,7 @@ Short description:
string-predicate(used by predicate-func)
isString
collection-predicate(used by predicate-func)
isCollection
date-predicate(used by predicate-func)
isDate
+
iso-date-predicate(used by predicate-func)
isIsoDate
predicate-value(used by equal-predicate, not-equal-predicate, include-predicate)
 boolean
|multiline-string
|null
@@ -220,7 +223,7 @@ Short description:
key-string-content(used by key-string)
(key-string-text|key-string-escaped-char)*
key-string-text(used by key-string-content)
(alphanum|_|-|.|[|]|@|$)+
key-string-escaped-char(used by key-string-content)
\ (#|:|\|\b|\f|\n|\r|\t|\u unicode-char)
-
value-string(used by request, key-value, aws-sigv4-option, client-certificate-option, client-key-option, connect-to-option, netrc-file-option, output-option, proxy-option, resolve-option, unix-socket-option)
(value-string-content|template)*
+
value-string(used by request, key-value, aws-sigv4-option, client-key-option, connect-to-option, netrc-file-option, output-option, proxy-option, resolve-option, unix-socket-option, user-option)
(value-string-content|template)*
value-string-content(used by value-string)
(value-string-text|value-string-escaped-char)*
value-string-text(used by value-string-content)
~[#\n\\]+
value-string-escaped-char(used by value-string-content)
\ (#|\|\b|\f|\n|\r|\t|\u unicode-char)
@@ -241,9 +244,13 @@ Short description:
multiline-string-escaped-char(used by multiline-string-content)
\ (\|b|f|n|r|t|`|u unicode-char)
filename(used by file-value, ca-certificate-option, oneline-file)
(filename-content|template)*
filename-content(used by filename)
(filename-text|filename-escaped-char)*
-
filename-text(used by filename-content)
~[#; \n\\]+
-
filename-escaped-char(used by filename-content)
\ (;|#|[ ])
-
unicode-char(used by quoted-string-escaped-char, key-string-escaped-char, value-string-escaped-char, oneline-string-escaped-char, multiline-string-escaped-char)
{ hexdigit+ }
+
filename-text(used by filename-content)
~[#;{} \n\\]+
+
filename-escaped-char(used by filename-content)
\ (\|b|f|n|r|t|#|;| |{|}|u unicode-char)
+
filename-password(used by client-certificate-option)
(filename-password-content|template)*
+
filename-password-content(used by filename-password)
(filename-password-text|filename-password-escaped-char)*
+
filename-password-text(used by filename-password-content)
~[#;{} \n\\]+
+
filename-password-escaped-char(used by filename-password-content)
\ (\|b|f|n|r|t|#|;| |{|}|:|u unicode-char)
+
unicode-char(used by quoted-string-escaped-char, key-string-escaped-char, value-string-escaped-char, oneline-string-escaped-char, multiline-string-escaped-char, filename-escaped-char, filename-password-escaped-char)
{ hexdigit+ }

JSON

json-value(used by bytes, json-key-value, json-array)
 template
|json-object
|json-array
@@ -259,7 +266,7 @@ Short description:
json-string-text(used by json-string-content)
~["\\]
json-string-escaped-char(used by json-string-content)
\ ("|\|b|f|n|r|t|u hexdigit hexdigit hexdigit hexdigit)
json-number(used by json-value)
integer fraction? exponent?
-

Template / Expression

template(used by boolean-option, integer-option, predicate-value, quoted-string, key-string, value-string, oneline-string, multiline-string, filename, json-value, json-string)
{{ expr }}
+

Template / Expression

template(used by boolean-option, integer-option, predicate-value, quoted-string, key-string, value-string, oneline-string, multiline-string, filename, filename-password, json-value, json-string)
{{ expr }}
expr(used by template)
variable-name (sp filter)*
variable-name(used by variable-definition, expr)
[A-Za-z] [A-Za-z_-0-9]*

Filter

filter(used by capture, assert, expr)
 count-filter
@@ -307,7 +314,7 @@ Short description:
fraction(used by json-number, float)
. digit+
exponent(used by json-number)
(e|E) (+|-)? digit+
sp(used by request, response, capture, assert, header-query, certificate-query, cookie-query, xpath-query, jsonpath-query, regex-query, variable-query, predicate, equal-predicate, not-equal-predicate, greater-predicate, greater-or-equal-predicate, less-predicate, less-or-equal-predicate, start-with-predicate, end-with-predicate, contain-predicate, match-predicate, include-predicate, expr, jsonpath-filter, nth-filter, regex-filter, replace-filter, split-filter, xpath-filter, lt)
[ \t]
-
lt(used by hurl-file, request, response, header, body, query-string-params-section, form-params-section, multipart-form-data-section, cookies-section, captures-section, asserts-section, basic-auth-section, options-section, file-param, capture, assert, option, aws-sigv4-option, ca-certificate-option, client-certificate-option, client-key-option, compressed-option, connect-to-option, delay-option, follow-redirect-option, follow-redirect-trusted-option, http10-option, http11-option, http2-option, http3-option, insecure-option, ipv4-option, ipv6-option, max-redirs-option, netrc-option, netrc-file-option, netrc-optional-option, output-option, path-as-is-option, proxy-option, resolve-option, retry-option, retry-interval-option, skip-option, unix-socket-option, variable-option, verbose-option, very-verbose-option, multiline-string)
sp* comment? [\n]?
+
lt(used by hurl-file, request, response, header, body, query-string-params-section, form-params-section, multipart-form-data-section, cookies-section, captures-section, asserts-section, basic-auth-section, options-section, file-param, capture, assert, option, aws-sigv4-option, ca-certificate-option, client-certificate-option, client-key-option, compressed-option, connect-to-option, delay-option, follow-redirect-option, follow-redirect-trusted-option, http10-option, http11-option, http2-option, http3-option, insecure-option, ipv4-option, ipv6-option, max-redirs-option, netrc-option, netrc-file-option, netrc-optional-option, output-option, path-as-is-option, proxy-option, resolve-option, retry-option, retry-interval-option, skip-option, unix-socket-option, user-option, variable-option, verbose-option, very-verbose-option, multiline-string)
sp* comment? [\n]?
comment(used by lt)
# ~[\n]*
regex(used by regex-query, match-predicate, regex-filter, replace-filter)
/ regex-content /
regex-content(used by regex)
(regex-text|regex-escaped-char)*
diff --git a/sites/hurl.dev/_docs/manual.md b/sites/hurl.dev/_docs/manual.md index aee2358..fd82ea5 100644 --- a/sites/hurl.dev/_docs/manual.md +++ b/sites/hurl.dev/_docs/manual.md @@ -133,7 +133,8 @@ More information on asserts can be found here [https://hurl.dev/docs/asserting-r Options that exist in curl have exactly the same semantics. -Options specified on the command line are defined for every Hurl file's entry. +Options specified on the command line are defined for every Hurl file's entry, +except if they are tagged as cli-only (can not be defined in the Hurl request [Options] entry) For instance: @@ -155,62 +156,69 @@ HTTP 200 will follow a redirection only for the second entry. -| Option | Description | -|-------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| --aws-sigv4 <PROVIDER1[:PROVIDER2[:REGION[:SERVICE]]]> | Generate an `Authorization` header with an AWS SigV4 signature.

Use [`-u, --user`](#user) to specify Access Key Id (username) and Secret Key (password).

To use temporary session credentials (e.g. for an AWS IAM Role), add the `X-Amz-Security-Token` header containing the session token.
| -| --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.
| -| -E, --cert <CERTIFICATE[:PASSWORD]> | Client certificate file and password.

See also [`--key`](#key).
| -| --color | Colorize debug output (the HTTP response output is not colorized).
| -| --compressed | Request a compressed response using one of the algorithms br, gzip, deflate and automatically decompress the content.
| -| --connect-timeout <SECONDS> | Maximum time in seconds that you allow Hurl's connection to take.

See also [`-m, --max-time`](#max-time).
| -| --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 [`--resolve`](#resolve).
| -| --continue-on-error | 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.
| -| -b, --cookie <FILE> | Read cookies from FILE (using the Netscape cookie file format).

Combined with [`-c, --cookie-jar`](#cookie-jar), you can simulate a cookie storage between successive Hurl runs.
| -| -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 [`-b, --cookie`](#cookie), you can simulate a cookie storage between successive Hurl runs.
| -| --delay <MILLISECONDS> | Sets delay before each request.
| -| --error-format <FORMAT> | Control the format of error message (short by default or long)
| -| --file-root <DIR> | Set root directory to import files in Hurl. This is used for files in multipart form data, request body and response output.
When it is not explicitly defined, files are relative to the current directory in which Hurl is running.
| -| --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.
| -| -0, --http1.0 | Tells Hurl to use HTTP version 1.0 instead of using its internally preferred HTTP version.
| -| --http1.1 | Tells Hurl to use HTTP version 1.1.
| -| --http2 | Tells Hurl to use HTTP version 2.
For HTTPS, this means Hurl negotiates HTTP/2 in the TLS handshake. Hurl does this by default.
For HTTP, this means Hurl attempts to upgrade the request to HTTP/2 using the Upgrade: request header.
| -| --http3 | Tells Hurl to try HTTP/3 to the host in the URL, but fallback to earlier HTTP versions if the HTTP/3 connection establishment fails. HTTP/3 is only available for HTTPS and not for HTTP URLs.
| -| --ignore-asserts | Ignore all asserts defined in the Hurl file.
| -| -i, --include | Include the HTTP headers in the output
| -| -k, --insecure | This option explicitly allows Hurl to perform "insecure" SSL connections and transfers.
| -| --interactive | Stop between requests.

This is similar to a break point, You can then continue (Press C) or quit (Press Q).
| -| -4, --ipv4 | This option tells Hurl to use IPv4 addresses only when resolving host names, and not for example try IPv6.
| -| -6, --ipv6 | This option tells Hurl to use IPv6 addresses only when resolving host names, and not for example try IPv4.
| -| --json | Output each Hurl file result to JSON. The format is very closed to HAR format.
| -| --key <KEY> | Private key file name.
| -| -L, --location | Follow redirect. To limit the amount of redirects to follow use the [`--max-redirs`](#max-redirs) option
| -| --location-trusted | Like [`-L, --location`](#location), but allows sending the name + password to all hosts that the site may redirect to.
This may or may not introduce a security breach if the site redirects you to a site to which you send your authentication info (which is plaintext in the case of HTTP Basic authentication).
| -| --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.
| -| -m, --max-time <SECONDS> | Maximum time in seconds that you allow a request/response to take. This is the standard timeout.

See also [`--connect-timeout`](#connect-timeout).
| -| --no-color | Do not colorize output.
| -| --no-output | Suppress output. By default, Hurl outputs the body of the last response.
| -| --noproxy <HOST(S)> | Comma-separated list of hosts which do not use a proxy.

Override value from Environment variable no_proxy.
| -| -o, --output <FILE> | Write output to FILE instead of stdout.
| -| --path-as-is | Tell Hurl to not handle sequences of /../ or /./ in the given URL path. Normally Hurl will squash or merge them according to standards but with this option set you tell it not to do that.
| -| -x, --proxy <[PROTOCOL://]HOST[:PORT]> | Use the specified proxy.
| -| --report-html <DIR> | Generate HTML report in DIR.

If the HTML report already exists, it will be updated with the new test results.
| -| --report-junit <FILE> | Generate JUnit File.

If the FILE report already exists, it will be updated with the new test results.
| -| --report-tap <FILE> | Generate TAP report.

If the FILE report already exists, it will be updated with the new test results.
| -| --resolve <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.
| -| --retry <NUM> | Maximum number of retries, 0 for no retries, -1 for unlimited retries. Retry happens if any error occurs (asserts, captures, runtimes etc...).
| -| --retry-interval <MILLISECONDS> | Duration in milliseconds between each retry. Default is 1000 ms.
| -| --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.
| -| --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.
| -| --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.
| -| --unix-socket <PATH> | (HTTP) Connect through this Unix domain socket, instead of using the network.
| -| -u, --user <USER:PASSWORD> | Add basic Authentication header to each request.
| -| -A, --user-agent <NAME> | Specify the User-Agent string to send to the HTTP server.
| -| --variable <NAME=VALUE> | Define variable (name/value) to be used in Hurl templates.
| -| --variables-file <FILE> | Set properties file in which your define your variables.

Each variable is defined as name=value exactly as with [`--variable`](#variable) option.

Note that defining a variable twice produces an error.
| -| -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, [`-i, --include`](#include) might be the option you're looking for.
| -| --very-verbose | Turn on more verbose output on standard error stream.

In contrast to [`--verbose`](#verbose) option, this option outputs the full HTTP body request and response on standard error. In addition, lines starting with '**' are libcurl debug logs.
| -| -h, --help | Usage help. This lists all current command line options with a short description.
| -| -V, --version | Prints version information
| +| Option | Description | +|-------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| --aws-sigv4 <PROVIDER1[:PROVIDER2[:REGION[:SERVICE]]]> | Generate an `Authorization` header with an AWS SigV4 signature.

Use [`-u, --user`](#user) to specify Access Key Id (username) and Secret Key (password).

To use temporary session credentials (e.g. for an AWS IAM Role), add the `X-Amz-Security-Token` header containing the session token.
| +| --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.
| +| -E, --cert <CERTIFICATE[:PASSWORD]> | Client certificate file and password.

See also [`--key`](#key).
| +| --color | Colorize debug output (the HTTP response output is not colorized).

This is a cli-only option.
| +| --compressed | Request a compressed response using one of the algorithms br, gzip, deflate and automatically decompress the content.
| +| --connect-timeout <SECONDS> | Maximum time in seconds that you allow Hurl's connection to take.

See also [`-m, --max-time`](#max-time).
| +| --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 [`--resolve`](#resolve).
| +| --continue-on-error | 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.

This is a cli-only option.
| +| -b, --cookie <FILE> | Read cookies from FILE (using the Netscape cookie file format).

Combined with [`-c, --cookie-jar`](#cookie-jar), you can simulate a cookie storage between successive Hurl runs.

This is a cli-only option.
| +| -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 [`-b, --cookie`](#cookie), you can simulate a cookie storage between successive Hurl runs.

This is a cli-only option.
| +| --delay <MILLISECONDS> | Sets delay before each request.
| +| --error-format <FORMAT> | Control the format of error message (short by default or long)

This is a cli-only option.
| +| --file-root <DIR> | Set root directory to import files in Hurl. This is used for files in multipart form data, request body and response output.
When it is not explicitly defined, files are relative to the Hurl file's directory.

This is a cli-only option.
| +| --from-entry <ENTRY_NUMBER> | Execute Hurl file from ENTRY_NUMBER (starting at 1).

This is a cli-only option.
| +| --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.

This is a cli-only option.
| +| -0, --http1.0 | Tells Hurl to use HTTP version 1.0 instead of using its internally preferred HTTP version.
| +| --http1.1 | Tells Hurl to use HTTP version 1.1.
| +| --http2 | Tells Hurl to use HTTP version 2.
For HTTPS, this means Hurl negotiates HTTP/2 in the TLS handshake. Hurl does this by default.
For HTTP, this means Hurl attempts to upgrade the request to HTTP/2 using the Upgrade: request header.
| +| --http3 | Tells Hurl to try HTTP/3 to the host in the URL, but fallback to earlier HTTP versions if the HTTP/3 connection establishment fails. HTTP/3 is only available for HTTPS and not for HTTP URLs.
| +| --ignore-asserts | Ignore all asserts defined in the Hurl file.

This is a cli-only option.
| +| -i, --include | Include the HTTP headers in the output

This is a cli-only option.
| +| -k, --insecure | This option explicitly allows Hurl to perform "insecure" SSL connections and transfers.
| +| --interactive | Stop between requests.

This is similar to a break point, You can then continue (Press C) or quit (Press Q).

This is a cli-only option.
| +| -4, --ipv4 | This option tells Hurl to use IPv4 addresses only when resolving host names, and not for example try IPv6.
| +| -6, --ipv6 | This option tells Hurl to use IPv6 addresses only when resolving host names, and not for example try IPv4.
| +| --jobs <NUM> | (Experimental) Maximum number of parallel jobs in parallel mode. Default value corresponds (in most cases) to the
current amount of CPUs.

See also [`--parallel`](#parallel).

This is a cli-only option.
| +| --json | Output each Hurl file result to JSON. The format is very closed to HAR format.

This is a cli-only option.
| +| --key <KEY> | Private key file name.
| +| -L, --location | Follow redirect. To limit the amount of redirects to follow use the [`--max-redirs`](#max-redirs) option
| +| --location-trusted | Like [`-L, --location`](#location), but allows sending the name + password to all hosts that the site may redirect to.
This may or may not introduce a security breach if the site redirects you to a site to which you send your authentication info (which is plaintext in the case of HTTP Basic authentication).
| +| --max-filesize <BYTES> | Specify the maximum size (in bytes) of a file to download. If the file requested is larger than this value, the transfer does not start.

This is a cli-only option.
| +| --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.
| +| -m, --max-time <SECONDS> | Maximum time in seconds that you allow a request/response to take. This is the standard timeout.

See also [`--connect-timeout`](#connect-timeout).

This is a cli-only option.
| +| -n, --netrc | Scan the .netrc file in the user's home directory for the username and password.

See also [`--netrc-file`](#netrc-file) and [`--netrc-optional`](#netrc-optional).
| +| --netrc-file <FILE> | Like [`--netrc`](#netrc), but provide the path to the netrc file.

See also [`--netrc-optional`](#netrc-optional).
| +| --netrc-optional | Similar to [`--netrc`](#netrc), but make the .netrc usage optional.

See also [`--netrc-file`](#netrc-file).
| +| --no-color | Do not colorize output.

This is a cli-only option.
| +| --no-output | Suppress output. By default, Hurl outputs the body of the last response.

This is a cli-only option.
| +| --noproxy <HOST(S)> | Comma-separated list of hosts which do not use a proxy.

Override value from Environment variable no_proxy.
| +| -o, --output <FILE> | Write output to FILE instead of stdout.
| +| --parallel | (Experimental) Run files in parallel.

Each Hurl file is executed in its own worker thread, without sharing anything with the other workers. The default run mode is sequential.

See also [`--jobs`](#jobs).

This is a cli-only option.
| +| --path-as-is | Tell Hurl to not handle sequences of /../ or /./ in the given URL path. Normally Hurl will squash or merge them according to standards but with this option set you tell it not to do that.
| +| -x, --proxy <[PROTOCOL://]HOST[:PORT]> | Use the specified proxy.
| +| --report-html <DIR> | Generate HTML report in DIR.

If the HTML report already exists, it will be updated with the new test results.

This is a cli-only option.
| +| --report-junit <FILE> | Generate JUnit File.

If the FILE report already exists, it will be updated with the new test results.

This is a cli-only option.
| +| --report-tap <FILE> | Generate TAP report.

If the FILE report already exists, it will be updated with the new test results.

This is a cli-only option.
| +| --resolve <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.
| +| --retry <NUM> | Maximum number of retries, 0 for no retries, -1 for unlimited retries. Retry happens if any error occurs (asserts, captures, runtimes etc...).
| +| --retry-interval <MILLISECONDS> | Duration in milliseconds between each retry. Default is 1000 ms.
| +| --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.

This is a cli-only option.
| +| --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.

This is a cli-only option.
| +| --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.

This is a cli-only option.
| +| --unix-socket <PATH> | (HTTP) Connect through this Unix domain socket, instead of using the network.
| +| -u, --user <USER:PASSWORD> | Add basic Authentication header to each request.
| +| -A, --user-agent <NAME> | Specify the User-Agent string to send to the HTTP server.

This is a cli-only option.
| +| --variable <NAME=VALUE> | Define variable (name/value) to be used in Hurl templates.
| +| --variables-file <FILE> | Set properties file in which your define your variables.

Each variable is defined as name=value exactly as with [`--variable`](#variable) option.

Note that defining a variable twice produces an error.

This is a cli-only option.
| +| -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, [`-i, --include`](#include) might be the option you're looking for.
| +| --very-verbose | Turn on more verbose output on standard error stream.

In contrast to [`--verbose`](#verbose) option, this option outputs the full HTTP body request and response on standard error. In addition, lines starting with '**' are libcurl debug logs.
| +| -h, --help | Usage help. This lists all current command line options with a short description.
| +| -V, --version | Prints version information
| ## Environment diff --git a/sites/hurl.dev/_docs/request.md b/sites/hurl.dev/_docs/request.md index 98b0a74..54344af 100644 --- a/sites/hurl.dev/_docs/request.md +++ b/sites/hurl.dev/_docs/request.md @@ -668,6 +668,7 @@ output: out.html # dump the response to this file path-as-is: true # do not handle sequences of /../ or /./ in URL path skip: false # skip this request unix-socket: sock # use Unix socket for transfer +user: bob=secret # use basic authentication variable: country=Italy # define variable country variable: planet=Earth # define variable planet verbose: true # allow verbose output diff --git a/sites/hurl.dev/_docs/samples.md b/sites/hurl.dev/_docs/samples.md index ac2a5ad..3445d58 100644 --- a/sites/hurl.dev/_docs/samples.md +++ b/sites/hurl.dev/_docs/samples.md @@ -24,6 +24,18 @@ oriented output, you can use [`--test` option]: $ hurl --test sample.hurl ``` +A particular response can be saved with [`[Options] section`][option]: + +```hurl +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. @@ -35,6 +47,15 @@ A simple GET: GET https://example.org ``` +Requests can be chained: + +```hurl +GET https://example.org/a +GET https://example.org/b +HEAD https://example.org/c +GET https://example.org/c +``` + [Doc]({% link _docs/request.md %}#method) ### HTTP Headers @@ -68,6 +89,8 @@ 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]({% link _docs/request.md %}#query-parameters) ### Basic Authentication @@ -88,9 +111,45 @@ GET https://example.org/protected Authorization: Basic Ym9iOnNlY3JldA== ``` -Basic authentication 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]. +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]: + +```shell +$ hurl --user bob=secret login.hurl +``` + +[`--user`] option can also be set per request: + +```hurl +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: + +{% raw %} +```hurl +POST https://sample.org/orders +HTTP 201 +[Captures] +order_id: jsonpath "$.order.id" + +GET https://sample.org/orders/{{order_id}} +HTTP 200 +``` +{% endraw %} + + +[Doc]({% link _docs/capturing-response.md %}) ## Sending Data @@ -280,6 +339,44 @@ GraphQL queries can also use [Hurl templates]. ## Testing Response +Responses are optional, everything after `HTTP` is part of the response asserts. + +```hurl +# A request with (almost) no check: +GET https://foo.com + +# A status code check: +GET https://foo.com +HTTP 200 + +# A test on response body +GET https://foo.com +HTTP 200 +[Asserts] +jsonpath "$.state" == "running" +``` + +### Testing Status Code + +```hurl +GET https://example.org/order/435 +HTTP 200 +``` + +[Doc]({% link _docs/asserting-response.md %}#version-status) + +```hurl +GET https://example.org/order/435 +# Testing status code is in a 200-300 range +HTTP * +[Asserts] +status >= 200 +status < 300 +``` + +[Doc]({% link _docs/asserting-response.md %}#status-assert) + + ### Testing Response Headers Use implicit response asserts to test header values: @@ -305,6 +402,16 @@ header "Location" contains "www.example.net" [Doc]({% link _docs/asserting-response.md %}#header-assert) +Implicit and explicit asserts can be combined: + +```hurl +GET https://example.org/index.html +HTTP 200 +Set-Cookie: theme=light +Set-Cookie: sessionToken=abc123; Expires=Wed, 09 Jun 2021 10:18:14 GMT +[Asserts] +header "Location" contains "www.example.net" +``` ### Testing REST APIs @@ -323,32 +430,12 @@ jsonpath "$.links" count == 12 jsonpath "$.state" != null jsonpath "$.order" matches "^order-\\d{8}$" jsonpath "$.order" matches /^order-\d{8}$/ # Alternative syntax with regex literal +jsonpath "$.created" isIsoDate ``` [Doc]({% link _docs/asserting-response.md %}#jsonpath-assert) -Testing status code: - -```hurl -GET https://example.org/order/435 -HTTP 200 -``` - -[Doc]({% link _docs/asserting-response.md %}#version-status) - -```hurl -GET https://example.org/order/435 -# Testing status code is in a 200-300 range -HTTP * -[Asserts] -status >= 200 -status < 300 -``` - -[Doc]({% link _docs/asserting-response.md %}#status-assert) - - ### Testing HTML Response ```hurl @@ -411,16 +498,141 @@ certificate "Serial-Number" matches /[\da-f]+/ [Doc]({% link _docs/asserting-response.md %}#ssl-certificate-assert) +### Checking Full Body + +Use implicit body to test an exact JSON body match: + +```hurl +GET https://example.org/api/cats/123 +HTTP 200 +{ + "name" : "Purrsloud", + "species" : "Cat", + "favFoods" : ["wet food", "dry food", "any food"], + "birthYear" : 2016, + "photo" : "https://learnwebcode.github.io/json-example/images/cat-2.jpg" +} +``` + +[Doc]({% link _docs/asserting-response.md %}#json-body) + +Or an explicit assert file: + +```hurl +GET https://example.org/index.html +HTTP 200 +[Asserts] +body == file,cat.json; +``` + +[Doc]({% link _docs/asserting-response.md %}#body-assert) + +Implicit asserts supports XML body: + +```hurl +GET https://example.org/api/catalog +HTTP 200 + + + + Gambardella, Matthew + XML Developer's Guide + Computer + 44.95 + 2000-10-01 + An in-depth look at creating applications with XML. + + +``` + +[Doc]({% link _docs/asserting-response.md %}#xml-body) + +Plain text: + +~~~hurl +GET https://example.org/models +HTTP 200 +``` +Year,Make,Model,Description,Price +1997,Ford,E350,"ac, abs, moon",3000.00 +1999,Chevy,"Venture ""Extended Edition""","",4900.00 +1999,Chevy,"Venture ""Extended Edition, Very Large""",,5000.00 +1996,Jeep,Grand Cherokee,"MUST SELL! air, moon roof, loaded",4799.00 +``` +~~~ + +[Doc]({% link _docs/asserting-response.md %}#multiline-string-body) + + +One line: + +```hurl +POST https://example.org/helloworld +HTTP 200 +`Hello world!` +``` + +[Doc]({% link _docs/asserting-response.md %}#oneline-string-body) + +File: + +```hurl +GET https://example.org +HTTP 200 +file,data.bin; +``` + +[Doc]({% link _docs/asserting-response.md %}#file-body) + + +## Reports + +### HTML Report + +```shell +$ hurl --test --report-html build/report/ *.hurl +``` + +[Doc]({% link _docs/running-tests.md %}#generating-report) + +### JUnit Report + +```shell +$ hurl --test --report-junit build/report.xml *.hurl +``` + +[Doc]({% link _docs/running-tests.md %}#generating-report) + +### TAP Report + +```shell +$ hurl --test --report-tap build/report.txt *.hurl +``` + +[Doc]({% link _docs/running-tests.md %}#generating-report) + +### JSON Output + +A structured output of running Hurl files can be obtained with [`--json` option]. Each file will produce a JSON export of the run. + + +```shell +$ hurl --json *.hurl +``` + ## Others ### HTTP Version -Testing HTTP version (1.0, 1.1, 2 or 3): +Testing HTTP version (HTTP/1.0, HTTP/1.1, HTTP/2 or HTTP/3): ```hurl -GET https://example.org/order/435 +GET https://foo.com HTTP/3 200 + +GET https://bar.com +HTTP/2 200 ``` [Doc]({% link _docs/asserting-response.md %}#version-status) @@ -474,7 +686,7 @@ HTTP 200 ### Skipping Requests ```hurl -# a, b, d are runner, c is skipped +# a, c, d are run, b is skipped GET https://example.org/a GET https://example.org/b @@ -563,7 +775,17 @@ Action: GetCallerIdentity Version: 2011-06-15 ``` -The Access Key is given per [`--user`]. +The Access Key is given per [`--user`], either with command line option or within the [`[Options]`][option] section: + +```hurl +POST https://sts.eu-central-1.amazonaws.com/ +[Options] +aws-sigv4: aws:amz:eu-central-1:sts +user: bob=secret +[FormParams] +Action: GetCallerIdentity +Version: 2011-06-15 +``` [Doc]({% link _docs/manual.md %}#aws-sigv4) @@ -585,3 +807,6 @@ The Access Key is given per [`--user`]. [`--user`]: {% link _docs/manual.md %}#user [Hurl templates]: {% link _docs/templates.md %} [AWS Signature Version 4]: https://docs.aws.amazon.com/AmazonS3/latest/API/sig-v4-authenticating-requests.html +[Captures]: {% link _docs/capturing-response.md %} +[option]: {% link _docs/request.md %}#options +[`--json` option]: {% link _docs/manual.md %}#json diff --git a/sites/hurl.dev/_docs/tutorial/debug-tips.md b/sites/hurl.dev/_docs/tutorial/debug-tips.md index 84d8e32..43fb802 100644 --- a/sites/hurl.dev/_docs/tutorial/debug-tips.md +++ b/sites/hurl.dev/_docs/tutorial/debug-tips.md @@ -83,6 +83,16 @@ $ hurl --verbose --no-output basic.hurl Lines beginning with `*` are debug info, lines that begin with `>` are HTTP request headers and lines that begin with `<` are HTTP response headers. +In each run request, we can also see a curl command line to replay this particular request: + +```shell +... +* Request can be run with the following curl command: +* curl --cookie 'x-session-id=s%3AEE3wsnrgUPSyAkgJZGa3jMWk7xmOtv4E.kXQpkmNBXnFOqmeSssqXnecF4qqv1D7bKu3rpbEJxmQ' 'http://localhost:3000/not-found' +... +``` + + In verbose mode, HTTP request and response bodies are not displayed in the debug logs. If you need to inspect the request or response body, you can display more logs with [`--very-verbose`] option: diff --git a/sites/linux/hurlfmt b/sites/linux/hurlfmt index ace8e10..e5febe5 100755 Binary files a/sites/linux/hurlfmt and b/sites/linux/hurlfmt differ diff --git a/sites/macos/hurlfmt b/sites/macos/hurlfmt index a673b27..4b28eaf 100755 Binary files a/sites/macos/hurlfmt and b/sites/macos/hurlfmt differ