Update docs.

jcamiel · jcamiel · commit 05f05a68799a · 2025-10-06T09:58:47.000+02:00
diff --git a/sites/hurl.dev/_data/docs.yml b/sites/hurl.dev/_data/docs.yml
@@ -118,6 +118,7 @@
           items:
             - title: Debug Logs
             - title: HTTP Responses
+        - title: Stress and Performance Tests
         - title: Generating Report
           items:
             - title: HTML Report
diff --git a/sites/hurl.dev/_docs/asserting-response.md b/sites/hurl.dev/_docs/asserting-response.md
@@ -418,7 +418,7 @@ Predicates consist of a predicate function and a predicate value. Predicate func
 | __`isString`__     | Query returns a string                                                                                                                                                                                                      | `jsonpath "$.name" isString`                                                                                       |
 | __`isIpv4`__       | Query returns an IPv4 address                                                                                                                                                                                               | `ip isIpv4`                                                                                                        |
 | __`isIpv6`__       | Query returns an IPv6 address                                                                                                                                                                                               | `ip isIpv6`                                                                                                        |
-| __`isUuid`__       | Query returns a UUID                                                                                                                                                                                                        | `ip isUuid`                                                                                                        |
+| __`isUuid`__       | Query returns a [UUID v4]                                                                                                                                                                                                   | `ip isUuid`                                                                                                        |
 
 
 Each predicate can be negated by prefixing it with `not` (for instance, `not contains` or `not exists`)
@@ -1011,3 +1011,4 @@ certificate "Serial-Number" matches "[0-9af]+"
 [`Content-Type` header]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Type
 [`body` assert]: #body-assert
 [`location` filter]: {% link _docs/filters.md %}#location
+[UUID v4]: https://en.wikipedia.org/wiki/Universally_unique_identifier
diff --git a/sites/hurl.dev/_docs/capturing-response.md b/sites/hurl.dev/_docs/capturing-response.md
@@ -36,6 +36,13 @@ HTTP 302
 {% endraw %}
 
 
+Body responses can be encoded by server (see [`Content-Encoding` HTTP header]) but captures in Hurl files are not
+affected by this content compression. All body captures (`body`, `bytes`, `sha256` etc...) work _after_ content decoding.
+
+Finally, body text captures (`body`, `jsonpath`, `xpath` etc...) are also decoded to strings based on [`Content-Type` header]
+so these queries can be captures as usual strings.
+
+
 Structure of a capture:
 
 <div class="schema-container schema-container u-font-size-2 u-font-size-3-sm">
@@ -175,6 +182,8 @@ HTTP 200
 my_body: bytes decode "gb2312"
 ```
 
+`body` capture works _after_ content encoding decompression (so the captured value is not affected by `Content-Encoding` response header).
+
 ### Bytes capture
 
 Capture the entire body (as a raw bytestream) from the received HTTP response
@@ -186,6 +195,9 @@ HTTP 200
 my_data: bytes
 ```
 
+Like `body` capture, `bytes` capture works _after_ content encoding decompression (so the captured value is not
+affected by `Content-Encoding` response header).
+
 ### XPath capture
 
 Capture a [XPath] query from the received HTTP body decoded as a string.
diff --git a/sites/hurl.dev/_docs/hurl-file.md b/sites/hurl.dev/_docs/hurl-file.md
@@ -53,9 +53,9 @@ In the following example:
 
 ```hurl
 GET https://example.org/api
-x-token: BEEF \#STEACK # Some comment
+x-token: BEEF \#STEAK # Some comment
 HTTP 200
 ```
 
-We're sending a header `x-token` with value `BEEF #STEACK`
+We're sending a header `x-token` with value `BEEF #STEAK`
 
diff --git a/sites/hurl.dev/_docs/installation.md b/sites/hurl.dev/_docs/installation.md
@@ -214,4 +214,4 @@ Please follow the [contrib on Windows section].
 [NixOS / Nix package]: https://search.nixos.org/packages?from=0&size=1&sort=relevance&type=packages&query=hurl
 [`conda-forge`]: https://conda-forge.org
 [`pixi`]: https://prefix.dev
-[extra]: https://archlinux.org/packages/extra/x86   _64/hurl/
+[extra]: https://archlinux.org/packages/extra/x86_64/hurl/
diff --git a/sites/hurl.dev/_docs/running-tests.md b/sites/hurl.dev/_docs/running-tests.md
@@ -64,14 +64,17 @@ Failed files:      1 (50.0%)
 Duration:          10 ms
 ```
 
+> With or without `--test`, all asserts are always executed. `--test` adds a run recap and disables the output of the 
+> last response. To ignore asserts execution, you can use [`--ignore-asserts`].
+
 In test mode, files are executed in parallel to speed-ud the execution. If a sequential run is needed, you can use
 [`--jobs 1`] option to execute tests one by one.
 
 ```shell
 $ hurl --test --jobs 1 *.hurl
 ```
 
-[`--repeat` option] can be used to repeat run files and do performance check. For instance, this call will run 1000 tests
+[`--repeat` option] can be used to repeat run files and do [performance check]. For instance, this call will run 1000 tests
 in parallel:
 
 ```shell
@@ -204,6 +207,90 @@ Failed files:      0 (0.0%)
 Duration:          187 ms
 ```
 
+## Stress and Performance Tests
+
+Hurl can be used to perform stress tests:
+
+- with [query duration]:
+
+```hurl
+GET https://example.org/foo
+HTTP 200
+[Asserts]
+duration < 1200
+```
+
+- [response metrics] with [`--very-verbose`] or [`--json`] to get structured timing data:
+
+```shell
+$ hurl --json foo.hurl | jq
+...
+          "timings": {
+            "app_connect": 0,
+            "begin_call": "2025-10-06T07:00:57.127794Z",
+            "connect": 120915,
+            "end_call": "2025-10-06T07:00:57.280724Z",
+            "name_lookup": 92987,
+            "pre_transfer": 121014,
+            "start_transfer": 152721,
+            "total": 152807
+          }
+...
+```
+
+In performance uses-cases, it's important to know how Hurl is working to get the best request per second load. Each Hurl file 
+is processed by its own libcurl instance (roughly speaking a living HTTP connection). Let's say we want to stress our 
+application with 100,000 HTTP requests and see how it's behaving. The simplest idea would be to make a single Hurl file 
+repeating 100,000 requests:
+
+```hurl
+GET https://my-website/health
+[Options]
+repeat: 100000
+```
+
+and run it:
+
+```shell
+$ hurl --test perf.hurl
+```
+
+With a single Hurl file, we won't benefit from any parallel runs (files are run in parallel, requests _within_ a file are
+run sequentially). To benefit from parallel run, we can use [`--repeat`] as a CLI argument to repeat file execution. It's 
+as if we've written 100,000 identical Hurl files and run them:
+
+
+```hurl
+GET https://my-website/health
+```
+
+and run it:
+
+```shell
+$ hurl --test --repeat 100000 perf.hurl
+```
+
+In this case, we're running 100,000 Hurl files in parallel. Now, we have another problem: as each file is basically a
+HTTP connection, we can run out of TCP port, a phenomenon known as [ephemeral ports exhaustion]. So, to recap:
+
+- running 100,000 requests in a single file won't benefit from parallel run
+- running 100,000 one request files can lead to TCP port resources issues
+
+The solution is to combine the two approaches: running 10 files of 10,000 HTTP requests. With 10 files of 10,000
+requests, we're going to execute those files in parallel in their own worker. Each worker will be working sequentially, 
+maximizing the usage and not running into TCP ports exhaustion. We can force jobs count to be exactly 10 so 
+all workers start at the same time and no one is waiting to get a job done:
+
+```hurl
+GET https://my-website/health
+[Options]
+repeat: 10000
+```
+
+```shell
+$ hurl --test --repeat 10 --jobs 10 perf.hurl
+```
+
 
 
 ## Generating Report
@@ -257,7 +344,6 @@ To use variables in your tests, you can:
 
 You will find a detailed description in the [Injecting Variables] section of the docs.
 
-
 [`--output /dev/null`]: {% link _docs/manual.md %}#output
 [`--test`]: {% link _docs/manual.md %}#test
 [`--report-html DIR`]: {% link _docs/manual.md %}#report-html
@@ -280,3 +366,9 @@ You will find a detailed description in the [Injecting Variables] section of the
 [`very-verbose`]: {% link _docs/manual.md %}#very-verbose
 [`--output` option]: {% link _docs/manual.md %}#output
 [`--repeat` option]: {% link _docs/manual.md %}#repeat
+[query duration]: {% link _docs/asserting-response.md %}#duration-assert
+[response metrics]: {% link _docs/response.md %}#timings
+[`--ignore-asserts`]: {% link _docs/manual.md %}#ignore-asserts
+[performance check]: {% link _docs/running-tests.md %}#stress-and-performance-tests
+[ephemeral ports exhaustion]: https://blog.cloudflare.com/how-to-stop-running-out-of-ephemeral-ports-and-start-to-love-long-lived-connections/
+[`--repeat`]: {% link _docs/manual.md %}#repeat
diff --git a/sites/hurl.dev/_docs/tutorial/your-first-hurl-file.md b/sites/hurl.dev/_docs/tutorial/your-first-hurl-file.md
@@ -8,9 +8,9 @@ section: Tutorial
 # Your First Hurl File
 
 Throughout this tutorial, we'll walk through the creation of multiple
-Hurl files to test a basic web application about movies called _Movies Box_. We'll show how to test
-this site locally, and how to automate these integration tests in a CI/CD
-chain like [GitHub Action] and [GitLab CI/CD].
+Hurl files to test a basic web application about movies called _Movies Box_. The source code of the project is at 
+<https://github.com/jcamiel/hurl-express-tutorial>. We'll show how to test this site locally, and how to automate these 
+integration tests in a CI/CD chain like [GitHub Action] and [GitLab CI/CD].
 
 Our Movies Box website consists of:
 
