Documentation Center

  • Trial Software
  • Product Updates

matlab.unittest.constraints.PublicPropertyComparator class

Package: matlab.unittest.constraints

Comparator for public properties of MATLAB objects

Description

The PublicPropertyComparator compares public properties of MATLAB® objects.

The PublicPropertyComparator supports MATLAB objects or arrays of objects and recursively compares data structures contained in the public properties. The PublicPropertyComparator is different from the isequal function because it only examines the public properties of the objects.

Construction

PublicPropertyComparator creates a comparator for public properties of MATLAB objects. This comparator only supports objects with no public properties.

PublicPropertyComparator(compObj) indicates a comparator, compObj, that defines the comparator used to compare public properties. This comparator only supports in recursion the data types supported by compObj.

PublicPropertyComparator(___,Name,Value) provides a comparator with additional options specified by one or more Name,Value pair arguments. You can specify several name-value pair arguments in any order as Name1,Value1,...,NameN,ValueN. You can use this syntax with any of the input arguments of the previous syntaxes.

PublicPropertyComparator.supportingAllValues creates a comparator for public properties of MATLAB objects that supports any value in recursion. supportingAllValues is a Static method of the PublicPropertyComparator class.

You typically pass this comparator to another constraint, such as IsEqualTo. You can use the Name,Value pairs of the IsEqualTo constraint in combination with a comparator constructed with the PublicPropertyComparator.supportingAllValues syntax.

Input Arguments

compObj

Comparator object

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 comparator is insensitive to case, specified as false or true (logical 0 or 1). When it is false, the comparator is sensitive to case. The comparator only uses this name-value pair if the contents being compared consists of strings.

Default: false

'IgnoringWhitespace'

Indicator if the comparator is insensitive to whitespace, specified as false or true (logical 0 or 1). When it is false, the comparator is sensitive to whitespace. Whitespace characters are space, form feed, new line, carriage return, horizontal tab, and vertical tab. The comparator only uses this name-value pair if the contents being compared consists of strings.

Default: false

'Recursively'

Indicator of whether comparator operates recursively, specified as false or true (logical 0 or 1). When this value is false, the comparator does not operate recursively on its data.

When the value is true, the data types the public property comparator supports are fully supported in recursion.

Default: false

'Within'

Tolerance to use for numerical comparison, specified as a matlab.unittest.constraints.Tolerance object. The comparator only uses this name-value pair if the contents being compared consists of numeric types.

Default: (empty)

Properties

IgnoreCase

Indicator if the comparator is insensitive to case, specified in the name-value pair argument, 'IgnoringCase'.

IgnoreWhitespace

Indicator if the comparator is insensitive to whitespace, specified in the name-value pair argument, 'IgnoringWhitespace'.

Recursive

Indicator of whether comparator operates recursively, specified in the name-value pair argument, 'Recursively'.

Tolerance

Specific tolerance used in construction of the comparator, specified as a matlab.unittest.constraints.Tolerance object in the name-value pair argument, 'Within'.

Copy Semantics

Value. To learn how value classes affect copy operations, see Copying Objects in the MATLAB documentation.

Examples

expand all

Instantiate PublicPropertyComparator Object

In a file, Employee.m, in your working folder, construct the following class.

classdef Employee
    properties (SetAccess=immutable)
        Name;
    end
    properties (Access=private)
        Location;
    end
    methods
        function obj = Employee(name,location)
            obj.Name = name;
            obj.Location = location;
        end
    end
end

At the command prompt, create two instances of the Employee class.

e1 = Employee('sam','Building A');
e2 = Employee('Sam','Building B');

Create a test case for interactive testing.

import matlab.unittest.TestCase;
import matlab.unittest.constraints.IsEqualTo;
import matlab.unittest.constraints.PublicPropertyComparator;
import matlab.unittest.constraints.StringComparator;

testCase = TestCase.forInteractiveUse;

Construct a comparator and verify that e1 and e2 are equal.

compObj = PublicPropertyComparator;
testCase.verifyThat(e1, IsEqualTo(e2,'Using',compObj));
Error using matlab.unittest.constraints.ComparatorList/throwUnsupportedType (line 148)
No comparator in list supports the char below:
    Sam
List contains the following comparators:
   <empty>

Error in matlab.unittest.constraints.ComparatorList/getAndPrepareComparatorFor (line 197)
                list.throwUnsupportedType(expVal);

Error in matlab.unittest.constraints.ComparatorList/satisfiedBy (line 129)
            comp = list.getAndPrepareComparatorFor(expVal);

Error in matlab.unittest.internal.constraints.FieldComparator/findFirstDifferingField (line 112)
                    bool = comp.satisfiedBy(actField, expField);

Error in matlab.unittest.internal.constraints.FieldComparator/fieldsHaveSameContents (line 83)
            bool = comparator.findFirstDifferingField(actVal, expVal);

Error in matlab.unittest.internal.constraints.FieldComparator/satisfiedBy (line 22)
            bool = haveSameClass(actVal, expVal) && ...

Error in matlab.unittest.constraints.IsEqualTo/satisfiedBy (line 165)
            bool = comp.supports(actual) && comp.satisfiedBy(actual, constraint.Expected);

Error in matlab.unittest.internal.qualifications.QualificationDelegate/qualifyThat (line 92)
                result = constraint.satisfiedBy(actual);

Error in matlab.unittest.qualifications.Verifiable/verifyThat (line 206)
            qualifyThat(verifiable.VerificationDelegate, actual, constraint, varargin{:});

The test fails because, by default, the PublicPropertyComparator does not support strings.

Construct a comparator that supports strings. Specify that the comparison is not case-sensitive.

compObj = PublicPropertyComparator(StringComparator, 'IgnoringCase',true);
testCase.verifyThat(e1, IsEqualTo(e2,'Using',compObj));
Interactive verification passed.

Note that the test passes even though e1.Location and e2.Location are not the same. Since Location is a private property, the comparator does not compare its contents.

Instantiate PublicPropertyComparator Object to Support All Values

Create a test case for interactive testing.

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

testCase = TestCase.forInteractiveUse;

Test a passing case.

m1 = MException('Msg:ID','MsgText');
m2 = MException('Msg:ID','MsgText');
testCase.verifyThat(m1, IsEqualTo(m2, 'Using', ...
    PublicPropertyComparator.supportingAllValues));
Interactive verification passed.

Test a failing case.

m1 = MException('Msg:ID','MsgText');
m2 = MException('Msg:ID','msgtext');
testCase.verifyThat(m1, IsEqualTo(m2, 'Using', ...
    PublicPropertyComparator.supportingAllValues));
Interactive verification failed.

---------------------
Framework Diagnostic:
---------------------
IsEqualTo failed.
--> StringComparator failed.
    Path to failure: <Value>.message
    --> The strings are not equal
    
    Actual String:
        MsgText
    Expected String:
        msgtext

Actual MException:
      MException with properties:
    
        identifier: 'Msg:ID'
           message: 'MsgText'
             cause: {}
             stack: [0x1 struct]
Expected MException:
      MException with properties:
    
        identifier: 'Msg:ID'
           message: 'msgtext'
             cause: {}
             stack: [0x1 struct]

Test a case that passes when the comparator ignores differences in case.

m1 = MException('Msg:ID','MsgText');
m2 = MException('Msg:ID','msgtext');
testCase.verifyThat(m1, IsEqualTo(m2, 'IgnoringCase', true,...
    'Using', PublicPropertyComparator.supportingAllValues));
Interactive verification passed.

Instantiate PublicPropertyComparator Object with Tolerance

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?