matlab.unittest.constraints.PublicPropertyComparator Class

Namespace: matlab.unittest.constraints

Comparator for public properties of MATLAB object arrays

Description

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

Unlike the isequal function, the isequaln function, or the ObjectComparator class, the PublicPropertyComparator class examines only the public properties of object arrays.

Creation

Typically, you create a PublicPropertyComparator instance using the supportingAllValues static method. The resulting instance operates recursively and supports all data types contained in the public properties. To create an instance for a specific use case, such as when you need to test for a given data type, use one of the syntaxes in this section.

Description

c = matlab.unittest.constraints.PublicPropertyComparator creates a comparator for empty object arrays or object arrays with no public properties. The comparator is satisfied if the actual and expected values are object arrays with the same class and size that either are empty or have no public properties.

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

c = matlab.unittest.constraints.PublicPropertyComparator(___,Name,Value) sets additional options using one or more name-value arguments in addition to any of the input argument combinations in the previous syntaxes. For example, c = matlab.unittest.constraints.PublicPropertyComparator("Recursively",true) creates a comparator that operates recursively when comparing the values contained in the public properties.

Input Arguments

comp — Comparators used to compare values in public properties

object array of comparator classes

Comparators used to compare the values contained in the public properties, 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]

Name-Value Arguments

Specify optional pairs of arguments as Name1=Value1,...,NameN=ValueN, where Name is the argument name and Value is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

Example: c = matlab.unittest.constraints.PublicPropertyComparator(Recursively=true)

Before R2021a, use commas to separate each name and value, and enclose Name in quotes.

Example: c = matlab.unittest.constraints.PublicPropertyComparator("Recursively",true)

IgnoringProperties — Properties to ignore during comparison

string array | cell array of character vectors

Properties to ignore during comparison, specified as a string array or cell array of character vectors. The comparator does not compare the values of the specified properties.

This argument sets the IgnoredProperties property.

Example: "IgnoringProperties","Property1"

Recursively — Whether to operate recursively

false or 0 (default) | true or 1

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

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

import matlab.unittest.constraints.PublicPropertyComparator
import matlab.unittest.constraints.NumericComparator

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

This argument sets the Recursive property.

Properties

IgnoredProperties — Properties to ignore during comparison

cell array of character vectors

Properties to ignore during comparison, returned as a cell array of character vectors.

This property is set by the IgnoringProperties name-value argument.

Attributes:

GetAccess	public
SetAccess	private

Recursive — Whether to operate recursively

false or 0 | true or 1

Whether to operate recursively, returned as a logical 0 (false) or 1 (true). If you create a PublicPropertyComparator instance using the supportingAllValues static method, then the default property value is true. Otherwise, the default property value is false.

This property is set by the Recursively name-value argument.

Attributes:

GetAccess	public
SetAccess	private

Methods

Public Methods

matlab.unittest.constraints.PublicPropertyComparator.supportingAllValues

Comparator for public properties that supports all values in recursion

Examples

Compare Values Using PublicPropertyComparator Class

Compare actual and expected values using the PublicPropertyComparator class.

In a file named Employee.m in your current folder, create the Employee class. The class has a public property Name and a private property Location.

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

Import the classes used in this example.

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

Create a test case for interactive testing.

testCase = TestCase.forInteractiveUse;

Use a PublicPropertyComparator instance to compare two empty Employee objects. The test passes.

testCase.verifyThat(Employee.empty,IsEqualTo(Employee.empty, ...
    "Using",PublicPropertyComparator))

Verification passed.

Create two nonempty Employee objects and compare them using the IsEqualTo constraint. In this example, the test fails because of the different values in the Location property.

e1 = Employee("Sam","Building A");
e2 = Employee("Sam","Building B");
testCase.verifyThat(e1,IsEqualTo(e2))

Verification failed.
    ---------------------
    Framework Diagnostic:
    ---------------------
    IsEqualTo failed.
    --> ObjectComparator failed.
        --> The objects are not equal using "isequaln".
        
        Actual Value:
          Employee with properties:
        
            Name: "Sam"
        Expected Value:
          Employee with properties:
        
            Name: "Sam"
    ------------------
    Stack Information:
    ------------------
    In C:\work\CompareValuesUsingPublicPropertyComparatorExample.m (CompareValuesUsingPublicPropertyComparatorExample) at 35

Repeat the test using a PublicPropertyComparator instance. To perform the comparison, pass an appropriate comparator to the PublicPropertyComparator constructor. Even though e1.Location and e2.Location have different values, the test passes because the comparator examines only the public property of e1 and e2.

testCase.verifyThat(e1,IsEqualTo(e2, ...
    "Using",PublicPropertyComparator(StringComparator)))

Verification passed.

Create a new Employee object and compare it to e1. The test fails because e1.Name and e3.Name have different values.

e3 = Employee("sam","Building C");
testCase.verifyThat(e1,IsEqualTo(e3, ...
    "Using",PublicPropertyComparator(StringComparator)))

Verification failed.
    ---------------------
    Framework Diagnostic:
    ---------------------
    IsEqualTo failed.
    --> Path to failure: <Value>.Name
        --> StringComparator failed.
            --> The strings are not equal.
            
            Actual Value:
                "Sam"
            Expected Value:
                "sam"
    
    Actual Value:
      Employee with properties:
    
        Name: "Sam"
    Expected Value:
      Employee with properties:
    
        Name: "sam"
    ------------------
    Stack Information:
    ------------------
    In C:\work\CompareValuesUsingPublicPropertyComparatorExample.m (CompareValuesUsingPublicPropertyComparatorExample) at 49

For the test to pass, use a comparator that ignores case.

testCase.verifyThat(e1,IsEqualTo(e3, ...
    "Using",PublicPropertyComparator( ...
    StringComparator("IgnoringCase",true))))

Verification passed.

Alternatively, you can instruct the comparator to ignore the Name property during comparison.

testCase.verifyThat(e1,IsEqualTo(e3, ...
    "Using",PublicPropertyComparator( ...
    StringComparator,"IgnoringProperties","Name")))

Verification passed.

Limitations

• The PublicPropertyComparator class does not support the public properties of objects that overload the subsref, numel, or properties functions.

Version History

Introduced in R2014a