Using XML Over TCP
Another option for automated testing, if you prefer working with XML, is to send properly formatted XML messages directly to dsTest. This is the method both dsClient Terminal and dsClient Desktop use to communicate with dsTest. The XML must match the element sequencing and value restrictions defined in the dsTest schema. You can incorporate dsClient Desktop, running in headless mode, in your automation scheme to generate the XML for your tests. As with the RESTful API you can encrypt this traffic with SSL if desired.
dsTest uses two ports for its control interface: the high priority port (9998) and the low priority port (9999). dsTest can be configured and controlled by sending XML messages to these two ports. The high priority port should be use for configuring dsTest and for controlling an active test, such as with action commands. The low priority port must be used to manage notifications or to get information from dsTest, such as Operational Measurements or status information. dsTest processes messages in a serial manner and it will complete processing of one message before starting on the next. It processes messages received on the low priority port as system resources allow, thereby ensuring that test performance is not impacted. Refer to this FAQ for all of the ports that must be open if dsClient and dsTest must communicate across a firewall.
Also see Automated Testing Support.
The XML declaration of version and encoding may be included but is not required as dsTest only supports UTF-8 encoding. The XML name space attribute defining the "dst" name space, however, is required on the devsol element. You may use the optional sequence attribute in the devsol element to uniquely identify your messages. If you do, dsTest will return the same sequence number in its response. This is useful for matching responses to requests if dsTest will also be sending notifications to the client.
The first four bytes of every request sent to dsTest must specify the length of the XML in bytes. Messages sent by dsTest will likewise specify the length of the XML content.
In this example, dsTest has been configured with an HSS node. To get the status of that HSS node, send a status command as follows:
<?xml version="1.0" encoding="UTF-8"?>
<dst:devsol xmlns:dst="http://www.developingsolutions.com/schema/dsTest" sequence="88505">
A message trace of a properly formatted message will appear as below. Note that the first four bytes contain the length of the XML shown above.
Parsing Responses and Notifications
dsTest messages always contain complete XML documents (i.e., having a devsol root element). Asynchronous notification messages sent by dsTest will contain one notification element per message, the content of which is dependent on the type of notification.
Messages that are sent in response to a request will return the sequence number transmitted in the request, if one was included, in the sequence attribute of the devsol element and the response is always contained in a response element. The content of that element is determined by the type of response.
A positive response to an executable command is an empty response element.
A negative response to any request message - a validation error or operational error, for example - is contained in the error element, a child of response.
A textual response to a query command is contained in the result element.
The content of the response element in response to a query request will consist of XML structure(s) as defined in the schema. The response to the example command is shown below (white space has been added for readability).
<dst:devsol xmlns:dst="http://www.developingsolutions.com/schema/dsTest" sequence='88505'>