Sync.

Author: jcamiel

sites/hurl.dev/_docs/asserting-response.md

@@ -25,6 +25,11 @@ jsonpath "$.cats[0].name" == "Felix"
 jsonpath "$.cats[0].lives" == 9
 ```
 
+Body responses can be encoded by server (see [`Content-Encoding` HTTP header]) but asserts in Hurl files are not 
+affected by this content compression. All body asserts (`body`, `bytes`, `sha256` etc...) work _after_ content decoding.
+Finally, body text asserts (`body`, `jsonpath`, `xpath` etc...) are also decoded to strings based on [`Content-Type` header] 
+so these asserts can be written with usual strings. 
+
 ## Implicit asserts
 
 ### Version - Status
@@ -245,7 +250,8 @@ In this case, the XPath query `string(//article/@data-visible)` returns a string
 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.
+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...
@@ -383,10 +389,8 @@ cookie "LSID[SameSite]" == "Lax"
 
 ### 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.
+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
@@ -395,18 +399,23 @@ HTTP 200
 body contains "<h1>Welcome!</h1>"
 ```
 
+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` doesn't include any encoding hint, a [`decode` filter] can be used to explicitly decode the body response
-bytes.
+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.
@@ -420,10 +429,31 @@ 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 "<h1>Welcome!</h1>"
+
+# Without content encoding, asserts remains identical
+GET https://example.org
+HTTP 200
+[Asserts]
+header "Content-Encoding" not exists
+body contains "<h1>Welcome!</h1>"
+```
+
+
 ### 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.
+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
@@ -434,6 +464,10 @@ 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
@@ -610,6 +644,26 @@ HTTP 200
 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.
@@ -621,6 +675,8 @@ HTTP 200
 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)
 
 ### Variable assert
 
@@ -672,6 +728,11 @@ with <code>&#96;&#96;&#96;</code>. For a precise byte control of the response bo
 a [Base64] encoded string or an input file can be used to describe exactly
 the body byte content to check.
 
+Like explicit [`body` assert], the body section is automatically decompressed based on the value of `Content-Encoding` 
+response header. So, whatever is the response compression (`gzip`, `brotli`, etc...) body section doesn't depend on
+the content encoding. For textual body sections (JSON, XML, multiline, etc...), content is also decoded to string, based
+on the value of `Content-Type` response header.
+
 ### JSON body
 
 {% raw %}
@@ -842,3 +903,6 @@ of all file nodes.
 [`decode` filter]: {% link _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

sites/hurl.dev/_docs/frequently-asked-questions.md

@@ -25,10 +25,10 @@ but also as a test tool for HTTP sessions, or even as documentation.
 Having a text based [file format] is another advantage. The Hurl format is simple,
 focused on the HTTP domain, can serve as documentation and can be read or written by non-technical people.
 
-For instance posting JSON data with Hurl can be done with this simple file:
+For instance putting JSON data with Hurl can be done with this simple file:
 
 ``` 
-POST http://localhost:3000/api/login
+PUT http://localhost:3000/api/login
 {
   "username": "xyz",
   "password": "xyz"
@@ -39,7 +39,7 @@ With [curl]:
 
 ```
 curl --header "Content-Type: application/json" \
-     --request POST \
+     --request PUT \
      --data '{"username": "xyz","password": "xyz"}' \
      http://localhost:3000/api/login
 ``` 

sites/hurl.dev/_docs/manual.md

@@ -170,7 +170,7 @@ will follow a redirection only for the second entry.
 | <a href="#cookie" id="cookie"><code>-b, --cookie &lt;FILE&gt;</code></a>                                          | Read cookies from FILE (using the Netscape cookie file format).<br><br>Combined with [`-c, --cookie-jar`](#cookie-jar), you can simulate a cookie storage between successive Hurl runs.<br><br>This is a cli-only option.<br>                                                                                                                                                                                                        |
 | <a href="#cookie-jar" id="cookie-jar"><code>-c, --cookie-jar &lt;FILE&gt;</code></a>                              | Write cookies to FILE after running the session (only for one session).<br>The file will be written using the Netscape cookie file format.<br><br>Combined with [`-b, --cookie`](#cookie), you can simulate a cookie storage between successive Hurl runs.<br><br>This is a cli-only option.<br>                                                                                                                                     |
 | <a href="#curl" id="curl"><code>--curl &lt;FILE&gt;</code></a>                                                    | Export each request to a list of curl commands.<br><br>This is a cli-only option.<br>                                                                                                                                                                                                                                                                                                                                                |
-| <a href="#delay" id="delay"><code>--delay &lt;MILLISECONDS&gt;</code></a>                                         | Sets delay before each request (aka sleep). The delay is not applied to requests that have been retried because of [`--retry`](#retry). See [`--retry-interval`](#retry-interval) to space retried requests.<br><br>You can specify time units in the delay expression. Set Hurl to use a delay of 2 seconds with `--delay 2s` or set it to 500 milliseconds with `--delay 500ms`. No spaces allowed.<br>                      |
+| <a href="#delay" id="delay"><code>--delay &lt;MILLISECONDS&gt;</code></a>                                         | Sets delay before each request (aka sleep). The delay is not applied to requests that have been retried because of [`--retry`](#retry). See [`--retry-interval`](#retry-interval) to space retried requests.<br><br>You can specify time units in the delay expression. Set Hurl to use a delay of 2 seconds with `--delay 2s` or set it to 500 milliseconds with `--delay 500ms`. No spaces allowed.<br>                            |
 | <a href="#error-format" id="error-format"><code>--error-format &lt;FORMAT&gt;</code></a>                          | Control the format of error message (short by default or long)<br><br>This is a cli-only option.<br>                                                                                                                                                                                                                                                                                                                                 |
 | <a href="#file-root" id="file-root"><code>--file-root &lt;DIR&gt;</code></a>                                      | Set root directory to import files in Hurl. This is used for files in multipart form data, request body and response output.<br>When it is not explicitly defined, files are relative to the Hurl file's directory.<br><br>This is a cli-only option.<br>                                                                                                                                                                            |
 | <a href="#from-entry" id="from-entry"><code>--from-entry &lt;ENTRY_NUMBER&gt;</code></a>                          | Execute Hurl file from ENTRY_NUMBER (starting at 1).<br><br>This is a cli-only option.<br>                                                                                                                                                                                                                                                                                                                                           |