WebAPI scripting API | QF-Test Manual

QF-Test provides a scripting API for sending HTTP(S) requests and validating the responses received during execution of a Web request node.

Scripts placed inside a Pre-request handler node typically operate on a WebRequest object that is initialized from the currently executing Web request. This object is automatically bound as qw.request during execution of the Pre-request handler nodes, so scripts can modify parameters before the request is sent.

When the response is received, it is made available to scripts placed inside a Post-request handler node in the form of a WebResponse object automatically bound as qw.response.

The implementation is based on the Java package java.net.http and several of its interfaces are directly exposed as shown below. For convenience, standard getters and setters were added to WebRequest and WebResponse enabling simplified script expressions such as qw.request.uri or qw.response.body.

HTTP headers are also a special case. Typically, they can be treated as a simple key:value map of strings, but the specification specifies case-insensitive keys and multiple values per key. The HttpHeaders class implements that behavior. Again, QF-Test provides access to this implementation while also offering various convenience methods for scripts that provide direct access to single-value headers, among other features.

Through qw.request and qw.response this module provides access to the request and response sent and received during the most recent execution of a Web request. Primary use is during execution of the Pre-request handler and Post-request handler nodes, but they remain bound even after the Web request completes to enable analysis of the most recent request and response in QF-Test's script consoles and to access response values in steps following a Web request.

The qw module also contains the following methods:


`WebResponse sendRequest(String url, String method, Map<String, String> headers, String body) throws TestException, IOException, InterruptedException`
Send a request via a Server script. The body can only be a string.
Parameters
`url`	URL of the receiver.
`method`	HTTP method.
`headers`	HTTP headers as a `Map`.
`payload`	Body as a string.
Returns	`WebResponse` object.

`WebRequest getRequest()`
Get the current thread's request.
Returns	WebRequest

`WebResponse getResponse()`
Get the current thread's response.
Returns	WebResponse

The class WebRequest extends HttpRequest and also implements its own HttpRequest.Builder, so you can use the methods of both classes directly. These methods are not documented here; please refer to the official documentation linked above.

For simplified scripting, the QF-Test classes provide alternative getters and setters. They are mostly identical to their counterparts, with two important exceptions:

The getHeaders() method does not return an HttpHeaders object like headers(), but returns a simplified Map with case-insensitive keys and a single value, the last value defined for the given name in the original HttpHeaders.
The get...() methods never return an Optional, but the contained value or a default value - usually null - if the Optional is empty.


`void addHeader(String name, String value)`
Alias for `header(String,String)`. Adds the specified name-value pair to the set of headers for this request. The value is appended to the list of values for that name.
Parameters
`name`	The name of the header to set.
`value`	The value to set.

`String body()`
Gets the request body as a `String`. If the payload for the request is loaded from a file, returns `null`.
Returns	The request body as a `String` or `null`.

`WebRequest body(String body)`
Sets the body for the request. Implicitly changes the `BodyPublisher` type to `String` using the default UTF-8 charset.
Parameters
`body`	The text to set as the body of the request.
Returns	This `WebRequest`.

`String getBody()`
Alias for `body()`. `body()`. Gets the request body as a `String`. If the payload for the request is loaded from a file, returns `null`.
Returns	The request body as a `String` or `null`.

`String getHeader(String name)`
Alias for `header(String)`. Gets the last header entry set for the given name or `null` if there is none. Convenience method for scripting, e.g. `qw.request.header("name")`.
Parameters
`name`	The name of the header.
Returns	The last header entry set for the given name or `null` if there is none.

`Map<String,String> getHeaders()`
Alternative for `headers()`. Gets an alternative header map with only the last value per name. This simplifies script access via `qw.request.headers["name"]`. If the full headers with multiple values per name are needed, use methods such as `headers()` or `getHeaders(String)`.
Returns	This request's flattened headers as a map with case-insensitive keys and only the last value per name.

`List<String> getHeaders(String name)`
Alias for `headers(String)`. Gets all header values for the given name.
Parameters
`name`	The name of the headers.
Returns	All header values for the given name or an empty list if there are none.

`String getPayload()`
Alias for `payload()`. Gets the request body as a `String`. If the payload for the request comes from a file, returns the file contents as a UTF-8 `String`.
Returns	The request body as a `String`, possibly read from a payload file.

`String getPayloadFile()`
Alias for `payloadFile()`. Gets the name of the file holding the payload for the request.
Returns	The path to the `payloadFile` or `null`.

`String header(String name)`
Convenience method for scripting, e.g. `qw.request.header("name")`. Gets the last header that was set for the given name or `null` if there is none.
Parameters
`name`	The name to get the header for.
Returns	The last header that was set for the given name or `null` if there is none.

`List<String> headers(String name)`
Gets all header values for the given name.
Parameters
`name`	The name of the headers.
Returns	All header values for the given name or an empty list if there are none.

`WebRequest method(String method)`
Sets the HTTP method for the request without changing its `BodyPublisher`.
Parameters
`method`	The method to set.
Returns	This `WebRequest`.

`String payload()`
Gets the request body as a `String`. Similar to `body()` except that if the payload for the request comes from a file, the file contents as a UTF-8 `String` are returned.
Returns	The request body as a `String`, possibly read from a payload file.

`WebRequest payload(String body)`
Overrides the body for the request. Implicitly changes the `BodyPublisher` type to `String` with the default UTF-8 charset.
Parameters
`body`	The text to set as the body of the request.
Returns	This `WebRequest`.

`String payloadFile()`
Gets the name of the file holding the payload for the request.
Returns	The name of the payload file or `null` if some other method was used to set the body or payload.

`WebRequest payloadFile(String filename)`
Sets the name of the file from which to load the payload. Changes the `BodyPublisher` type to `Path`. See `HttpRequest.BodyPublishers.ofFile(Path)`.
Parameters
`filename`	The name of the payload file to set.
Returns	This `WebRequest`.

`void setBody(String body)`
Alias for `body(String body)`. Overrides the body for the request. Implicitly changes the `BodyPublisher` type to `String` with the default UTF-8 charset.
Parameters
`body`	The text to set as the body of the request.

`void setMethod(String method)`
Alias for `method(String)`. Sets the method for the request without changing its `BodyPublisher`.
Parameters
`method`	The method to set.

`void setPayload(String body)`
Alias for `payload(String body)`. Overrides the body for the request. Implicitly changes the `BodyPublisher` type to `String` with the default UTF-8 charset.
Parameters
`body`	The text to set as the body of the request.

`void setPayloadFile(String filename)`
Alias for `payloadFile(String)`. Sets the name of the file from which to load the payload. Changes the `BodyPublisher` type to `Path`. See `HttpRequest.BodyPublishers.ofFile(Path)`.
Parameters
`filename`	The name of the payload file to set.

The qw.response object is bound in all scripting languages during execution of a Post-request handler. It can be used to read and validate response data. This object remains valid until another Web request is executed, which means it can also be used in scripts outside the WebAPI nodes.


`Object getBody()`
Alias for `body()`. Gets the response body.
Returns	The response body.

`String getBodyString()`
Gets the response body as a `String`. If a response file was specified, tries to read the contents of the file with charset based on a possible "content-type" header or UTF-8.
Returns	The response body as a `String`.

`String getHeader(String name)`
Alias for `header(String)`. Gets the last header that was set for the given name.
Parameters
`name`	The name to get the header for.
Returns	The last header that was set for the given name or `null` if there is none.

`Map<String,String> getHeaders()`
Alternative to `headers()`. Gets an alternative header map with only the last value per name. This simplifies script access via `qw.response.headers["name"]`. If the full headers with multiple values per name are needed, use methods such as `headers()` or `getHeaders(String)`.
Returns	This response's flattened headers as a map with case-insensitive keys and only the last value per name.

`List<String> getHeaders(String name)`
Alias for `headers(String)`. Gets all header values for the given name.
Parameters
`name`	The name to get the headers for.
Returns	All header values for the given name or an empty list if there are none.

`Object getJson()`
Alias for `json()`. Convenience method to get the body parsed as a JSON object.
Returns	The JSON object that the body represents. `null` if the body is not a string or parsing fails.

`String getPayloadFile()`
Gets the path of the file to which the response body was saved. This is set when the `Response file` attribute of the `WebRequestStep` was configured. The path is absolute and identical to the file path logged in the run-log during step execution.
Returns	The absolute path of the saved response file, or `null` if no response file was configured.

`SSLSession getSslSession()`
Alias for `sslSession()`. Gets the SSLSession of the response.
Returns	The SSLSession of the response.

`int getStatusCode()`
Alias for `statusCode()`. Gets the status code of the response.
Returns	The status code of the response.

`URI getUri()`
Alias for `uri()`. Gets the URI of the response.
Returns	The URI of the response.

`HttpClient.Version getVersion()`
Alias for `version()`. Gets the HTTP protocol version that was used for this response.
Returns	The HTTP protocol version of the response.

`String header(String name)`
Convenience method for script use, e.g. `qw.response.header("name")`. Gets the last header that was set for the given name.
Parameters
`name`	The name to get the header for.
Returns	The last header that was set for the given name or `null` if there is none.

`List<String> headers(String name)`
Gets all header values for the given name.
Parameters
`name`	The name to get the headers for.
Returns	All header values for the given name or an empty list if there are none.

`Object json()`
Convenience method to get the body parsed as a JSON object.
Returns	The JSON object that the body represents. `null` if the body is not a string or parsing fails.

10.0+52.6 WebAPI scripting API

10.0+52.6.1 The QF-Test WebAPI module (`qw`)

10.0+52.6.2 The `WebRequest` class (`qw.request`)

10.0+52.6.3 The WebResponse class (qw.response)

10.0+52.6 WebAPI scripting API

10.0+52.6.1 The QF-Test WebAPI module (qw)

10.0+52.6.2 The WebRequest class (qw.request)

10.0+52.6.3 The WebResponse class (qw.response)

10.0+52.6.1 The QF-Test WebAPI module (`qw`)

10.0+52.6.2 The `WebRequest` class (`qw.request`)