API documentation for setResponseCallback and co. (#228)

Author: mstoykov

src/data/markdown/docs/01 guides/02 Using k6/05 Options.md

@@ -1039,7 +1039,7 @@ CLI. Available in `k6 run` and `k6 cloud` commands
 
 | Env              | CLI             | Code / Config file | Default                                                                                                      |
 | ---------------- | --------------- | ------------------ | ------------------------------------------------------------------------------------------------------------ |
-| `K6_SYSTEM_TAGS` | `--system-tags` | `systemTags`       | `proto`,`subproto`,`status`,`method`,`url`,`name`,`group`, `check`,`error`,`tls_version`,`scenario`,`service`,`rpc_type` |
+| `K6_SYSTEM_TAGS` | `--system-tags` | `systemTags`       | `proto`,`subproto`,`status`,`method`,`url`,`name`,`group`, `check`,`error`,`tls_version`,`scenario`,`service`,`rpc_type`,`expected_response` |
 
 <CodeGroup labels={[]} lineNumbers={[true]}>
 

src/data/markdown/docs/02 javascript api/07 k6-http.md

@@ -16,6 +16,8 @@ The k6/http module contains functionality for performing HTTP transactions.
 | [post( url, [body], [params] )](/javascript-api/k6-http/post-url-body-params)  | Issue an HTTP POST request. |
 | [put( url, [body], [params] )](/javascript-api/k6-http/put-url-body-params)  | Issue an HTTP PUT request. |
 | [request( method, url, [body], [params] )](/javascript-api/k6-http/request-method-url-body-params)  | Issue any type of HTTP request. |
+| [setResponseCallback(expectedStatuses)](/javascript-api/k6-http/setresponsecallback-callback)  | Sets a response callback to mark responses as expected. |
+| [expectedStatuses( statusCodes )](/javascript-api/k6-http/expectedstatuses-statuses)  | Create a callback for setResponseCallback that checks status codes. |
 
 | Class | Description |
 | -------- | ----------- |

src/data/markdown/docs/02 javascript api/07 k6-http/10-set-response-callback-expectedStatuses.md

@@ -0,0 +1,53 @@
+---
+title: 'setResponseCallback( callback )'
+description: 'set responseCallback to mark responses as expected'
+---
+
+> ### 🎉 New in v0.31.0
+
+Set the response callback to be called to determine if a response was expected/successful or not.
+
+The result of this is that requests will be tagged with `expected_response` `"true"` or `"false"` and `http_req_failed` will be emitted with the reverse. This does include all redirects so if for a request only 200 is the expected response and there is 301 redirect before that, the redirect will be marked as failed as only status code 200 was marked as expected.
+
+#### Exceptions
+
+Due to implementation specifics:
+- Requests with authentication `digest` are always expected to first get 401 and then to get whatever was specified.
+- Requests with authentication `ntlm` will let a 401 status code on the first request as well as anything defined by `expectedStatuses`
+
+
+| Parameter | Type            | Description                                                      |
+| --------- | --------------- | ---------------------------------------------------------------- |
+| callback  | [expectedStatuses](/javascript-api/k6-http/expectedstatuses-statuses) | an object returned from [expectedStatuses](/javascript-api/k6-http/expectedstatuses-statuses) |
+
+Currently only the very special [expectedStatuses](/javascript-api/k6-http/expectedstatuses-statuses) objects are supported but in the future it is planned that a JavaScript callback will be supported as well. By default requests with status codes between 200 and 399 are considered "expected".
+
+Setting the callback to `null` disables the tagging with `expected_response` and the emitting of `http_req_failed`, effectively reverting to the behaviour prior to v0.31.0.
+
+It is recommended that if a per request responseCallback is used with [Params](/javascript-api/k6-http/params) it is actually defined once and used instead of creating it on each request.
+
+### Example
+
+<CodeGroup labels={["setResponseCallback-test.js"]}>
+
+```javascript
+import http from 'k6/http';
+
+http.setResponseCallback(http.expectedStatuses({min: 200, max: 300}));
+
+var only300Callback = http.expectedStatuses(300);
+
+export default () => {
+  // this will use the default response callback and be marked as successful
+  http.get("https://httpbin.test.k6.io/status/200");
+
+  // this will be marked as a failed request as it won't get the expected status code of 300
+  http.get("https://httpbin.test.k6.io/status/200", {responseCallback: only300Callback});
+
+  http.setResponseCallback(http.expectedStatuses(301));
+  // from here on for this VU only the 301 status code will be successful so on the next iteration of
+  // the VU the first request will be marked as failure
+};
+```
+
+</CodeGroup>

src/data/markdown/docs/02 javascript api/07 k6-http/11-expected-statuses.md

@@ -0,0 +1,34 @@
+---
+title: 'expectedStatuses( statuses )'
+description: 'generates a responseCallback to check status codes'
+---
+
+> ### 🎉 New in v0.31.0
+
+Returns a callback to be used with [setResponseCallback](/javascript-api/k6-http/setresponsecallback-callback) to mark responses as expected based only on their status codes.
+
+
+| Parameter | Type            | Description                                                      |
+| --------- | --------------- | ---------------------------------------------------------------- |
+| statuses  | integer/objects | either an integer or an object like {min:100, max:300} which gives a minimum and maximum expected status codes|
+
+You can have as many arguments as wanted in any order.
+
+### Example
+
+<CodeGroup labels={["expected-statuses-test.js"]}>
+
+```javascript
+import http from 'k6/http';
+
+// setting some pretty strange status codes as expected
+http.setResponseCallback(http.expectedStatuses(406, 500, {min: 200, max: 204}, 302, {min: 305, max: 405}));
+
+export default () => {
+  // this one will actually be marked as failed as it doesn't match any of the above listed status
+  // codes
+  http.get("https://httpbin.test.k6.io/status/205");
+};
+```
+
+</CodeGroup>

src/data/markdown/docs/02 javascript api/07 k6-http/60-Params.md

@@ -16,6 +16,7 @@ _Params_ is an object used by the http.\* methods that generate HTTP requests. _
 | `Params.timeout`      | string / number | Maximum time to wait for the request to complete. Default timeout is 60 seconds (`"60s"`). <br/> Since version 0.30, `timeout` accepts a string type. For backward compatibility, the type can also be a number, in which case k6 interprets it as milliseconds, e.g., `60000` is equivalent to `"60s"`. |
 | `Params.compression`  | string | Sets whether the request body should be compressed. If set to `gzip` it will use gzip to compress the body and set the appropriate `Content-Length` and `Content-Encoding` headers.<br /><br />Possible values: `gzip`, `deflate`, `br`, `zstd`, and any comma-separated combination of them (for stacked compression)                                                                                                                                                                                                                                                                            |
 | `Params.responseType` | string | ResponseType is used to specify how to treat the body of the response. The three options are:<br />- text: k6 will return it as a string. This might not be what you want in cases of binary data as the conversation to UTF-16 will probably break it. This is also the default if<br />[discardResponseBodies](/using-k6/options) is set to false or not set at all.<br />- `binary`: k6 will return an array of ints/bytes<br />- `none`: k6 will return null as the body. The whole body will be ignored. This is the default when [discardResponseBodies](/using-k6/options) is set to true. |
+| `Params.responseCallback` | [expectedStatuses](/javascript-api/k6-http/expectedstatuses-statuses) | sets a [responseCallback](/javascript-api/k6-http/setresponsecallback-callback) only for this request. For performance reasons it's better to initialize it once and reference it for each time the same callback will need to be used|
 
 ### Example of custom HTTP headers and tags