Main Content

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

example

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

example

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

expand all

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)

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.

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.

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"

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]

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

expand all

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

This property is set by the expected input argument.

Attributes:

GetAccess
public
SetAccess
immutable

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

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

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

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 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

collapse all

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 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 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

expand all

Version History

Introduced in R2013a

expand all