Compare Records

The Compare Records action is used compare record layout files such as semicolon delimited files. This action does not support comparing XML files. Two distinct records can be compared for equality, or multiple records can be summed and compared to the value of a single summary record.

Before the action can be used in a test, however, certain resources must be configured in Test Integrations and APIs as follows:

Define record layouts in the Schema Library for each type of record to be compared. You must specify the appropriate field type for numeric fields, but all other fields can be strings. All columns in the layout must be defined and have unique names, and you must specify the delimiter in use under the Options tab. See Record layouts.
Note: Every column in the record must be defined in the record layout. If there are more columns in a record than expected, the action fails. If a row contains fewer columns than expected, however, the values for the "missing" columns defaults to null.
Create schemas for each type of file and apply the correct record layout to it. In general, you create one file schema per record layout. Under the Settings tab, the schema type must be set to Delimited. Additionally, you can tell Test Integrations and APIs how many rows to skip at the start of the file (for example, for header rows). See Creating file schemas.
Create file resources in the Logical view of the Architecture School perspective (Files > File). For more information, see Testing with the File transport. With each resource, you can optionally define a specific directory. The directory can be overridden in the Compare Records action. You must also apply the appropriate schema (created earlier) in the File Schema field.

Note: When you use a directory of files, a pattern must be specified (for example, *.dat, or *.* for all files). The pattern is a directory listing wildcard, not a regular expression.

After the required artifacts and resources are configured in Test Integrations and APIs, you can add the Compare Records action to a test and begin to configure it.

A record-based file comparison is made between two files or groups of files. Each source in the comparison (expected and actual) can consist of one or more files that are concatenated together for the purposes of the comparison.

The basic configuration consists of telling Test Integrations and APIs which columns within each source are used to identify a record (the record mappings) and how they are matched up between the two sides of the comparison. Next, configure which columns in matching records are to be compared.

Four tabs are available in the Compare Records window.

Four tabs are available in the Compare Records action:

Config: Used to select resources and mappings. See Selecting file resources and record mappings.
Filter: Used to configure filters. See Configuring file resource filters.
Assert: Used to set up comparison options. See Configuring comparison options.
Logging: Used to configure logging options. See Specifying the logging options.

For each resource, record mappings are specified to identify which rows to compare. For the sake of performance, the fewest number of mappings possible are to be used to uniquely identify a row, and the contents of a record mapping column must not be null. Once a matching row or set of matching rows is found, the comparison occurs as defined under the Assert tab.

Note: Each source in the comparison can be one file or a directory of files. A collection of files can be expressed by using normal filepath notation (for example, c:\files\*.dat, or c:\files\*.*). All matching files are concatenated before the comparison starts.

Columns of any type (defined in the record layout) can be compared for equality, and numeric columns can be compared against a tolerance. When you are using a tolerance, columns that do not differ by more than the specified amount (+ or -) is considered to match. For example, a tolerance of '0.1' means that 1.5 is "equal" to 1.4 and 1.6.

Note: Only columns that are specified as numeric types (in the record layout) can use a tolerance for the comparison.

If you are comparing summary data, you can specify a sum comparison that adds up values in the target resource (right side) and compare the total to a single row in the source resource (left side).

Note: Rows in the expected resource cannot be summed and compared to a single row in the actual resource, and you cannot add rows in both resources to compare.

Note: Only one type of comparison can be defined in the test action, regardless of the actual number of comparisons (that is, they are all Equality or all Sum of comparisons).

Finally, you can configure the action to report any record mapping columns that are found in one resource and not the other.

Note: If any key columns are null, they are reported as rows found in the expected resource but not in the actual resource.

Warning: The gh.filecompare.maxlinelength argument can be applied as a JVM argument in Library Manager to force the comparison to skip blank lines or lines that are too long, as they can cause Test Integrations and APIs to run out of memory. The default value is 10,000. For example, gh.filecompare.maxlinelength=6000.

Results

The test passes if the two files are identical. The test fails if any differences are found.

The number of differences that are found is reported on the console. To see a list of the differences, the action must be included as part of a test suite. The differences are then displayed on the Reports page of the Results Gallery perspective.