matlab.unittest.constraints.IsEqualTo class

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

Constraint to test for equality

Description

The matlab.unittest.constraints.IsEqualTo class provides a constraint to test values for equality. The comparison details depend on the class of the expected value.

Creation

Description

c = matlab.unittest.constraints.IsEqualTo(expected) creates a constraint to test the expected value for equality.

c = matlab.unittest.constraints.IsEqualTo(expected,Name,Value) sets additional options using one or more name-value arguments. For example, c = matlab.unittest.constraints.IsEqualTo(expected,"IgnoringCase",true) creates a constraint that is insensitive to case.

Input Arguments

expected — Expected value

any value

Expected value, specified as a value of any data type.

This argument sets the Expected property.

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.IsEqualTo(expected,IgnoringCase=true)

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

Example: c = matlab.unittest.constraints.IsEqualTo(expected,"IgnoringCase",true)

IgnoringCase — Whether to ignore case

false or 0 (default) | true or 1

Whether to ignore case when comparing textual values, specified as a numeric or logical 0 (false) or 1 (true). By default, the constraint is sensitive to case.

This argument sets the IgnoreCase property.

IgnoringWhitespace — Whether to ignore white space

false or 0 (default) | true or 1

Whether to ignore white space when comparing textual values, specified as a numeric or logical 0 (false) or 1 (true). By default, the constraint is sensitive to white-space characters. White-space characters consist of space (' '), form feed ('\f'), new line ('\n'), carriage return ('\r'), horizontal tab ('\t'), and vertical tab ('\v').

This argument sets the IgnoreWhitespace property.

IgnoringFields — Fields to ignore when comparing structure arrays

string array | cell array of character vectors

Fields to ignore when comparing structure arrays, specified as a string array or cell array of character vectors. The constraint does not compare the values in the specified fields.

This argument sets the IgnoredFields property.

Example: "IgnoringFields","field1"

Using — Comparators to delegate comparison to

object vector of comparator classes

Comparators to delegate comparison to, specified as an object vector of classes in the matlab.unittest.constraints package that are classified as comparators.

If a comparator and the IsEqualTo constraint have a common name-value argument, the value passed to IsEqualTo overrides the corresponding value passed to the comparator. For example, this test passes because the value of the IgnoringCase name-value argument in the IsEqualTo constructor overrides the value specified in the StringComparator constructor.

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

testCase = TestCase.forInteractiveUse;
testCase.verifyThat("Text",IsEqualTo("text","IgnoringCase",true, ...
    "Using",StringComparator("IgnoringCase",false)))

This argument sets the Comparator property.

Example: "Using",matlab.unittest.constraints.NumericComparator

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

Example: "Using",[matlab.unittest.constraints.LogicalComparator matlab.unittest.constraints.NumericComparator]

Within — Tolerance to use in comparison

matlab.unittest.constraints.Tolerance object

Tolerance to use in comparison, specified as a matlab.unittest.constraints.Tolerance object.

This argument sets the Tolerance property.

Example: "Within",matlab.unittest.constraints.AbsoluteTolerance(1)

Example: "Within",matlab.unittest.constraints.AbsoluteTolerance(1) | matlab.unittest.constraints.RelativeTolerance(0.1)

Properties

Expected — Expected value

any value

Expected value, returned as a value of any data type.

This property is set by the expected input argument.

Attributes:

GetAccess	public
SetAccess	immutable

IgnoreCase — Whether to ignore case

false or 0 (default) | true or 1

Whether to ignore case when comparing textual values, returned as a logical 0 (false) or 1 (true). By default, the constraint is sensitive to case.

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

Attributes:

GetAccess	public
SetAccess	private

IgnoreWhitespace — Whether to ignore white space

false or 0 (default) | true or 1

Whether to ignore white space when comparing textual values, returned as a logical 0 (false) or 1 (true). By default, the constraint is sensitive to white-space characters.

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

Attributes:

GetAccess	public
SetAccess	private

IgnoredFields — Fields to ignore when comparing structure arrays

cell array of character vectors

Fields to ignore when comparing structure arrays, returned as a cell array of character vectors.

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

Attributes:

GetAccess	public
SetAccess	private

Comparator — Comparators to delegate comparison to

object row vector of comparator classes

Comparators to delegate comparison to, returned as an object row vector of classes in the matlab.unittest.constraints package that are classified as comparators.

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

Attributes:

GetAccess	public
SetAccess	private

Tolerance — Tolerance to use in comparison

matlab.unittest.constraints.Tolerance object

Tolerance to use in comparison, returned as a matlab.unittest.constraints.Tolerance object.

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

Attributes:

GetAccess	public
SetAccess	private

Examples

Compare Floating-Point Numbers

Test the result of a floating-point operation.

First, import the classes used in this example.

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

Create a test case for interactive testing.

testCase = TestCase.forInteractiveUse;

Compare 0.1*3 to 0.3. The test fails due to the round-off error in floating-point arithmetic.

actual = 0.1*3;
expected = 0.3;
testCase.verifyThat(actual,IsEqualTo(expected))

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
    ------------------
    Stack Information:
    ------------------
    In C:\work\TestFloatingPointNumbersExample.m (TestFloatingPointNumbersExample) at 19

Test if the values are within a relative tolerance of eps. The test passes.

testCase.verifyThat(actual,IsEqualTo(expected, ...
    "Within",RelativeTolerance(eps)))

Verification passed.

Compare Strings

Compare textual values using the IsEqualTo constraint.

First, import the classes used in this example.

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

Create a test case for interactive testing.

testCase = TestCase.forInteractiveUse;

Concatenate two strings and verify the result. The test passes.

actual = "Milky " + "Way";
expected = "Milky Way";
testCase.verifyThat(actual,IsEqualTo(expected))

Verification passed.

Change the actual value to "Milky way ". The test fails because the actual and expected values are no longer equal.

actual = "Milky way ";
testCase.verifyThat(actual,IsEqualTo(expected))

Verification failed.
    ---------------------
    Framework Diagnostic:
    ---------------------
    IsEqualTo failed.
    --> StringComparator failed.
        --> The strings are not equal.
        
        Actual Value:
            "Milky way "
        Expected Value:
            "Milky Way"
    ------------------
    Stack Information:
    ------------------
    In C:\work\CompareStringsExample.m (CompareStringsExample) at 22

For the test to pass, ignore case and white-space characters.

testCase.verifyThat(actual,IsEqualTo(expected, ...
    "IgnoringCase",true,"IgnoringWhitespace",true))

Verification passed.

Compare Public Properties of Different Types

Compare the public properties of two objects using a comparator that supports all data types.

In a file named Student.m in your current folder, create the Student class. The class has two public properties and one private property.

classdef Student
    properties (SetAccess=immutable)
        Name
        Age
    end
    properties (Access=private)
        Field
    end
    methods
        function obj = Student(name,age,field)
            arguments
                name = "";
                age = [];
                field = "";
            end
            obj.Name = name;
            obj.Age = age;
            obj.Field = field;
        end
    end
end

Import the classes used in this example.

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

Create a test case for interactive testing.

testCase = TestCase.forInteractiveUse;

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

s1 = Student("Mary Jones",20,"physics");
s2 = Student("Mary Jones",20,"biology");
testCase.verifyThat(s1,IsEqualTo(s2))

Verification failed.
    ---------------------
    Framework Diagnostic:
    ---------------------
    IsEqualTo failed.
    --> ObjectComparator failed.
        --> The objects are not equal using "isequaln".
        
        Actual Value:
          Student with properties:
        
            Name: "Mary Jones"
             Age: 20
        Expected Value:
          Student with properties:
        
            Name: "Mary Jones"
             Age: 20
    ------------------
    Stack Information:
    ------------------
    In C:\work\ComparePublicPropertiesExample.m (ComparePublicPropertiesExample) at 29

Repeat the test using a PublicPropertyComparator instance. Because the Name and Age properties are of different types, perform the comparison by using a comparator that supports all data types. Even though s1.Field and s2.Field have different values, the test passes because the comparator examines only the public properties of s1 and s2.

testCase.verifyThat(s1,IsEqualTo(s2, ...
    "Using",PublicPropertyComparator.supportingAllValues))

Verification passed.

Create a new Student object and compare it to s1. The test fails because s1.Name and s3.Name have different values.

s3 = Student("mary jones",20,"chemistry");
testCase.verifyThat(s1,IsEqualTo(s3, ...
    "Using",PublicPropertyComparator.supportingAllValues))

Verification failed.
    ---------------------
    Framework Diagnostic:
    ---------------------
    IsEqualTo failed.
    --> Path to failure: <Value>.Name
        --> StringComparator failed.
            --> The strings are not equal.
            
            Actual Value:
                "Mary Jones"
            Expected Value:
                "mary jones"
    
    Actual Value:
      Student with properties:
    
        Name: "Mary Jones"
         Age: 20
    Expected Value:
      Student with properties:
    
        Name: "mary jones"
         Age: 20
    ------------------
    Stack Information:
    ------------------
    In C:\work\ComparePublicPropertiesExample.m (ComparePublicPropertiesExample) at 44

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

testCase.verifyThat(s1,IsEqualTo(s3, ...
    "Using",PublicPropertyComparator.supportingAllValues( ...
    "IgnoringCase",true)))

Verification passed.

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

testCase.verifyThat(s1,IsEqualTo(s3, ...
    "Using",PublicPropertyComparator.supportingAllValues( ...
    "IgnoringProperties","Name")))

Verification passed.

More About

Comparison Details

This table describes how the IsEqualTo constraint behaves for different classes of expected value.

Expected Value	Comparison Details
Logical array	The constraint is satisfied if the actual and expected values have the same class, size, and sparsity, and their corresponding elements are equal.
Numeric array	When you do not specify a tolerance, the constraint is satisfied if the actual and expected values have the same class, size, complexity, and sparsity, and the isequaln function finds them equal. When you specify a tolerance, the constraint first checks for equal class, size, and sparsity of the actual and expected values. If any of these checks fail, the constraint is not satisfied. If the checks pass, but the complexity check or isequaln check fails, the constraint delegates comparison to the tolerance.
String array, character array, or cell array of character arrays	The constraint is satisfied if the actual and expected values are textual values with the same class and size, and their corresponding elements are equal. You can set the constraint to ignore case, white-space characters, or both.
Cell array	The constraint is satisfied if the actual and expected values are cell arrays with the same size, and the corresponding cell array elements also satisfy the constraint. The constraint operates recursively when comparing the values contained in cell arrays. The recursion continues until all nested values are examined for equality.
Structure array	The constraint is satisfied if the actual and expected values are structure arrays with the same size and fields, and the values in corresponding fields also satisfy the constraint. You can set the constraint to ignore certain fields. The constraint operates recursively when comparing the values contained in structure arrays. The recursion continues until all nested values are examined for equality.
Dictionary	The constraint is satisfied if the actual and expected values are dictionaries with the same keys, and the values assigned to corresponding keys also satisfy the constraint. The constraint operates recursively when comparing the values contained in dictionaries. The recursion continues until all nested values are examined for equality.
Table array	The constraint is satisfied if the actual and expected values are table arrays with the same size and property values, and the corresponding table variables also satisfy the constraint. The constraint operates recursively when comparing the values contained in table arrays. The recursion continues until all nested values are examined for equality.
MATLAB® or Java® object array	When you do not specify a tolerance, the constraint is satisfied if the actual and expected values are object arrays of the same class and size with equal values for all properties. If equality cannot be determined, the constraint then calls isequaln or isequal. (If the class of the expected value defines an isequaln method, the constraint calls isequaln. Otherwise, it calls isequal.) The constraint is satisfied if the call returns true. When you specify a tolerance, the constraint first checks for the equality of object arrays, as described above. If the check passes, the constraint is satisfied. Otherwise, the constraint checks for equal class, size, and sparsity of the actual and expected values. If any of these checks fail, the constraint is not satisfied. If they pass, the constraint delegates comparison to the tolerance.

Version History

Introduced in R2013a

R2022b: Compare dictionaries in tests

You can use the IsEqualTo constraint to compare MATLAB dictionaries.

R2019a: Table variables are consistently compared

The IsEqualTo constraint consistently compares the size and type of table variables. For example, this test fails because the actual and expected table variables have different types.

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

testCase = TestCase.forInteractiveUse;
act = table(zeros(0,2));
exp = table({});
testCase.verifyThat(act,IsEqualTo(exp))

Verification failed.
    ---------------------
    Framework Diagnostic:
    ---------------------
    IsEqualTo failed.
    --> Path to failure: <Value>.Var1
        --> CellComparator failed.
            --> Classes do not match.
                
                Actual Class:
                    double
                Expected Class:
                    cell
            
            Actual Value:
              0×2 empty double matrix
            Expected Value:
              0×0 empty cell array
    
    Actual Value:
      0×1 empty table
    Expected Value:
      0×1 empty table

In previous releases, the test passes because the constraint does not compare the table variables when the tables have no rows.