docs/filters.md
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-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.
Capture:
<div class="schema-container schema-container u-font-size-2 u-font-size-3-md"> <div class="schema"> <span class="schema-token schema-color-1">name<span class="schema-label">variable</span></span> <span> : </span> <span class="schema-token schema-color-2">jsonpath "$.books[0].name"<span class="schema-label">query</span></span> </div> </div>Assert:
<div class="schema-container schema-container u-font-size-2 u-font-size-3-md"> <div class="schema"> <span class="schema-token schema-color-2">jsonpath "$.books[0].name"<span class="schema-label">query</span></span> <span class="schema-token schema-color-3">== "Dune"<span class="schema-label">predicate</span></span> </div> </div>In both case, the query is exactly the same: queries are the core structure of asserts and captures. Sometimes, you want to process data extracted by queries: that's the purpose of filters.
Filters are used to transform value extracted by a query and can be used in asserts and captures to refine data. Filters can be chained, allowing for fine-grained data extraction.
<div class="schema-container schema-container u-font-size-2 u-font-size-3-md"> <div class="schema"> <span class="schema-token schema-color-2">jsonpath "$.name"<span class="schema-label">query</span></span> <span class="schema-token schema-color-1">split "," nth 0<span class="schema-label">2 filters</span></span> <span class="schema-token schema-color-3">== "Herbert"<span class="schema-label">predicate</span></span> </div> </div>GET https://example.org/api
HTTP 200
[Captures]
name: jsonpath "$.user.id" replaceRegex /\d/ "x"
[Asserts]
header "x-servers" split "," count == 2
header "x-servers" split "," nth 0 == "rec1"
header "x-servers" split "," nth 1 == "rec3"
jsonpath "$.books" count == 12
| Filter | Description | Input | Output |
|---|---|---|---|
| base64Decode | Decodes a Base64 encoded string into bytes. | string | bytes |
| base64Encode | Encodes bytes into Base64 encoded string. | bytes | string |
| base64UrlSafeDecode | Decodes a Base64 encoded string into bytes (using Base64 URL safe encoding). | string | bytes |
| base64UrlSafeEncode | Encodes bytes into Base64 encoded string (using Base64 URL safe encoding). | bytes | string |
| charsetDecode | Decodes bytes to string using a charset encoding. | bytes | string |
| count | Counts the number of items in a collection. | collection | number |
| dateFormat | Formats a date to a string given a specification format. | date | string |
| daysAfterNow | Returns the number of days between now and a date in the future. | date | number |
| daysBeforeNow | Returns the number of days between now and a date in the past. | date | number |
| first | Returns the first element from a collection. | collection | any |
| htmlEscape | Converts the characters &, < and > to HTML-safe sequence. | string | string |
| htmlUnescape | Converts all named and numeric character references (e.g. >, >, >) to the corresponding Unicode characters. | string | string |
| jsonpath | Evaluates a JSONPath expression. | string | any |
| last | Returns the last element from a collection. | collection | any |
| location | Returns the target location URL of a redirection. | response | string |
| nth | Returns the element from a collection at a zero-based index, accepts negative indices for indexing from the end of the collection. | collection | any |
| regex | Extracts regex capture group. Pattern must have at least one capture group. | string | string |
| replace | Replaces all occurrences of old string with new string. | string | string |
| replaceRegex | Replaces all occurrences of a pattern with new string. | string | string |
| split | Splits to a list of strings around occurrences of the specified delimiter. | string | string |
| toDate | Converts a string to a date given a specification format. | string | date |
| toFloat | Converts value to float number. | string | number | number |
| toHex | Converts bytes to hexadecimal string. | bytes | string |
| toInt | Converts value to integer number. | string | number | number |
| toString | Converts value to string. | any | string |
| urlDecode | Replaces %xx escapes with their single-character equivalent. | string | string |
| urlEncode | Percent-encodes all the characters which are not included in unreserved chars (see RFC3986) with the exception of forward slash (/). | string | string |
| urlQueryParam | Returns the value of a query parameter in a URL. | string | string |
| utf8Decode | Decodes bytes to string using UTF-8 encoding. | bytes | string |
| utf8Encode | Encodes a string to bytes using UTF-8 encoding. | string | bytes |
| xpath | Evaluates a XPath expression. | string | string |
Decodes a Base64 encoded string into bytes.
GET https://example.org/api
HTTP 200
[Asserts]
jsonpath "$.token" base64Decode == hex,3c3c3f3f3f3e3e;
Encodes bytes into Base64 encoded string.
GET https://example.org/api
HTTP 200
[Asserts]
bytes base64Encode == "PDw/Pz8+Pg=="
Decodes a Base64 encoded string into bytes (using Base64 URL safe encoding).
GET https://example.org/api
HTTP 200
[Asserts]
jsonpath "$.token" base64UrlSafeDecode == hex,3c3c3f3f3f3e3e;
Encodes bytes into Base64 encoded string (using Base64 URL safe encoding).
GET https://example.org/api
HTTP 200
[Asserts]
bytes base64UrlSafeEncode == "PDw_Pz8-Pg"
Decodes bytes to string using a charset encoding. Encoding labels are defined in Encoding Standard.
# The 'Content-Type' HTTP response header does not precise the charset 'gb2312'
# so body must be decoded explicitly by Hurl before processing any text based assert
GET https://example.org/hello_china
HTTP 200
[Asserts]
header "Content-Type" == "text/html"
# Content-Type has no encoding clue, we must decode ourselves the body response.
bytes charsetDecode "gb2312" xpath "string(//body)" == "你好世界"
When the encoding is UTF-8 (i.e. charsetDecode "utf-8"), an utf8Decode filter can be used instead.
Counts the number of items in a collection.
GET https://example.org/api
HTTP 200
[Asserts]
jsonpath "$.books" count == 12
Formerly known as format, which is deprecated and will be removed in a future major version.
Formats a date to a string given a specification format.
GET https://example.org
HTTP 200
[Asserts]
cookie "LSID[Expires]" dateFormat "%a, %d %b %Y %H:%M:%S" == "Wed, 13 Jan 2021 22:23:01"
Returns the number of days between now and a date in the future.
GET https://example.org
HTTP 200
[Asserts]
certificate "Expire-Date" daysAfterNow > 15
Returns the number of days between now and a date in the past.
GET https://example.org
HTTP 200
[Asserts]
certificate "Start-Date" daysBeforeNow < 100
Returns the first element from a collection.
GET https://example.org
HTTP 200
[Asserts]
jsonpath "$.books" first == "Dune"
Converts the characters &, < and > to HTML-safe sequence.
GET https://example.org/api
HTTP 200
[Asserts]
jsonpath "$.text" htmlEscape == "a > b"
Converts all named and numeric character references (e.g. >, >, >) to the corresponding Unicode characters.
GET https://example.org/api
HTTP 200
[Asserts]
jsonpath "$.escaped_html[1]" htmlUnescape == "Foo © bar 𝌆"
Evaluates a JSONPath expression.
GET https://example.org/api
HTTP 200
[Captures]
books: xpath "string(//body/@data-books)"
[Asserts]
variable "books" jsonpath "$[0].name" == "Dune"
variable "books" jsonpath "$[0].author" == "Franck Herbert"
Returns the last element from a collection.
GET https://example.org
HTTP 200
[Asserts]
jsonpath "$.books" last == "Les Misérables"
Returns the target URL location of a redirection; the returned URL is always absolute, contrary to the Location header from
which it's originated that can be absolute or relative.
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"
Returns the element from a collection at a zero-based index, accepts negative indices for indexing from the end of the collection.
GET https://example.org/api
HTTP 200
[Asserts]
jsonpath "$.books" nth 2 == "Children of Dune"
Extracts regex capture group. Pattern must have at least one capture group.
GET https://example.org/foo
HTTP 200
[Captures]
param1: header "header1"
param2: header "header2" regex "Hello (.*)!"
param3: header "header2" regex /Hello (.*)!/
param3: header "header2" regex /(?i)Hello (.*)!/
The regex syntax is documented at https://docs.rs/regex/latest/regex/#syntax.
Replaces all occurrences of old string with new string.
GET https://example.org/foo
HTTP 200
[Captures]
url: jsonpath "$.url" replace "http://" "https://"
[Asserts]
jsonpath "$.ips" replace ", " "|" == "192.168.2.1|10.0.0.20|10.0.0.10"
Replaces all occurrences of a pattern with new string.
GET https://example.org/foo
HTTP 200
[Captures]
url: jsonpath "$.id" replaceRegex /\d/ "x"
[Asserts]
jsonpath "$.message" replaceRegex "B[aoi]b" "Dude" == "Welcome Dude!"
Splits to a list of strings around occurrences of the specified delimiter.
GET https://example.org/foo
HTTP 200
[Asserts]
jsonpath "$.ips" split ", " count == 3
Converts a string to a date given a specification format.
GET https:///example.org
HTTP 200
[Asserts]
header "Expires" toDate "%a, %d %b %Y %H:%M:%S GMT" daysBeforeNow > 1000
ISO 8601 / RFC 3339 date and time format have shorthand format %+:
GET https://example.org/api/books
HTTP 200
[Asserts]
jsonpath "$.published" == "2023-01-23T18:25:43.511Z"
jsonpath "$.published" toDate "%Y-%m-%dT%H:%M:%S%.fZ" dateFormat "%A" == "Monday"
jsonpath "$.published" toDate "%+" dateFormat "%A" == "Monday" # %+ can be used to parse ISO 8601 / RFC 3339
Converts value to float number.
GET https://example.org/foo
HTTP 200
[Asserts]
jsonpath "$.pi" toFloat == 3.14
Converts bytes to hexadecimal string.
GET https://example.org/foo
HTTP 200
[Asserts]
bytes toHex == "d188d0b5d0bbd0bbd18b"
Converts value to integer number.
GET https://example.org/foo
HTTP 200
[Asserts]
jsonpath "$.id" toInt == 123
Converts value to string.
GET https://example.org/foo
HTTP 200
[Asserts]
jsonpath "$.count" toString == "42"
Replaces %xx escapes with their single-character equivalent.
GET https://example.org/foo
HTTP 200
[Asserts]
jsonpath "$.encoded_url" urlDecode == "https://mozilla.org/?x=шеллы"
Percent-encodes all the characters which are not included in unreserved chars (see RFC3986) except forward slash (/).
GET https://example.org/foo
HTTP 200
[Asserts]
jsonpath "$.url" urlEncode == "https%3A//mozilla.org/%3Fx%3D%D1%88%D0%B5%D0%BB%D0%BB%D1%8B"
Returns the value of a query parameter in a URL.
GET https://example.org/foo
HTTP 200
[Asserts]
jsonpath "$.url" urlQueryParam "x" == "шеллы"
Decodes bytes to string using UTF-8 encoding.
GET https://example.org/messages
HTTP 200
[Asserts]
# From a Base64 string to UTF-8 bytes to final string
jsonpath "$.bytesInBase64" base64Decode utf8Decode == "Hello World"
Encodes a string to bytes using UTF-8 encoding.
GET https://example.org/drinks
HTTP 200
[Asserts]
jsonpath "$.beverage" utf8Encode toHex == "636166C3A9"
Evaluates a XPath expression.
GET https://example.org/hello_gb2312
HTTP 200
[Asserts]
bytes decode "gb2312" xpath "string(//body)" == "你好世界"