Filters

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-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:

namevariable : jsonpath "$.books[0].name"query

Assert:

jsonpath "$.books[0].name"query == "Dune"predicate

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.

jsonpath "$.name"query split "," nth 02 filters == "Herbert"predicate

Example

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

Description

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
count Counts the number of items in a collection. collection number
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
decode Decodes bytes to string using encoding. bytes string
first Returns the first element from a collection. collection any
format Formats a date to a string given a specification format. date string
htmlEscape Converts the characters &, < and > to HTML-safe sequence. string string
htmlUnescape Converts all named and numeric character references (e.g. &gt;, &#62;, &#x3e;) 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
xpath Evaluates a XPath expression. string string

base64Decode

Decodes a Base64 encoded string into bytes.

GET https://example.org/api
HTTP 200
[Asserts]
jsonpath "$.token" base64Decode == hex,3c3c3f3f3f3e3e;

base64Encode

Encodes bytes into Base64 encoded string.

GET https://example.org/api
HTTP 200
[Asserts]
bytes base64Encode == "PDw/Pz8+Pg=="

base64UrlSafeDecode

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;

base64UrlSafeEncode

Encodes bytes into Base64 encoded string (using Base64 URL safe encoding).

GET https://example.org/api
HTTP 200
[Asserts]
bytes base64UrlSafeEncode == "PDw_Pz8-Pg"

count

Counts the number of items in a collection.

GET https://example.org/api
HTTP 200
[Asserts]
jsonpath "$.books" count == 12

daysAfterNow

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

daysBeforeNow

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

decode

Decodes bytes to string using encoding.

# 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 decode "gb2312" xpath "string(//body)" == "你好世界"

first

Returns the first element from a collection.

GET https://example.org
HTTP 200
[Asserts]
jsonpath "$.books" first == "Dune"

format

Formats a date to a string given a specification format.

GET https://example.org
HTTP 200
[Asserts]
cookie "LSID[Expires]" format "%a, %d %b %Y %H:%M:%S" == "Wed, 13 Jan 2021 22:23:01"

htmlEscape

Converts the characters &, < and > to HTML-safe sequence.

GET https://example.org/api
HTTP 200
[Asserts]
jsonpath "$.text" htmlEscape == "a &gt; b"

htmlUnescape

Converts all named and numeric character references (e.g. &gt;, &#62;, &#x3e;) to the corresponding Unicode characters.

GET https://example.org/api
HTTP 200
[Asserts]
jsonpath "$.escaped_html[1]" htmlUnescape == "Foo © bar 𝌆"

jsonpath

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"

last

Returns the last element from a collection.

GET https://example.org
HTTP 200
[Asserts]
jsonpath "$.books" last == "Les Misérables"

location

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"

nth

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"

regex

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.

replace

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"

replaceRegex

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!"

split

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

toDate

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" format "%A" == "Monday"
jsonpath "$.published" toDate "%+" format "%A" == "Monday" # %+ can be used to parse ISO 8601 / RFC 3339

toFloat

Converts value to float number.

GET https://example.org/foo
HTTP 200
[Asserts]
jsonpath "$.pi" toFloat == 3.14

toHex

Converts bytes to hexadecimal string.

GET https://example.org/foo
HTTP 200
[Asserts]
bytes toHex == "d188d0b5d0bbd0bbd18b"

toInt

Converts value to integer number.

GET https://example.org/foo
HTTP 200
[Asserts]
jsonpath "$.id" toInt == 123

toString

Converts value to string.

GET https://example.org/foo
HTTP 200
[Asserts]
jsonpath "$.count" toString == "42"

urlDecode

Replaces %xx escapes with their single-character equivalent.

GET https://example.org/foo
HTTP 200
[Asserts]
jsonpath "$.encoded_url" urlDecode == "https://mozilla.org/?x=шеллы"

urlEncode

Percent-encodes all the characters which are not included in unreserved chars (see RFC3986) with the exception of 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"

urlQueryParam

Returns the value of a query parameter in a URL.

GET https://example.org/foo
HTTP 200
[Asserts]
jsonpath "$.url" urlQueryParam "x" == "шеллы"

xpath

Evaluates a XPath expression.

GET https://example.org/hello_gb2312
HTTP 200
[Asserts]
bytes decode "gb2312" xpath "string(//body)" == "你好世界"