matlab.unittest.constraints.IsEqualTo class

Package: matlab.unittest.constraints
Superclasses: matlab.unittest.constraints.BooleanConstraint

General constraint to compare for equality

Description

The IsEqualTo class creates a constraint that compares data for equality. The type of comparison it uses is governed by the data type of the expected value. First, the testing framework checks if the expected value is an object. This check is performed first because it is possible for the object to have overridden methods that are used in subsequent checks (e.g. islogical). The following list categorizes and describes the various tests.

Data Type	Equality Comparison Method
MATLAB® & Java® Objects	If the expected value is a MATLAB or Java object, the IsEqualTo constraint calls the isequaln method if it is defined on the expected value object, otherwise it calls isequal. If the check returns false and a supported tolerance is specified, the IsEqualTo constraint checks the actual and expected values for equivalent class, size, and sparsity before determining if the values are within the tolerance. If the constraint can determine that the actual and expected values are equal because they are of the same class and size and all properties are equal, then IsEqualTo does not call isequal or isequaln.
Logicals	If the expected value is a logical, the constraint checks the actual and expected values for equivalent sparsity. If the sparsity matches, the constraint compares the values with the isequal method. Otherwise, the constraint is not satisfied.
Numerics	If the expected value is numeric, the constraint checks the actual and expected values for equivalent class, size, and sparsity. If the all these checks match, the constraint uses the isequaln method for comparison. If isequaln returns true, the constraint is satisfied. If the complexity does not match or isequaln returns false, and a supported tolerance is supplied, the constraint uses the tolerance in the comparison. Otherwise, the constraint is not satisfied.
Strings	If the expected value is a string, the constraint uses the strcmp function to check the actual and expected values for equality. However, if the IgnoreCase property is true, the strings are compared using strcmpi. If the IgnoreWhitespace is true, all whitespace characters are removed from the actual and expected strings before passing them to strcmp or strcmpi.
Structures	If the expected value is a struct, the constraint compares the field count of the actual and expected values. If not equal, the constraint is not satisfied. Otherwise, each field of the expected value struct must exist on the actual value struct. If any field names are different, the constraint is not satisfied. Then, the constraint recursively compares the fields in a depth first examination. The recursion continues until a fundamental data type is encountered (that is, logical, numeric, string, or object), and then the values are compared as described above.
Cell Arrays	If the expected value is a cell array, the constraint checks the actual and expected values for size equality. If they are not equal in size, the constraint is not satisfied. Otherwise, each element of the array is recursively compared in a manner identical to fields in a structure, described above.
Tables	If the expected value is a table, the actual and expected values are checked for class equality, size equality, and for equal table properties. If they are not equal in class, size, or table properties, the constraint is not satisfied. Then, the constraint compares the size and type of each column variable and recursively compares each row of the table in a depth first examination. The recursion continues until a fundamental data type is encountered (that is, logical, numeric, string, or object), and then the values are compared as described above.

Construction

IsEqualTo(expVal) provides a general constraint to compare for equality.

IsEqualTo(expVal,Name,Value) provides a constraint with additional options specified by one or more Name,Value pair arguments. Name must appear inside single quotes (''). You can specify several name-value pair arguments in any order as Name1,Value1,...,NameN,ValueN.

Input Arguments

expVal

The expected value that is compared to the actual value.

Name-Value Pair Arguments

Specify optional comma-separated pairs of Name,Value arguments. Name is the argument name and Value is the corresponding value. Name must appear inside quotes. You can specify several name and value pair arguments in any order as Name1,Value1,...,NameN,ValueN.

'IgnoringCase'	Indicator if the constraint is insensitive to case, specified as false or true (logical 0 or 1) Default: false
'IgnoringFields'	Fields to ignore during struct comparison, specified as a cell array of character vectors or a string array. Default: (empty)
'IgnoringWhitespace'	Indicator if the constraint is insensitive to whitespace, specified as false or true (logical 0 or 1) Default: false
'Using'	Particular comparator to use for constraint construction, specified as a matlab.unittest.constraints.Comparator object Default: (empty)
'Within'	Tolerance to use in constraint construction, specified as a matlab.unittest.constraints.Tolerance object Default: (empty)

Properties

Comparator	Specific comparator used in construction of the constraint, specified as a matlab.unittest.constraints.Comparator object in the name-value pair argument, 'Using'.
Expected	The expected value that is compared to the actual value specified in the expVal input argument.
IgnoreCase	Indicator if the constraint is insensitive to case, specified in the name-value pair argument, 'IgnoringCase'. This property applies at all levels of recursion, such as nested structures.
IgnoredFields	Fields to ignore during struct comparison, specified in the name-value pair argument, 'IgnoringFields'. This property applies at all levels of recursion, such as nested structures.
IgnoreWhitespace	Indicator if the constraint is insensitive to whitespace, specified in the name-value pair argument, 'IgnoringWhitespace'. This property applies at all levels of recursion, such as nested structures.
Tolerance	Specific tolerance used in construction of the constraint, specified as a matlab.unittest.constraints.Tolerance object in the name-value pair argument, 'Within'. This property applies at all levels of recursion, such as nested structures.

Copy Semantics

Value. To learn how value classes affect copy operations, see Copying Objects.

Examples

Test Numerics for Equality

Create a TestCase for interactive testing.

import matlab.unittest.TestCase
import matlab.unittest.constraints.IsEqualTo
import matlab.unittest.constraints.AbsoluteTolerance
import matlab.unittest.constraints.RelativeTolerance

testCase = TestCase.forInteractiveUse;

Verify that an actual value of 5 is equal to the expected value.

expVal = 5;
testCase.verifyThat(5,IsEqualTo(expVal))

Verification passed.

Assume that the actual value is 4.95. Verify that the difference between the actual value and expected value is less than 0.09.

testCase.verifyThat(4.95,IsEqualTo(expVal,'Within',AbsoluteTolerance(0.09)))

Verification passed.

Assume that the actual value is 4.9. Verify that the difference between the actual and expected value is less than 1%.

testCase.verifyThat(4.9,IsEqualTo(expVal,'Within',RelativeTolerance(0.01)))

Verification failed.
    ---------------------
    Framework Diagnostic:
    ---------------------
    IsEqualTo failed.
    --> NumericComparator failed.
        --> The numeric values are not equal using "isequaln".
        --> RelativeTolerance failed.
            --> The error was not within relative tolerance.
            --> Failure table:
                    Actual    Expected           Error              RelativeError       RelativeTolerance
                    ______    ________    ___________________    ___________________    _________________
                     4.9         5        -0.0999999999999996    -0.0199999999999999          0.01       
        
        Actual Value:
           4.900000000000000
        Expected Value:
             5

The two values differ by more than 1%.

Test Floating Point Calculation with Tolerance

Create a TestCase for interactive testing.

import matlab.unittest.TestCase
import matlab.unittest.constraints.IsEqualTo
import matlab.unittest.constraints.RelativeTolerance

testCase = TestCase.forInteractiveUse;

Test that 0.1*3 = 0.3.

act = 0.1*3;
exp = 0.3;
testCase.verifyThat(act, IsEqualTo(exp))

Verification failed.
    ---------------------
    Framework Diagnostic:
    ---------------------
    IsEqualTo failed.
    --> NumericComparator failed.
        --> The numeric values are not equal using "isequaln".
        --> Failure table:
                Actual    Expected           Error               RelativeError    
                ______    ________    ____________________    ____________________
                 0.3        0.3       5.55111512312578e-17    1.85037170770859e-16
        
        Actual Value:
           0.300000000000000
        Expected Value:
           0.300000000000000

This test fails due to round off error in floating point arithmetic.

Perform the comparison of floating point numbers using a tolerance. Test that 0.1*3 = 0.3 within a relative tolerance of 2*eps.

testCase.verifyThat(act, IsEqualTo(exp, ...
    'Within', RelativeTolerance(2*eps)))

Verification passed.

Test Strings for Equality

Create a TestCase for interactive testing.

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

testCase = TestCase.forInteractiveUse;

Verify that two character vectors are equal.

expVal = 'Hello';
testCase.verifyThat('Hello',IsEqualTo(expVal))

Verification passed.

Change the case of the actual value and test for equality.

testCase.verifyThat('hello',IsEqualTo(expVal))

Verification failed.

---------------------
Framework Diagnostic:
---------------------
IsEqualTo failed.
--> StringComparator failed.
    --> The character arrays are not equal.
    
    Actual char:
        hello
    Expected char:
        Hello

Ignore case and test again.

testCase.verifyThat('hello',IsEqualTo(expVal,'IgnoringCase',true))

Verification passed.

Ignore whitespace and test two character vectors.

expVal = 'a bc';
testCase.verifyThat('abc',IsEqualTo(expVal,'IgnoringWhitespace',true))
testCase.verifyThat('ab c',IsEqualTo(expVal,'IgnoringWhitespace',true))

Verification passed.
Verification passed.

Test Objects for Equality Using Comparator

Create a test case for interactive testing.

import matlab.unittest.TestCase
import matlab.unittest.constraints.IsEqualTo
import matlab.unittest.constraints.RelativeTolerance
import matlab.unittest.constraints.PublicPropertyComparator

testCase = TestCase.forInteractiveUse;

Define actual and expected timeseries objects. Perturb one of the actual data points by 1%.

expected = timeseries(1:10);
actual = expected;
actual.Data(7) = 1.01*actual.Data(7);

Test that the actual and expected values are equal within a relative tolerance of 2%.

testCase.verifyThat(actual, IsEqualTo(expected,...
    'Within', RelativeTolerance(.02)))

Verification failed.

---------------------
Framework Diagnostic:
---------------------
IsEqualTo failed.
--> ObjectComparator failed.
    --> The objects are not equal using "isequal".
    --> The tolerance was ignored. The tolerance as specified does not support comparisons of timeseries values.
    
    Actual timeseries:
          timeseries
        
          Common Properties:
                    Name: 'unnamed'
                    Time: [10x1 double]
                TimeInfo: [1x1 tsdata.timemetadata]
                    Data: [1x1x10 double]
                DataInfo: [1x1 tsdata.datametadata]
        
          More properties, Methods
    Expected timeseries:
          timeseries
        
          Common Properties:
                    Name: 'unnamed'
                    Time: [10x1 double]
                TimeInfo: [1x1 tsdata.timemetadata]
                    Data: [1x1x10 double]
                DataInfo: [1x1 tsdata.datametadata]
        
          More properties, Methods

Use the PublicPropertyComparator in the construction of the constraint.

testCase.verifyThat(actual, IsEqualTo(expected,...
    'Within', RelativeTolerance(.02),...
    'Using', PublicPropertyComparator.supportingAllValues))

Interactive verification passed.

The test passes because the PublicPropertyComparator compares each public property individually instead of comparing the object all at once. In the former test, the ObjectComparator compares timeseries objects, and therefore relies on the isequal method of the timeseries class. Due to the perturbation in the actual timeseries, isequal returns false. The comparator does not apply the tolerance because the double-valued tolerance cannot apply directly to the timeseries object. In the latter test, the comparator applies the tolerance to each public property that contains double-valued data.