``` 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 ``` ### 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. ```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`, `includes` 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" includes "User-Agent" header "Vary" includes "Content-Type" ``` Or implicit header asserts: ```hurl GET https://example.org/hello HTTP 200 Vary: User-Agent Vary: Content-Type ``` ### 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" ``` ### 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]" equals "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. The encoding used to decode the body is based on the `charset` value in the `Content-Type` header response. ```hurl GET https://example.org HTTP 200 [Asserts] body contains "

Welcome!

" ``` ```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 contains hex,c4e3bac3cac0bde7; # 你好世界 encoded in GB 2312 body contains "你好世界" ``` If the `Content-Type` doesn't include any encoding hint, a [`decode` filter] can be used to explicitly decode the body response 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 "你好世界" ``` ### 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" ``` ### 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" includes "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://sample.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://sample.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. ### SHA-256 assert Check response body [SHA-256] hash. ```hurl GET https://example.org/data.tar.gz HTTP 200 [Asserts] sha256 == hex,039058c6f2c0cb492c533b0a4d14ef77cc0f78abccced5287d84a1a2011cfb81; ``` ### MD5 assert Check response body [MD5] hash. ```hurl GET https://example.org/data.tar.gz HTTP 200 [Asserts] md5 == hex,ed076287532e86365e841e92bfc50d8c; ``` ### 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://sample.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` and `Serial-Number`. ```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]+" ``` ## 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 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 not JSON nor XML, one can use multiline string that starts with ``` and ends with ```. For a precise byte control of the response body, a [Base64] encoded string or an input file can be used to describe exactly the body byte content to check. ### JSON body ```hurl # Get a doggy thing: GET https://example.org/api/dogs/{{dog-id}} HTTP 200 { "id": 0, "name": "Frieda", "picture": "images/scottish-terrier.jpeg", "age": 3, "breed": "Scottish Terrier", "location": "Lisco, Alabama" } ``` JSON response body can be seen as syntactic sugar of [multiline string body] with `json` identifier: ~hurl # Get a doggy thing: GET https://example.org/api/dogs/{{dog-id}} HTTP 200 ```json { "id": 0, "name": "Frieda", "picture": "images/scottish-terrier.jpeg", "age": 3, "breed": "Scottish Terrier", "location": "Lisco, Alabama" } ``` ~ ### 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. ~ XML response body can be seen as syntactic sugar of [multiline string body] with `xml` identifier: ~hurl GET https://example.org/api/catalog HTTP 200 ```xml Gambardella, Matthew XML Developer's Guide Computer 44.95 2000-10-01 An in-depth look at creating applications with XML. ``` ~ ### Multiline string body ~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 ``` ~ The standard usage of a multiline string is : ~ ``` line1 line2 line3 ``` ~ #### Oneline string body For text based response body that do not contain newlines, one can use oneline string, started and ending with `. ~hurl POST https://example.org/helloworld HTTP 200 `Hello world!` ~ ### Base64 body Base64 response body assert starts with `base64,` and end with `;`. MIME's Base64 encoding is supported (newlines and white spaces may be present anywhere but are to be ignored on decoding), and `=` padding characters might be added. ```hurl GET https://example.org HTTP 200 base64,TG9yZW0gaXBzdW0gZG9sb3Igc2l0IGFtZXQsIGNvbnNlY3RldHVyIG FkaXBpc2NpbmcgZWxpdC4gSW4gbWFsZXN1YWRhLCBuaXNsIHZlbCBkaWN0dW0g aGVuZHJlcml0LCBlc3QganVzdG8gYmliZW5kdW0gbWV0dXMsIG5lYyBydXRydW 0gdG9ydG9yIG1hc3NhIGlkIG1ldHVzLiA=; ``` ### File body To use the binary content of a local file as the body response assert, file body can be used. File body starts with `file,` and ends with `;`` ```hurl GET https://example.org HTTP 200 file,data.bin; ``` File are relative to the input Hurl file, and cannot contain implicit parent directory (`..`). You can use [`--file-root` option] to specify the root directory of all file nodes. [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