Global objects and functions

###req: factory of ReqBuilders

req is used both as an object and a function.

####req(name) Returns a ReqBuilder for a named request.

####req.<http-method>(url) Returns a ReqBuilder for an unnamed request.

<http-method> is one of get, put, post, delete, head, or options.

url is a string, commonly built by the UrlBuilder.

####req.acceptableStatus(status) Sets the default for the range of HTTP response status code which are deemed as acceptable (not indicating a failure). Since this mutates the global state, it should be called inside the init() method. Calling it from test() will have unpredictable consequences.

status is one of:

• any: all responses are acceptable;
• success: only 200-something and 300-something status codes are acceptable;
• ok: only 200-something status codes are acceptable.

####req.declare(name...) Declares the names of requests to be tracked in the GUI. Must be called before creating any named requests.

###require(filename) Evaluates the named file as a part of the current RequestAge script.

If filename names a relative path, it is relative to the location of the top-level script being executed.

Multiple requires of the same file are allowed: repetitions will be simply ignored.

require returns a boolean value indicating whether the file was evaluated (true) or ignored as a repetition (false).

###ns(prefix, & uri) Factory of JDOM2 Namespace objects, as accepted by the xml() global function and JdomBuilder's el method. <prefix> indicates the prefix to be used for the namespace; <uri> indicates the namespace URI. Optional: if ommitted, the prefix should already have been declared with nsdecl().

###nsdecl(prefix, url) Declares an XML namespace prefix, allowing later calls to ns() to use just the prefix argument.

###xml(root, & ns) Factory of JdomBuilder objects.

root is the root, specified as either:

• a string: the name of the root element,
• a JDOM2 Element: the root element, or
• a JDOM2 Document: the document node.

ns: optional argument, if root is given as a string. Specifies the namespace. Type: JDOM2 Namespace, usually obtained from the ns() function.

###parseXml(input) Parses the input into a JDOM2 document tree. input can be:

• a Response object (getResponseBodyAsStream will be called to retrieve the bytes),
• an InputStream, or
• a string.

prettyXml(input) Returns an object whose toString method will return a pretty-printed (indented) XML string representation of the input, which can be:

• a Response object,
• an InputStream,
• a string,
• a JDOM2 object (Document or any Content),
• a JdomBuilder object.

Note that the creation of the XML string is lazy and the input argument is retained until the first invocation of toString, after which it is released. This means that the cost of pretty printing is incurred only if the result of this function is actually used. This makes it safe to pass to spy and infoSpy, which will not call toString on their arguments unless the appropriate logging level is enabled.

###xpath(expr)

expr is a string, an XPath 1.0 expression.

The expr string is compiled and returned as an XPathExpression object. If expr was seen previously, the corresponding XPathExpression object is retrieved from the cache without recompiling. The cache is limited to 256 entries; all further expressions are recompiled every time.

###regex(expr)

expr is a string, a Java regex expression.

The expr string is compiled and returned as a java.util.regex.Pattern object. If expr was seen previously, the corresponding Pattern object is retrieved from the cache without recompiling. The cache is limited to 256 entries; all further expressions are recompiled every time.

Note: JavaScript has its own native regular expression support. This function is provided as a second choice, when there is a specific reason to use Java's regular expressions (could be performance or a missing feature in JavaScript's regex).

###url(baseUrl) Factory of UrlBuilder objects.

baseUrl is a string specifying the base URL. At a minimum it must contain the URI scheme (http or https) and authority (username, server port) parts; the rest can be added through URL builder's methods.

###spy(arg) ###spy(template, arg, & args) ###infoSpy(arg) ###infoSpy(template, arg, & args)

Log a message at the DEBUG (spy) or INFO (infoSpy) level.

If there is a single argument, it is logged as-is.

If there are two or more arguments, then the first one is used as an SLF4j template, where {} marks a placeholder where further arguments will be inserted. This avoids the cost of toString() conversion when the log statement will be ignored due to a disabled logging level.