To quickly add diff comparisons to your SOAP Client and REST Client tools, you can create Diff tools directly from the CTP interface. The Diff tool compares the data in its editor against a specified regression control and reports a failure when it finds a difference. The Diff tool can be used for JSON, XML, text, or binary.
Any Diff tools added from CTP will be attached to the response of the selected test.
Additionally, you can edit Diff tools that were added to the response traffic using SOAtest desktop. Any Diff tools that are added to the request traffic using SOAtest desktop will not be visible in CTP. Binary diff tools can be edited, but not added, in CTP.
Diff tools vs. Assertor tools
If you want to check whether all or most parts of a message match a regression control, use a Diff tool. If you want to check a specific element of a message—and/or if you want to validate something other than a match—use an Assertor.
Adding a Diff Tool
To add a new Diff tool:
- In the left pane, select the REST Client or SOAP Client whose response you want to compare.
- Choose the appropriate Add Diff command from the page-level action menu.
Note that JSON Diff tools are available for REST Clients, but not for SOAP Clients.
- (Optional) Modify the name of the newly-created tool.
- Configure the tool as described below.
- Save the new tool configuration.
The new tool will be "chained" as an output to the response of the selected test client tool. Header Diff tools are chained to the response header. All other Diff tools are chained to the response body message.
Configuring a Diff Tool
To configure a Diff tool:
In the Regression control area, specify the "control" value (the value against which it will compare all subsequent results). Depending on the Diff type selected, you may have access to a literal text editor, a JSON editor, and/or an XML editor (see Editing JSON Messages and Editing XML Messages for details and tips).
Updating the regression control based on the most recent traffic
If CTP has access to new traffic that is different than the current regression control, you can click the Update Regression Control button to copy the new traffic into your regression control.
- (XML or Text/Header Diff only) In the Options area, modify additional configuration options as needed. See XML Diff Options and Text Diff / Header Diff Options for details.
- (Optional) In the Ignored differences, specify any differences you want to allow (i.e., differences you do NOT want reported as errors). Depending on the type of Diff, ignored differences can be specified using XPath builders (which is described in Specifying XPaths) and/or tables. When working with a table:
- Modify Allowed accepts a different value for the specified property.
- Insert Allowed accepts a new/additional property (which you will need to add in the table).
- Delete Allowed accepts the absence of the specified property.
- Click within the table row to toggle between Allowed and Not Allowed.
XML Diff Options
|Diff engine||Specifies what diff engine is used. XMLUnit is the default; it provides support for large messages, comparisons that generate a large number of differences, and the ability to ignore changes in element order. Diff tools created in older versions of SOAtest tools may be configured to use VMTools or ExamXML MDCXML.|
|Ignore element order||Configures the tool to ignore element order throughout all areas of every processed document. Note that if you’d rather ignore order for only a specific part of the document, use the SOAtest XML Sort tool to sort that part before passing the document to the Diff tool.|
|SOAP mode||If this is selected, the following actions are enabled: |
Text Diff / Header Diff Options
Determines whether the expected value will be parsed as a regular expression. If this box is unselected, the control value will not be parsed as a regular expression. If this box is selected, the control value will be parsed as a regular expression.
For example, the following regular expression may be entered:
Java[a-zA-Z ]+\Q(\E[4-9]+th Edition\Q)\E
Where the actual string extracted may be the following: Java How to Program (4th Edition)
The regular expression will parse through the above string to check if "Java" appears as the first substring, followed by one or more occurrences (indicated by the + operator after the open and closed brackets) whereas the occurrences are limited to only letters ranging between a-z and A-Z and whitespace. Notice we escaped ( and ) by adding \Q and \E around ( and ). This needs to be done because open and closed parentheses can be part of a regular expression, therefore they need to be escaped if they are represented to be substrings. We also have a digit appear after the first open parenthesis which is indicated by [4-9]+. This specifies at least one occurrence of a digit between 4 and 9 that should appear and be followed by "th Edition". Lastly, we have the closed parenthesis which we escape with \Q\E.
Determines whether empty lines and whitespaces at the end and beginning of input lines and diff control lines are ignored. If this box is unselected, empty lines and leading/trailing whitespaces will cause the regression test to fail. If this box is selected, empty lines and leading/trailing whitespaces will be ignored.
A whitespace is any of the following: horizontal tabulation, new line, form feed, carriage return, space. An empty line is a line that contains one or more of these whitespaces.