This topic covers the Diff tool, which compares saved data with incoming data and reports differences in SOAtest and Virtualize.
Sections include:

...

The Diff Project Configuration panel is divided into two main sections. The upper section contains general options. The bottom section contains the Regression Control, Ignored Differences, and Options tabs in which you can configure the options for comparing data in text, binary, JSON, and XML formats.

...

Choose Binary from the Diff Mode drop-down menu to view differences for binary files.

...

• Editor: Choose this option from the drop-down menu and enter text you want to use as a regression control in control in the related field.

• File: Choose this option from the drop-down menu and specify a file to use as a regression control. If you want to ensure that this file's path is always relative to your project file, enable the the Persist as Relative Path option.

• Data Source Column: Choose this option from the drop-down menu and specify a value from the designated data source column as regression controls. This  This option is only available if your project includes a data source.

Text Diff Mode

Choose Text from the Diff Mode drop-down menu to access the following configuration options for this mode.

...

Determines what data source values, file, or text is used as the "control" value (the value against which it will compare all subsequent results). Choose one of the following options.

• Editor:  Choose Choose this option from the drop-down menu and enter text you want to use as a regression control in control in the related field.

• File:  Choose Choose this option from the drop-down menu and specify a file to use as a regression control. If you want to ensure that this file's path is always relative to your project file, enable the Persist as Relative Path option.

• Data Source Column:  Choose Choose this option from the drop-down menu and specify a value from the designated data source column as regression controls. This  This option is only available if your project includes a data source.

Ignored Differences

From the Ignored Differences tab of the Diff tool for Text mode, you can delete any ignored text differences by clicking the Delete button.

Options

The following options are available in the Options tab of the Diff tool for Text mode.

• Regular Expression: Determines whether the expected value will be parsed as a regular expression. If this box option is unselectednot enabled, the control value will not be parsed as a regular expression. If this box option is selectedenabled, 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. For more information regarding supported regular expression syntax, click here.
• Ignore Whitespace: Determines whether empty lines and whitespaces at the end and beginning of input lines and diff control lines are ignored. If this box option is unselectednot enabled, empty lines and leading/trailing whitespaces will cause the regression test to fail. If this box option is selectedenabled, 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.
• Output results as UNIX-style diff: Determines the diff output format. If this box option is unselectednot enabled, the output will display in table form. If this box option is selectedenabled, the output will display in UNIX-style.

XML Diff Mode

Choose XML diff from the Diff Mode drop-down menu to access options for XML formats. XML mode parses XML files and compares them element by element and attribute by attribute (ignoring “ignorable” whitespace). The result of the comparison is expressed as an XML document. If you want to use this mode, make sure that both inputs are well-formed XML documents which have the same type of document element. 

...

The following options are available in the Regression Control tab the Regression Control tab of the Diff tool for Literal XML modefor Literal XML mode.

• • Editor:  Choose Choose this option from the drop-down menu and enter text you want to use as a regression control in control in the related field.

  • File:  Choose Choose this option from the drop-down menu and specify a file to use as a regression control. If you want to ensure that this file's path is always relative to your project file, enable the Persist as Relative Path option.

  • Data Source Column:  Choose Choose this option from the drop-down menu and specify a value from the designated data source column as regression controls. This  This option is only available if your project includes a data source.

• Set From WSDL: Initializes the Form XML content with the expected response based on the WSDL. This button is only available if a WSDL document exists for the particular SOAP client.

...

The XML tree displays the literal XML as a tree with each tree node representing an element. The options for the tree in the Diff panel can be configured in the same fashion as the Form XML SOAP Envelope options of the SOAP Client tool.   For more information, see see Manipulating the XML View Tree.

...

XML Ignored Differences

From the Ignored Differences tab of the Diff tool for XML mode, you can Add and Modify XPath settings by clicking the appropriate buttons. For more information on configuring Ignored Differences, see Understanding XPaths.

...

The following options are available in the Options tab of the Diff tool for XML mode.

• Diff engine: Choose a diff engine from the drop-down menu. XMLUnit is the default engine. This engine provides support for large messages, comparisons that generate a large number of differences, and the ability to ignore changes in element order. If desired, you can switch to 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 XML Sort tool to sort that part before passing the document to the Diff tool. See XML Sort for details.
• SOAP mode: If this box option is selectedenabled, the following actions are enabled:
• SOAP multi-references are resolved before diffing and are not reported as errors. For example, some services (such as Axis) rearrange the XML responses in an unpredictable way when using SOAP multi-refs (i.e.that is, giving different id numbers to the references). When such responses are diffed in text mode, failures occur even though the SOAP messages are logically equivalent, but their references are different.
• Namespace prefix changes in type and arrayType attributes are ignored. This is needed when the control is generated automatically from the WSDL because prefixes cannot be determined in advance.
• Numerical values are compared as numbers. For example, the difference between 1 and 1.0 would not be reported as an error.
• Ignore differences in comments: Disable this option to include changes in XML comments. Default It is enabled by default.

Using  Using ExamXML MDCXML

ExamXML is a 3rd third-party tool that is licensed and purchased separately from A7Soft. If you select ExamXML MDCXML, be sure to specify the location of the executable and options file.
Notes:

...

Using VMTools

 VMTools is built in to into the product. No additional license is needed. If you select VMTools, you can specify the following options:

• Output results as XML: Determines the diff output format. If this box option is unselectednot enabled, the output will display in table form. If this box option is selectedenabled, the output will display in XML. Differences are only reflected when another tool is chained to the message output of the Diff tool.

• SOAP mode: If this box option is selectedenabled, the following actions are enabled:
  • SOAP multi-references are resolved before diffing and are not reported as errors. For example, some services (such as Axis) rearrange the XML responses in an unpredictable way when using SOAP multirefs (i.e.that is, giving different id numbers to the references). When such responses are diffed in text mode, failures occur even though the SOAP messages are logically equivalent, but their references are different.
  • Namespace prefix changes in type and arrayType attributes are ignored. This is needed when the control is generated automatically from the WSDL because prefixes cannot be determined in advance.
  • Numerical values are compared as numbers. For example, the difference between 1 and 1.0 would not be reported as an error.

...

If this occurs, one of the following message messages will be printed to the Console view to explain what happened.

...

The maximum time allowed to perform an XML diff before switching to text mode is the default timeout value specified in the preference panel’s Misc tab (Connection Settings> Default timeout)—but preferences (go to Parasoft > Preferences > Misc and see the Default timeout (milliseconds) setting), but no higher than 120 seconds.

...

When JSON is selected from the Diff Mode drop-down menu of the Diff tool, the Regression Control and Ignored Differences options are available.

...

The following options are available in the Regression Control tab of the Diff tool for JSON mode.

• Name: Specifies the name of the Diff tool.

• Regression Control Source: Determines what data source values, file, or text is used as the "control" value (the value against which it will compare all subsequent results).

  • Editor:  Choose Choose this option from the drop-down menu and enter text you want to use as a regression control in control in the related field.

  • File:  Choose Choose this option from the drop-down menu and specify a file to use as a regression control. If you want to ensure that this file's path is always relative to your project file, enable the Persist as Relative Path option.

  • Data Source Column:  Choose Choose this option from the drop-down menu and specify a value from the designated data source column as regression controls. This  This option is only available if your project includes a data source.

Ignored Differences

From the Ignored Differences tab of the Diff tool for JSON mode, you can Add and Delete XPath settings by clicking the appropriate buttons.

...

Ignoring XPaths is useful for ignoring transient values that would normally cause the regression test to fail. For example, the actual outcome may contain a time stamp timestamp value that is constantly changing. Since this value is never the same, it will more than likely not match the value you configure in the Diff tool, causing the test to fail. Therefore, you can specify the XPath of this value to be ignored so that the test will not fail.

...

• Ignore XPaths from the Quality Tasks view: This is the easiest way to configure the Diff tool to ignore XPaths. After a failed regression test, you can simply right-click the Quality Tasks view node to select choose an XPath to ignore.
• Manually entering an XPath in the Diff GUI: You can manually enter an XPath by clicking the Configure Ignored Differences button in the Diff GUI.
• Ignore XPaths from the Form XML tree: You can right-click an element node from the Form XML tree and configure an XPath to ignore based on the selected element.

...

When entering XPaths to ignore in the Diff tool, it is easiest easier to right-click in the Quality Tasks view rather than manually entering the XPath position into the Diff tool GUI. XPath positions are displayed in tree form in the Quality Tasks view after a failed regression test:

To ignore an XPath from the Quality Tasks view after a failed regression test:

1. Right-click the error , then and choose Ignore XPathfrom the shortcut menu. An Ignored XPath Settings dialog displays opens with the selected XPath automatically entered.
   
2. Select the appropriate check boxes of Enable the options related to the XPath operations you would like to ignore. The following options are available:
   • XPath: Specifies the XPath position that you selected.
   • Recursive: Select to apply the Ignored XPath settings to child elements.
   • Text Content (Modify/Insert/Delete): Select the content operation you want to ignore.
   • Element/Subtree (Insert/Delete): Select the element or subtree operation you want to ignore.
   • Attribute (Modify/Insert/Delete): Select the attribute operation you want to ignore. If this field option is selectedenabled, SOAtest will only ignore the specified attribute name within the XPath. To ignore a specific attribute, enter the attribute name in the field next to the Attribute check box option. If you want to ignore more than one attribute at an element’s XPath location, leave the attribute name empty or use the wild card * (e.g. for example, myAttribute*).
   • Element Name and Namespace (Modify/Insert/Delete): Select the element name operation you want to ignore.
3. Click OK.
   
   The XPath you specified will now be ignored for any future test runs. In addition, the XPath you specified now appears in the Ignored Differences tab of the XML Mode in the Diff tool. To modify the XPath, see Modifying XPath Settings.

...

1. Select the Ignored Differences tab within the Text, XML, or JSON mode of the Diff tool.
2. Click the Add button. An empty field displays appears in the XPath column of the Ignored XPaths list. By default, the Settings column is automatically filled in with all XPath operations specified, meaning that the entire XPath you add will be ignored. To specify a single XPath operation to ignore, see Ignoring XPaths from the Form XML Tree.
3. Either enter Enter an XPath position in the empty XPath field.
4. To add additional XPaths, repeat steps 1 through 3.
5. Click the OK button.

All XPaths added will be ignored in future runs of the modified regression test. For information on modifying ignored XPaths, see Modifying XPath Settings.

...

1. Right-click an element node from the tree and choose Setup Ignored XPaths from the shortcut menu.
   • If the element you selected from the Form XML tree is not a repeated element, the Ignored XPaths Settings dialog box displays opens with the selected XPath automatically entered.
     
     
     
   • If the element you selected from the Form XML tree is a repeated element that has siblings with the same local name, a Repeated XPath Settings dialog displays.
     
     
     You can either select to Ignore All of the repeated elements , or Ignore Selected Element Only. After making your selection and clicking OK, the Ignored XPaths Settings dialog box displays with the selected XPath automatically entered.
2. Select Enable the appropriate check boxes options of the XPath operations you would like to ignore. The following options are available:
   • XPath: Specifies the XPath position that you selected.
   • Recursive: Select to apply the Ignored XPath settings to child elements.
   • Text Content (Modify/Insert/Delete): Select the content operation you want to ignore.
   • Element/Subtree (Insert/Delete): Select the element or subtree operation you want to ignore.

   • Attribute (Modify/Insert/Delete): Select the attribute operation you want to ignore. If this field option is selectedenabled, only the specified attribute name within the XPath will be ignoredbe ignored. To ignore a specific attribute, enter the attribute name in the field next to the Attribute check box option. If you want to ignore more than one attribute at an element’s XPath location, leave the attribute name empty or use the wild card * (e.g. for example, myAttribute*).

   • Element Name and Namespace (Modify/Insert/Delete): Select the element name operation you want to ignore.
3. Click OK.
   The selected element node now displays in gray in the Form XML tree. All XPath operations specified will be ignored in future runs of the modified regression test.
   To reset and no longer Ignore an XPath, right-click the Ignored XPath node and select choose Remove Ignored XPath from the shortcut menu. The node will then display in black and will no longer be ignored.

...

By default, when you add an XPath to the Ignored Differences tab, all of the possible operations for that XPath display appear in the Settings column. Since all of the possible operations for the XPath are specified by default, all of these operations will be ignored the next time the regression test is run. However, you can specify which operations are ignored, rather than having all of them ignored, by modifying the XPath settings.

...

1. In the Ignored Differences tab, select the XPath you would like to modify and click theModify button. The Ignored XPaths Settings dialog box displaysopens.
   
2. Select the appropriate check boxes of Enable the options related to the XPath operations you would like to ignore. The following options are available:
   • Recursive: Select to apply the Ignored XPath settings to child elements.
   • XPath: Specifies the XPath position that you selected.
   • Text Content (Modify/Insert/Delete): Select the content operation you want to ignore.
   • Element/Subtree (Insert/Delete): Select the element or subtree operation you want to ignore.

   • Attribute (Modify/Insert/Delete): Select the attribute operation you want to ignore. If this field option is selectedenabled, only the specified attribute name within the XPath will be ignored. To ignore a specific attribute, enter the attribute name in the field next to the Attribute check box option. If you want to ignore more than one attribute at an element’s XPath location, leave the attribute name empty or use the wild card * (e.g. for example, myAttribute*).

   • Element Name and Namespace (Modify/Insert/Delete): Select the element name operation you want to ignore.
3. Click OK.

...