Documentation Center

  • Trial Software
  • Product Updates

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 TypeEquality Comparison Method
MATLAB® & Java® Objects

If the expected value is a MATLAB or Java object, the IsEqualTo constraint calls the isequal method on the expected value object. If isequal returns false and a supported tolerance is specified, the constraint checks the actual and expected values for equivalent class, size, and sparsity. If these checks fail, the constraint is not satisfied. If these checks pass, the constraint uses the tolerance in the comparison.

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 (i.e. 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.

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 will be 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 single 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

'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 will be 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.

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 in the MATLAB documentation.

Examples

expand all

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(expVal, IsEqualTo(5));
Interactive 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(expVal, IsEqualTo(4.95, 'Within', AbsoluteTolerance(0.09)));
Interactive 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(expVal, IsEqualTo(4.9, 'Within', RelativeTolerance(0.01)));
Interactive verification failed.

---------------------
Framework Diagnostic:
---------------------
IsEqualTo failed.
--> NumericComparator failed.
    --> The values are not equal using "isequaln".
    --> RelativeTolerance failed.
        --> The value was not within relative tolerance.
            
            Tolerance Value:
                   0.010000000000000

Actual Value:
         5
Expected Value:
       4.900000000000000

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))
Interactive verification failed.

---------------------
Framework Diagnostic:
---------------------
IsEqualTo failed.
--> NumericComparator failed.
    --> The values are not equal using "isequaln".

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)));
Interactive 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 strings are equal.

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

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

testCase.verifyThat(expVal, IsEqualTo('hello'));
Interactive verification failed.

---------------------
Framework Diagnostic:
---------------------
IsEqualTo failed.
--> StringComparator failed.
    --> The strings are not equal

Actual String:
    Hello
Expected String:
    hello

Ignore case and test again.

testCase.verifyThat(expVal, IsEqualTo('hello', 'IgnoringCase', true));
Interactive verification passed.

Ignore whitespace and test two strings.

expVal = 'a bc';
testCase.verifyThat(expVal, IsEqualTo('abc', 'IgnoringWhitespace', true));
testCase.verifyThat(expVal, IsEqualTo('ab c', 'IgnoringWhitespace', true));
Interactive verification passed.
Interactive 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)));
Interactive verification failed.

---------------------
Framework Diagnostic:
---------------------
IsEqualTo failed.
--> ObjectComparator failed.
    --> The objects are not equal using "isequal".
    --> The tolerance does not support timeseries values so it was not used.

Actual Object:
      timeseries
    
      Common Properties:
                Name: 'unnamed'
                Time: [10x1 double]
            TimeInfo: [1x1 tsdata.timemetadata]
                Data: [1x1x10 double]
            DataInfo: [1x1 tsdata.datametadata]
    
      More properties, Methods
Expected Object:
      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 is used on the timeseries object, 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.

See Also

|

Was this topic helpful?