All messages received by sampler TestSteps are internally converted to an XML counterpart, which provides a common ground for assertions and other post-processing. This also makes way for two of the most powerful assertions, XPath Match and XQuery Match, which both utilize the named technologies to provide fine-grained message validation possibilities. Let's have a look at each together with some examples!
Quick Tip: Both the XPath and XQuery Match assertions make use of the Saxon XPath / XQuery processor which supports most of the latest standards in this area. Check out their website to get details on supported standards, reference documentation, etc.
1. The XPath Match Assertion
The XPath assertion applies a specified XPath expression to the received message and validates the resulting nodes against an expected value. If the values match the assertion passes, otherwise it fails. Let's jump right in, here is a login response message that we want to validate;
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:sam="http://www.example.org/sample/">
Basically we want to check for the loginResponse and sessionid elements in the SOAP Body, but ignore the actual value of the sessionid since it will change between each request.
Start by selecting the "Add Assertion" button in the Assertion Toolbar and selecting the "XPath Match" assertion in the prompting dialog:
After pressing OK, the following (empty) configuration dialog is opened:
The dialog is divided into two areas: the top specifies the XPath expression to apply and the bottom the Expected Result. Next step is to specify the XPath expression that selects the loginResponse element;
declare namespace sam='http://www.example.org/sample/';
Entering this expression into the top edit field and the pressing "Select from current" in the toolbar below gives us the following:
As you can see, the "Select from current" action applied the XPath expression to the underlying response message and shows the result in the "Expected Result" field; this is now the value that SoapUI will compare against each time a new response is received and the assertion is executed. If the value doesn't match, the assertion fails.
Obviously there is a problem here; the sessionid will be different each time around which will fail the assertion, let's use the wildcard feature to work around this;
Above we have selected the "Allow Wildcards" option and replaced the sessionid value with a '*' which will result in SoapUI ignoring the sessionid value when asserting the result.
If we would want to assert the entire response message we could change the configuration to the following:
1.2. XPath Wizards
In SoapUI Pro the above creation of the assertion or just its XPath statement is extremely easy; the top left button in the XPath Match configuration dialog opens a dialog that allows you to select the desired target node for the XPath expression, which will then be created automatically for you. For the above scenario this looks as follows:
(Pressing OK in the dialog inserts the selected XPath statement into the editor field)
SoapUI Pro also adds a number of wizards to the right-click popup menu of outline view of the response message; right-clicking the node you want to assert in the outline view opens the following popup:
The first four options here all create preconfigured XPath assertions for you, for example selecting the "for Existence" option creates the following XPath Assertion;
If we instead had selected the "for Content matching RegEx" option, we would first have been prompted for a regular expression that should be used to validate the selected node;
here we specified the ".\d" regular expression which matches just numbers (see this page for a regex reference), after pressing OK we get
2. The XQuery Match Assertion
The XQuery Match assertion works just like the above described XPath assertions, with the only difference that instead of XPath it uses an XQuery expression to select the XML that should be validated, which has some distinct advantages for complex validations;
- Only desired nodes can be selected and merged into one XML result, making assertion management much easier
- Results can be ordered allowing you to create assertions that are not dependent on the ordering of items in an XML message
This calls for an example; lets say you want to validate the following response message;
<description>One handy protocol droid</description>
<description>Item nr 2</description>
<description>Item nr 3</description>
<description>Item nr 4</description>
<description>Item nr 5</description>
Now let's say you always expect these items but the order is undefined and you are only interested in validating the price. The following XQuery Match assertion will do the trick:
The specified XQuery expression selects all items, orders them by their id, and then just extracts the price into a temporary xml result. Pressing "Select from current" gives the above response.