``` The following assert will check the value of the `data-visible` attribute: ```hurl GET https://example.org/home HTTP 200 [Asserts] xpath "string(//article/@data-visible)" == "true" ``` In this case, the XPath query `string(//article/@data-visible)` returns a string, so the predicate value must be a string. The predicate function `==` can be used with string, numbers or booleans; `startWith` and `contains` can only be used with strings and bytes, while `matches` only works on string. If a query returns a number, using a `matches` predicate will cause a runner error. ```hurl # A really well tested web page... GET https://example.org/home HTTP 200 [Asserts] header "Content-Type" contains "text/html" header "Last-Modified" == "Wed, 21 Oct 2015 07:28:00 GMT" xpath "//h1" exists # Check we've at least one h1 xpath "normalize-space(//h1)" contains "Welcome" xpath "//h2" count == 13 xpath "string(//article/@data-id)" startsWith "electric" ``` ### Status assert Check the received HTTP response status code. Status assert consists of the keyword `status` followed by a predicate function and value. ```hurl GET https://example.org HTTP * [Asserts] status < 300 ``` ### Version assert Check the received HTTP version. Version assert consists of the keyword `version` followed by a predicate function and value. The value returns by `version` is a string: ```hurl GET https://example.org HTTP * [Asserts] version == "2" ``` ### Header assert Check the value of a received HTTP response header. Header assert consists of the keyword `header` followed by the value of the header, a predicate function and a predicate value. Like [headers implicit asserts], the check is case-insensitive for the name: comparing a `Content-Type` header is equivalent to a `content-type` one. ```hurl GET https://example.org HTTP 302 [Asserts] header "Location" contains "www.example.net" header "Last-Modified" matches /\d{2} [a-z-A-Z]{3} \d{4}/ ``` If there are multiple headers with the same name, the header assert returns a collection, so `count`, `contains` can be used in this case to test the header list. Let's say we have this request and response: ``` > GET /hello HTTP/1.1 > Host: example.org > Accept: */* > User-Agent: hurl/2.0.0-SNAPSHOT > * Response: (received 12 bytes in 11 ms) * < HTTP/1.0 200 OK < Vary: Content-Type < Vary: User-Agent < Content-Type: text/html; charset=utf-8 < Content-Length: 12 < Server: Flask Server < Date: Fri, 07 Oct 2022 20:53:35 GMT ``` One can use explicit header asserts: ```hurl GET https://example.org/hello HTTP 200 [Asserts] header "Vary" count == 2 header "Vary" contains "User-Agent" header "Vary" contains "Content-Type" ``` Or implicit header asserts: ```hurl GET https://example.org/hello HTTP 200 Vary: User-Agent Vary: Content-Type ``` ### Cookie assert Check value or attributes of a [`Set-Cookie`] response header. Cookie assert consists of the keyword `cookie`, followed by the cookie name (and optionally a cookie attribute), a predicate function and value. Cookie attributes value can be checked by using the following format:`[cookie-attribute]`. The following attributes are supported: `Value`, `Expires`, `Max-Age`, `Domain`, `Path`, `Secure`, `HttpOnly` and `SameSite`. ```hurl GET http://localhost:8000/cookies/set HTTP 200 # Explicit check of Set-Cookie header value. If the attributes are # not in this exact order, this assert will fail. Set-Cookie: LSID=DQAAAKEaem_vYg; Expires=Wed, 13 Jan 2021 22:23:01 GMT; Secure; HttpOnly; Path=/accounts; SameSite=Lax; Set-Cookie: HSID=AYQEVnDKrdst; Domain=localhost; Expires=Wed, 13 Jan 2021 22:23:01 GMT; HttpOnly; Path=/ Set-Cookie: SSID=Ap4PGTEq; Domain=localhost; Expires=Wed, 13 Jan 2021 22:23:01 GMT; Secure; HttpOnly; Path=/ # Using cookie assert, one can check cookie value and various attributes. [Asserts] cookie "LSID" == "DQAAAKEaem_vYg" cookie "LSID[Value]" == "DQAAAKEaem_vYg" cookie "LSID[Expires]" exists cookie "LSID[Expires]" contains "Wed, 13 Jan 2021" cookie "LSID[Max-Age]" not exists cookie "LSID[Domain]" not exists cookie "LSID[Path]" == "/accounts" cookie "LSID[Secure]" exists cookie "LSID[HttpOnly]" exists cookie "LSID[SameSite]" == "Lax" ``` > `Secure` and `HttpOnly` attributes can only be tested with `exists` or `not exists` predicates > to reflect the [Set-Cookie header] semantics (in other words, queries `[HttpOnly]` > and `[Secure]` don't return boolean). ### Body assert Check the value of the received HTTP response body when decoded as a string. Body assert consists of the keyword `body` followed by a predicate function and value. ```hurl GET https://example.org HTTP 200 [Asserts] body contains "

Welcome!

" ``` The encoding used to decode the response body bytes to a string is based on the `charset` value in the `Content-Type` header response. ```hurl # Our HTML response is encoded with GB 2312 (see https://en.wikipedia.org/wiki/GB_2312) GET https://example.org/cn HTTP 200 [Asserts] header "Content-Type" == "text/html; charset=gb2312" # bytes of the response, without any text decoding: bytes contains hex,c4e3bac3cac0bde7; # 你好世界 encoded in GB 2312 # text of the response, decoded with GB 2312: body contains "你好世界" ``` If the `Content-Type` response header doesn't include any encoding hint, a [`decode` filter] can be used to explicitly decode the response body bytes. ```hurl # Our HTML response is encoded using GB 2312. # But, the 'Content-Type' HTTP response header doesn't precise any charset, # so we decode explicitly the bytes. GET https://example.org/cn HTTP 200 [Asserts] header "Content-Type" == "text/html" bytes contains hex,c4e3bac3cac0bde7; # 你好世界 encoded in GB2312 bytes decode "gb2312" contains "你好世界" ``` Body asserts are automatically decompressed based on the value of `Content-Encoding` response header. So, whatever is the response compression (`gzip`, `brotli`) etc... asserts values don't depend on the content encoding. ```hurl # Request a gzipped reponse, the `body` asserts works with ungzipped response GET https://example.org Accept-Encoding: gzip HTTP 200 [Asserts] header "Content-Encoding" == "gzip" body contains "

Welcome!

" # Without content encoding, asserts remains identical GET https://example.org HTTP 200 [Asserts] header "Content-Encoding" not exists body contains "

Welcome!

" ``` ### Bytes assert Check the value of the received HTTP response body as a bytestream. Body assert consists of the keyword `bytes` followed by a predicate function and value. ```hurl GET https://example.org/data.bin HTTP 200 [Asserts] bytes startsWith hex,efbbbf; bytes count == 12424 header "Content-Length" == "12424" ``` Like `body` assert, `bytes` assert works _after_ content encoding decompression (so the predicates values are not affected by `Content-Encoding` response header value). ### XPath assert Check the value of a [XPath] query on the received HTTP body decoded as a string (using the `charset` value in the `Content-Type` header response). Currently, only XPath 1.0 expression can be used. Body assert consists of the keyword `xpath` followed by a predicate function and value. Values can be string, boolean or number depending on the XPath query. Let's say we want to check this HTML response: ```plain $ curl -v https://example.org < HTTP/1.1 200 OK < Content-Type: text/html; charset=UTF-8 ... Example Domain ...

Example

This domain is for use in illustrative examples in documents. You may use this domain in literature without prior coordination or asking for permission.

More information...

``` With Hurl, we can write multiple XPath asserts describing the DOM content: ```hurl GET https://example.org HTTP 200 Content-Type: text/html; charset=UTF-8 [Asserts] xpath "string(/html/head/title)" contains "Example" # Check title xpath "count(//p)" == 2 # Check the number of

xpath "//p" count == 2 # Similar assert for

xpath "boolean(count(//h2))" == false # Check there is no

xpath "//h2" not exists # Similar assert for

``` XML Namespaces are also supported. Let's say you want to check this XML response: ```xml Cheaper by the Dozen 1568491379 ``` This XML response can be tested with the following Hurl file: ```hurl GET http://localhost:8000/assert-xpath HTTP 200 [Asserts] xpath "string(//bk:book/bk:title)" == "Cheaper by the Dozen" xpath "string(//[name()='bk:book']/[name()='bk:title'])" == "Cheaper by the Dozen" xpath "string(//[local-name()='book']/[local-name()='title'])" == "Cheaper by the Dozen" xpath "string(//bk:book/isbn:number)" == "1568491379" xpath "string(//[name()='bk:book']/[name()='isbn:number'])" == "1568491379" xpath "string(//[local-name()='book']/[local-name()='number'])" == "1568491379" ``` The XPath expressions `string(//bk:book/bk:title)` and `string(//bk:book/isbn:number)` are written with `bk` and `isbn` namespaces. > For convenience, the first default namespace can be used with `_` ### JSONPath assert Check the value of a [JSONPath] query on the received HTTP body decoded as a JSON document. JSONPath assert consists of the keyword `jsonpath` followed by a predicate function and value. Let's say we want to check this JSON response: ```plain curl -v http://httpbin.org/json < HTTP/1.1 200 OK < Content-Type: application/json ... { "slideshow": { "author": "Yours Truly", "date": "date of publication", "slides": [ { "title": "Wake up to WonderWidgets!", "type": "all" }, ... ], "title": "Sample Slide Show" } } ``` With Hurl, we can write multiple JSONPath asserts describing the DOM content: ```hurl GET http://httpbin.org/json HTTP 200 [Asserts] jsonpath "$.slideshow.author" == "Yours Truly" jsonpath "$.slideshow.slides[0].title" contains "Wonder" jsonpath "$.slideshow.slides" count == 2 jsonpath "$.slideshow.date" != null jsonpath "$.slideshow.slides[*].title" contains "Mind Blowing!" ``` > Explain that the value selected by the JSONPath is coerced to a string when only > one node is selected. In `matches` predicates, metacharacters beginning with a backslash (like `\d`, `\s`) must be escaped. Alternatively, `matches` predicate support [JavaScript-like Regular expression syntax] to enhance the readability: ```hurl GET https://example.org/hello HTTP 200 [Asserts] # Predicate value with matches predicate: jsonpath "$.date" matches "^\\d{4}-\\d{2}-\\d{2}$" jsonpath "$.name" matches "Hello [a-zA-Z]+!" # Equivalent syntax: jsonpath "$.date" matches /^\d{4}-\d{2}-\d{2}$/ jsonpath "$.name" matches /Hello [a-zA-Z]+!/ ``` ### Regex assert Check that the HTTP received body, decoded as text, matches a regex pattern. ```hurl GET https://example.org/hello HTTP 200 [Asserts] regex "^(\\d{4}-\\d{2}-\\d{2})$" == "2018-12-31" # Same assert as previous using regex literals regex /^(\d{4}-\d{2}-\d{2})$/ == "2018-12-31" ``` The regex pattern must have at least one capture group, otherwise the assert will fail. The assertion is done on the captured group value. When the regex pattern is a double-quoted string, metacharacters beginning with a backslash in the pattern (like `\d`, `\s`) must be escaped; literal pattern enclosed by `/` can also be used to avoid metacharacters escaping. The regex syntax is documented at . For instance, once can use [flags](https://docs.rs/regex/latest/regex/#grouping-and-flags) to enable case-insensitive match: ```hurl GET https://example.org/hello HTTP 200 [Asserts] regex /(?i)hello (\w+)!/ == "World" ``` ### SHA-256 assert Check response body [SHA-256] hash. ```hurl GET https://example.org/data.tar.gz HTTP 200 [Asserts] sha256 == hex,039058c6f2c0cb492c533b0a4d14ef77cc0f78abccced5287d84a1a2011cfb81; ``` Like `body` assert, `sha256` assert works _after_ content encoding decompression (so the predicates values are not affected by `Content-Encoding` response header). For instance, if we have a resource `a.txt` on a server with a given hash `abcdef`, `sha256` value is not affected by `Content-Encoding`: ```hurl # Without content encoding compression: GET https://example.org/a.txt HTTP 200 [Asserts] sha256 == hex,abcdef; # With content encoding compression: GET https://example.org/a.txt Accept-Encoding: brotli HTTP 200 [Asserts] header "Content-Encoding" == "brotli" sha256 == hex,abcdef; ``` ### MD5 assert Check response body [MD5] hash. ```hurl GET https://example.org/data.tar.gz HTTP 200 [Asserts] md5 == hex,ed076287532e86365e841e92bfc50d8c; ``` Like `sha256` asserts, `md5` assert works _after_ content encoding decompression (so the predicates values are not affected by `Content-Encoding` response header) ### URL assert Check the last fetched URL. This is most meaningful if you have told Hurl to follow redirection (see [`[Options]`section][options] or [`--location` option]). URL assert consists of the keyword `url` followed by a predicate function and value. ```hurl GET https://example.org/redirecting [Options] location: true HTTP 200 [Asserts] url == "https://example.org/redirected" ``` ### Redirects assert Check each step of redirection. This is most meaningful if you have told Hurl to follow redirection (see [`[Options]`section][options] or [`--location` option]). Redirects assert consists of the keyword `redirects` followed by a predicate function and value. The `redirects` query returns a collection of redirections that can be tested with a [`location` filter]: ```hurl GET https://example.org/redirecting/1 [Options] location: true HTTP 200 [Asserts] redirects count == 3 redirects nth 0 location == "https://example.org/redirecting/2" redirects nth 1 location == "https://example.org/redirecting/3" redirects nth 2 location == "https://example.org/redirected" ``` ### IP address assert Check the IP address of the last connection. The value of the `ip` query is a string. > Predicates `isIpv4` and `isIpv6` are available to check if a particular string matches an IPv4 or IPv6 address and > can use with `ip` queries. ```hurl GET https://example.org/hello HTTP 200 [Asserts] ip isIpv4 ip not isIpv6 ip == "172.16.45.87" ``` ### Variable assert ```hurl # Test that the XML endpoint return 200 pets GET https://example.org/api/pets HTTP 200 [Captures] pets: xpath "//pets" [Asserts] variable "pets" count == 200 ``` ### Duration assert Check the total duration (sending plus receiving time) of the HTTP transaction. ```hurl GET https://example.org/helloworld HTTP 200 [Asserts] duration < 1000 # Check that response time is less than one second ``` ### SSL certificate assert Check the SSL certificate properties. Certificate assert consists of the keyword `certificate`, followed by the certificate attribute value. The following attributes are supported: `Subject`, `Issuer`, `Start-Date`, `Expire-Date`, `Serial-Number`, and `Subject-Alt-Name`. ```hurl GET https://example.org HTTP 200 [Asserts] certificate "Subject" == "CN=example.org" certificate "Issuer" == "C=US, O=Let's Encrypt, CN=R3" certificate "Expire-Date" daysAfterNow > 15 certificate "Serial-Number" matches "[0-9af]+" certificate "Subject-Alt-Name" contains "DNS:example.org" certificate "Subject-Alt-Name" split "," count == 2 ``` [predicates]: #predicates [header assert]: #header-assert [captures]: /docs/capturing-response.md#query [data attributes]: https://developer.mozilla.org/en-US/docs/Learn/HTML/Howto/Use_data_attributes [`Set-Cookie`]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Set-Cookie [Set-Cookie header]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Set-Cookie [XPath]: https://en.wikipedia.org/wiki/XPath [JSONPath]: https://goessner.net/articles/JsonPath/ [body asserts]: #body-assert [JSON]: https://www.json.org [XML]: https://en.wikipedia.org/wiki/XML [Base64]: https://en.wikipedia.org/wiki/Base64 [`--file-root` option]: /docs/manual.md#file-root [JavaScript-like Regular expression syntax]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_Expressions [MD5]: https://en.wikipedia.org/wiki/MD5 [SHA-256]: https://en.wikipedia.org/wiki/SHA-2 [options]: /docs/request.md#options [`--location` option]: /docs/manual.md#location [multiline string body]: #multiline-string-body [filters]: /docs/filters.md [count]: /docs/filters.md#count [`decode` filter]: /docs/filters.md#decode [headers implicit asserts]: #headers [RFC 3339]: https://www.rfc-editor.org/rfc/rfc3339 [`Content-Encoding` HTTP header]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Encoding [`Content-Type` header]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Type [`body` assert]: #body-assert [`location` filter]: /docs/filters.md#location [UUID v4]: https://en.wikipedia.org/wiki/Universally_unique_identifier