Description

The behavior of the Compare method depends on whether the update feature is enabled and whether HashValue is specified.

Usually, Compare performs a byte-by-byte comparison of the two files specified. If the files are identical, the method returns True and posts a success message to the test log. If the files differ, it can also log a message indicating the level of differences between the files (see below). If the files are not found, Compare returns False and generates an error string, which you can retrieve using the Files.LastError method and then post it to the test log.

The method can operate in two modes:

Strict comparison - Returns True only if the files are the same. To perform this type of comparison, specify only the File1 and File2 parameters.
Comparison with a permissible variation - Returns True if the files are exactly identical, or if one file differs from the other and this level of difference is allowed. To perform this type of comparison, specify File1, File2 and also pass a value to the HashValue parameter.

The latter mode is rather specific and needs further explanation. During this comparison, a special value that indicates the difference between the two files is calculated. After that, this value is compared with the value of the HashValue parameter. If the calculated value equals zero or HashValue, then the compared files are considered identical. See, How File Verification Works for a detailed description and examples.

Files.Compare also lets you update the specified stored file during the script execution. TestComplete does this if the update feature is enabled, that is if both the global Update files option and the stored file’s Update option are checked. Also, one of the Compare method parameters should be the file stored in the Stores | Files collection; another parameter should be the file that will replace the stored file. In this case, Files.Compare will replace the contents of the stored file with the contents of the specified file, post a message reporting the file was updated to the log and return True.

Declaration

Files.Compare(File1, File2, HashValue, ReportDifference, MessageType)

File1	[in]	Required	String
File2	[in]	Required	String
HashValue	[in]	Optional	Integer	Default value: 0
ReportDifference	[in]	Optional	Boolean	Default value: True
MessageType	[in]	Optional	Variant	Default value: lmWarning
Result	Boolean

Applies To

The method is applied to the following object:

Files

Parameters

The method has the following parameters:

File1 and File2

Specify the files to be compared, or the stored file and the file it will be replaced with. You can either use the file name (including the path), or, if the file belongs to the Stores | Files collection, specify the file name in this collection.

If you call this method to update a stored file, at least one of the files should be the element of the Stores collection.

The order in which the files are specified is not significant for strict comparison and content update, but is extremely important for the comparison with a permissible variation. The difference calculation algorithm depends on what file name was passed first and what name was second. Thus the values of the differences would differ if the file order is changed.

HashValue

This parameter is used during the comparison with permissible variation. It specifies the reference value of allowed difference between files (0 means that the files are physically identical). Compare calculates the value of the actual difference between files and compares it with the value passed as HashValue. If these values coincide, the method assumes that the files are identical. Otherwise, the method fails, and TestComplete posts an error message with the actual value of the difference to the test log. You can use this value in future comparisons.

This value is also included in the string returned by the LastError method if the comparison fails. For more information, see File Checkpoints and How File Verification Works.

Do not obtain the value of the difference every time you are going to perform a file comparison. You should calculate the difference once and then use this value in future comparisons. Otherwise, if you calculate the value of the difference right before performing a comparison and then use it in the Compare method, the comparison will always be successful even if the compared images are not identical.

ReportDifference

Specifies whether the Compare method posts a message to the test log if the comparison fails.

MessageType

The type of message to be posted to the test log in case the comparison fails and ReportDifference is True. Possible values:

Constant	Value	Description
`lmNone`	`0`	Do not post any message.
`lmMessage`	`1`	Post an informative message.
`lmWarning`	`2`	Post a warning message.
`lmError`	`3`	Post an error message.

Result Value

True if the compared files are identical and False otherwise.

True if Compare has updated the stored file.

Remarks

If the Compare method returns False, TestComplete posts a message to the test log that contains the total number of differences between the Stores item and the specified file. A type of the posted message is specified by the MessageType parameter.

If the method uses a third-party Diff utility for file comparison (the utility and its launch parameters are specified by the Files diff utility options) and the compared files are not equal, the method also posts an informative message to the test log. The message holds a link to the file comparison report generated by the utility.

To compare a Stores item with an external file easily, you can also use the Check method of the File object.

Example

The following code snippet demonstrates how you can compare two files using the Compare method.

JavaScript, JScript

if (!Files.Compare("C:\\Work\\OrdersList_Var1.txt", "C:\\Work\\OrdersList.txt"))
Log.Warning("List of orders was changed");

Python

if not Files.Compare("C:\\Work\\OrdersList_Var1.txt", "C:\\Work\\OrdersList.txt"):
  Log.Warning("List of orders was changed")

VBScript

  If (Not Files.Compare("C:\Work\OrdersList_Var1.txt", "C:\Work\OrdersList.txt")) Then
    Log.Warning("List of orders was changed")
  End If

DelphiScript

if (not Files.Compare('C:\Work\OrdersList_Var1.txt', 'C:\Work\OrdersList.txt')) then
Log.Warning('List of orders was changed');
end;