Main Content

matlab.unittest.constraints.TableComparator Class

Namespace: matlab.unittest.constraints

Comparator for table arrays

expand all in page

Description

The matlab.unittest.constraints.TableComparator class provides a comparator for MATLAB® table arrays. To use this comparator in your tests, create a TableComparator instance, and specify it as the value of the Using name-value argument of the IsEqualTo constraint constructor.

Creation

Description

c = matlab.unittest.constraints.TableComparator creates a comparator for empty table arrays. The comparator is satisfied if the actual and expected values are empty table arrays with the same size and property values.

example

c = matlab.unittest.constraints.TableComparator(comp) uses the specified comparators comp to compare the values contained in the table arrays. When you use this syntax, the comparator is satisfied if the actual and expected values are table arrays with the same size and property values, and the corresponding table variables satisfy any of the comparators in comp.

example

c = matlab.unittest.constraints.TableComparator(___,"Recursively",tf) also specifies whether to operate recursively when comparing the values contained in the table arrays. If tf is true, the recursion continues until all nested values are examined for equality. You can use this syntax with any of the input argument combinations in the previous syntaxes.

example

Input Arguments

expand all

Comparators used to compare the values contained in the table variables, specified as an object array of classes in the matlab.unittest.constraints namespace that are classified as comparators.

Example: matlab.unittest.constraints.NumericComparator

Example: matlab.unittest.constraints.StringComparator("IgnoringCase",true)

Example: [matlab.unittest.constraints.LogicalComparator matlab.unittest.constraints.NumericComparator]

Whether to operate recursively, specified as a numeric or logical 0 (false) or 1 (true).

When the value is true, the variables of the actual and expected table arrays also can be table arrays, and the comparator recursively compares these variables. When the value is false, all variables of the actual and expected table arrays must have a type that is supported by comp. For example, in the following code, both c1 and c2 can compare table arrays of numeric values. However, only c2 can compare table arrays that contain either table arrays or numeric values as their variables.

import matlab.unittest.constraints.TableComparator
import matlab.unittest.constraints.NumericComparator

c1 = TableComparator(NumericComparator);
c2 = TableComparator(NumericComparator,"Recursively",true);

This argument sets the Recursive property.

Properties

expand all

Whether to operate recursively, returned as a logical 0 (false) or 1 (true).

This property is set by the tf input argument.

Attributes:

GetAccess
public
SetAccess
private

Examples

collapse all

Open Script

Compare empty tables using the TableComparator class.

First, import the classes used in this example.

import matlab.unittest.TestCase
import matlab.unittest.constraints.IsEqualTo
import matlab.unittest.constraints.TableComparator

Create a test case for interactive testing.

testCase = TestCase.forInteractiveUse;

Use a TableComparator instance to compare two empty tables. Verify that table and table.empty result in the same empty table.

testCase.verifyThat(table,IsEqualTo(table.empty,"Using",TableComparator))

Verification passed.

Test if two empty tables with different property values are equal. The test fails.

T1 = table;
T1.Properties.Description = "First Empty Table";
T2 = table;
T2.Properties.Description = "Second Empty Table";
testCase.verifyThat(T1,IsEqualTo(T2,"Using",TableComparator))

Verification failed.
    ---------------------
    Framework Diagnostic:
    ---------------------
    IsEqualTo failed.
    --> TableComparator failed.
        --> Table properties do not match.
            Path to failure: <table>.Properties
            --> ObjectComparator failed.
                --> The objects are not equal using "isequaln".
                
                Actual Value:
                  TableProperties with properties:
                
                             Description: 'First Empty Table'
                                UserData: []
                          DimensionNames: {'Row'  'Variables'}
                           VariableNames: {1×0 cell}
                           VariableTypes: [1×0 string]
                    VariableDescriptions: {}
                           VariableUnits: {}
                      VariableContinuity: []
                                RowNames: {}
                        CustomProperties: No custom properties are set.
                      Use addprop and rmprop to modify CustomProperties.
                Expected Value:
                  TableProperties with properties:
                
                             Description: 'Second Empty Table'
                                UserData: []
                          DimensionNames: {'Row'  'Variables'}
                           VariableNames: {1×0 cell}
                           VariableTypes: [1×0 string]
                    VariableDescriptions: {}
                           VariableUnits: {}
                      VariableContinuity: []
                                RowNames: {}
                        CustomProperties: No custom properties are set.
                      Use addprop and rmprop to modify CustomProperties.
        
        Actual Value:
          0×0 empty table
        Expected Value:
          0×0 empty table
    ------------------
    Stack Information:
    ------------------
    In C:\work\CompareEmptyTablesExample.m (CompareEmptyTablesExample) at 25
Open Script

Compare tables that contain nonempty variables using the TableComparator class.

First, import the classes used in this example.

import matlab.unittest.TestCase
import matlab.unittest.constraints.IsEqualTo
import matlab.unittest.constraints.TableComparator
import matlab.unittest.constraints.NumericComparator
import matlab.unittest.constraints.AbsoluteTolerance

Create a test case for interactive testing.

testCase = TestCase.forInteractiveUse;

Create two tables whose variables contain numeric values.

LastName = ["Lin";"Jones";"Brown"];
Age = [38;40;49];
Height = [64;67;64];
Weight = [131;133;119];
BloodPressure = [125 83; 117 75; 122 80];
T1 = table(Age,Height,Weight,BloodPressure);
T2 = table(Age,Height,Weight,BloodPressure,'RowNames',LastName);

Use a TableComparator instance to compare the tables. To compare nonempty tables, pass an appropriate comparator to the TableComparator constructor.

testCase.verifyThat(T1,IsEqualTo(T2, ...
    "Using",TableComparator(NumericComparator)))

Verification failed.
    ---------------------
    Framework Diagnostic:
    ---------------------
    IsEqualTo failed.
    --> TableComparator failed.
        --> Table properties do not match.
            Path to failure: <table>.Properties
            --> ObjectComparator failed.
                --> The objects are not equal using "isequaln".
                
                Actual Value:
                  TableProperties with properties:
                
                             Description: ''
                                UserData: []
                          DimensionNames: {'Row'  'Variables'}
                           VariableNames: {'Age'  'Height'  'Weight'  'BloodPressure'}
                           VariableTypes: ["double"    "double"    "double"    "double"]
                    VariableDescriptions: {}
                           VariableUnits: {}
                      VariableContinuity: []
                                RowNames: {}
                        CustomProperties: No custom properties are set.
                      Use addprop and rmprop to modify CustomProperties.
                Expected Value:
                  TableProperties with properties:
                
                             Description: ''
                                UserData: []
                          DimensionNames: {'Row'  'Variables'}
                           VariableNames: {'Age'  'Height'  'Weight'  'BloodPressure'}
                           VariableTypes: ["double"    "double"    "double"    "double"]
                    VariableDescriptions: {}
                           VariableUnits: {}
                      VariableContinuity: []
                                RowNames: {3×1 cell}
                        CustomProperties: No custom properties are set.
                      Use addprop and rmprop to modify CustomProperties.
        
        Actual Value:
          3×4 table
        
            Age    Height    Weight    BloodPressure
            ___    ______    ______    _____________
        
            38       64       131       125     83  
            40       67       133       117     75  
            49       64       119       122     80  
        Expected Value:
          3×4 table
        
                     Age    Height    Weight    BloodPressure
                     ___    ______    ______    _____________
        
            Lin      38       64       131       125     83  
            Jones    40       67       133       117     75  
            Brown    49       64       119       122     80  
    ------------------
    Stack Information:
    ------------------
    In C:\work\CompareNonemptyTablesExample.m (CompareNonemptyTablesExample) at 30

Even though the table variables contain the same numeric data, the test fails because the RowNames property has different values on T1 and T2. For the test to pass, set the RowNames property on T1.

T1.Properties.RowNames = LastName;
testCase.verifyThat(T1,IsEqualTo(T2, ...
    "Using",TableComparator(NumericComparator)))

Verification passed.

Change one of the values in T2 and compare the tables again. The test fails.

T2.Age(end) = 50;
testCase.verifyThat(T1,IsEqualTo(T2, ...
    "Using",TableComparator(NumericComparator)))

Verification failed.
    ---------------------
    Framework Diagnostic:
    ---------------------
    IsEqualTo failed.
    --> Path to failure: <Value>.Age
        --> NumericComparator failed.
            --> The numeric values are not equal using "isequaln".
            --> Failure table:
                    Index    Actual    Expected    Error    RelativeError
                    _____    ______    ________    _____    _____________
                                                                         
                      3        49         50        -1          -0.02    
            
            Actual Value:
                38
                40
                49
            Expected Value:
                38
                40
                50
    
    Actual Value:
      3×4 table
    
                 Age    Height    Weight    BloodPressure
                 ___    ______    ______    _____________
    
        Lin      38       64       131       125     83  
        Jones    40       67       133       117     75  
        Brown    49       64       119       122     80  
    Expected Value:
      3×4 table
    
                 Age    Height    Weight    BloodPressure
                 ___    ______    ______    _____________
    
        Lin      38       64       131       125     83  
        Jones    40       67       133       117     75  
        Brown    50       64       119       122     80  
    ------------------
    Stack Information:
    ------------------
    In C:\work\CompareNonemptyTablesExample.m (CompareNonemptyTablesExample) at 43

Specify that corresponding values in the table variables must be equal within an absolute tolerance of 1. The test passes.

testCase.verifyThat(T1,IsEqualTo(T2, ...
    "Using",TableComparator( ...
    NumericComparator("Within",AbsoluteTolerance(1)))))

Verification passed.

Modify the tables to contain nested tables. To compare the modified tables, instruct TableComparator to operate recursively. The test passes.

T1.BloodPressure = table([125;117;122],[83;75;80]);
T2 = T1;
testCase.verifyThat(T1,IsEqualTo(T2, ...
    "Using",TableComparator(NumericComparator,"Recursively",true)))

Verification passed.

Tips

  • In most cases, you are not required to use a TableComparator instance. The IsEqualTo class creates a constraint to test for the equality of various data types, including table arrays.

    Use a TableComparator instance when you need to override the comparison performed by the IsEqualTo class. For example, if you want the comparison to fail when table arrays contain nonnumeric values, include a TableComparator instance in your test. In this example, MATLAB throws an error because the actual and expected tables contain nonnumeric values.

    import matlab.unittest.TestCase
import matlab.unittest.constraints.IsEqualTo
import matlab.unittest.constraints.TableComparator
import matlab.unittest.constraints.NumericComparator
 
testCase = TestCase.forInteractiveUse;
exp = table([45;32;34],logical([1;0;0]),'VariableNames',["Age" "Vote"]); 
act = exp;
testCase.verifyThat(act,IsEqualTo(exp,"Using",TableComparator(NumericComparator)))

Version History

Introduced in R2017a

See Also

|

Topics