Global objects and functions

An & in the method signatures marks the end of the mandatory arguments and the beginning of optional arguments.

###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).

###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.

Note that each request may specify its own acceptable status range, by invoking ReqBuilder#accept.

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

####req.maxThrottle(int) Sets the maximum requests-per-second rate when the throttle slider is pushed all the way.

####req.showRunningScriptCount(boolean) If the argument is true or missing, then activates the display of the number of invocations of the test function currently in progress. The number is shown above the throttle slider. An invocation of the test function is considered complete when the function itself completes and any callbacks it submitted complete, and any callbacks submitted from those callbacks complete, etc. In other words, the complete chain of events initiated by calling test must have happened for the invocation to be considered complete.

This indicator will be useful if you write such a test function that it simulates the behavior of a user of the system, including pauses between requests and possible loops. The number shown will then mean "the number of concurrent users actively using the system".

###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. ###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). ###spy(arg) ###spy(template, arg, & args...) ###infoSpy(arg) ###infoSpy(template, arg, & args...)

Log a message at the DEBUG (spy) or INFO (infoSpy) level and return the last argument.

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.

The fact that these functions return their last argument makes them specifically convenient to insert logging at any point without disturbing the existing code structure. For example, in this line of code:

req('items').get(url('http://www.example.org').s('items')).go();

if we want to log the URL, we can simply surround the expression which builds it with a spy:

req('test').get(spy('Using URL: {}', url('http://www.example.org').s('items'))).go();