XMLHttpRequest Object

The XMLHttpRequest object can be used as a HTTP client that can make GET, HEAD, POST, PUT, PATCH or DELETE requests. Possible usage ranges from querying the content of Web pages up to so called REST calls with data transmitted as plain text, XML or JSON.

XMLHttpRequest XMLHttpRequest()

The constructor for the XMLHttpRequest type.

XMLHttpRequest.abort()

This function will reset the client object and change the readyState property back to UNSENT.

String XMLHttpRequest.getResponseHeader(header)

This function returns the header field value from the response of which the field name matches header. A call like

var client = new XMLHttpRequest();
client.open("GET", "http://www.example.com/result.txt", false);
client.send();
test.log(client.getResponseHeader("Content-Type"));

might log a result like "text/plain".

String XMLHttpRequest.getAllResponseHeaders()

This function returns all headers from the response. Whereas each name/value pair is separated by a CR/LF sequence.

XMLHttpRequest.open(method, url, async, [username], [password])

This function opens the client for a method request to the specified url. The method can be any of GET, HEAD, POST, PUT, PATCH or DELETE. The async parameter has to be false.

The optional username and password parameters can be used for authentication against the server.

Unlike in a Web browser the requests initiated through the XMLHttpRequest object will run in the foreground only. Installation of a handler receiving the data asynchronously is not required. With async set to false calls to send() will wait for the response to fully have arrived before returning.

Number XMLHttpRequest.readyState

This property holds the current state of the client. Possible values are XMLHttpRequest.UNSENT, OPENED, HEADERS_RECEIVED, LOADING and DONE. Given the synchronous send() mode the intermediate states HEADERS_RECEIVED and LOADING will not be visible to the test script.

String XMLHttpRequest.responseText

In case of a successful request this property holds the server's response. The response text is expected to have been UTF-8 encoded. Here is an example that makes use of this property to check the content of a Web page:

var client = new XMLHttpRequest();
client.open('GET', 'https://www.froglogic.com', false);
client.send();
test.compare(client.status, 200);
test.verify(client.response.indexOf("Testing") >= 0);

XMLHttpRequest.send([data], [boundary])

This function initiates the request as specified by XMLHttpRequest.open(method, url, async, [username], [password]). The data argument is ignored if the request method is GET or HEAD. The optional boundary is only used when sending form data and sets the dividing boundary between key-value pairs.

An fictional example demonstrating the addition of a customer to a database via a REST API call:

var client = new XMLHttpRequest();
client.open("POST", "http://www.example.com/rest/CUSTOMER/", false);
client.send("<CUSTOMER><ID>60</ID><FIRSTNAME>Laura</FIRSTNAME><LASTNAME>Miller</LASTNAME><STREET>443 Seventh Av.</STREET><CITY>Lyon</CITY></CUSTOMER>");
test.compare(client.statusText, "Created");

Furthermore, this function can send FormData according to the FormData Web API using an HTTP POST or PUT request. The following example shows how another customer can be added to the same database as above using FormData.

var client = new XMLHttpRequest();
client.open("POST", "http://www.example.com/rest/CUSTOMER/", false);
client.setRequestHeader( "Content-type", "multipart/form-data" );

var data = new FormData();
data.append("id", "61");
data.append("firstname", "John");
data.append("lastname", "Smith");
data.append("street", "1301 Ferguson Rd");
data.append("city", "Sebastopol");

client.send(data);
test.compare(client.statusText, "Created");

When sending form data this way it is important to use XMLHttpRequest.setRequestHeader(header, value) and to set the media type with Content-type to multipart/form-data. Setting the Content-type header is imperative for data to be interpreted correctly by the server.

It is possible to set a custom boundary used in the HTTP request body to separate the keys from the values and avoid any random boundaries. This boundary is provided as a second optional argument for the send method. The boundary should not exceed 70 characters and should contain only characters from the US-ASCII character set. When using UTF-8 characters please set the charset inside Content-Type header accordingly.

client.send(data, "CUSTOMBOUNDARY");

For further details how to handle such data please refer to the section FormData Object.

XMLHttpRequest.setRequestHeader(header, value)

This function adds a header to the list of request headers, of if header is already in the list of headers, combines its value with value An example showing an explicit setting of the type of message being sent:

client.setRequestHeader("Content-Type", "text/plain;charset=UTF-8");
client.send(message);

Number XMLHttpRequest.status

This read-only property holds the HTTP status code of the previous request. For example, 200 if a GET request succeeded. See the Status Code Registry for a complete listing.

String XMLHttpRequest.statusText

This read-only property holds the HTTP status text of the previous request. For example, "OK" if a GET request succeeded. See the Status Code Registry for a complete listing.