matlab.unittest.constraints.IsEqualTo - Constraint to test for equality - MATLAB (original) (raw)

Namespace: 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](#mw%5F68385950-62a5-43be-8738-9fbcf7415078)) creates a constraint to test the expected value for equality.

example

c = matlab.unittest.constraints.IsEqualTo([expected](#mw%5F68385950-62a5-43be-8738-9fbcf7415078),[Name,Value](#namevaluepairarguments)) 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.

example

Input Arguments

expand all

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

This argument sets the [Expected](matlab.unittest.constraints.isequalto-class.html#mw%5Fce717c43-67e3-418a-a9ba-8e0dc76c1658) property.

Name-Value Arguments

expand all

Specify optional pairs of arguments asName1=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](matlab.unittest.constraints.isequalto-class.html#mw%5F2acb86eb-1757-4793-9c25-3a0b7b01371b) property.

Whether to ignore white space when comparing textual values, specified as a numeric or logical 0 (false) or1 (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](matlab.unittest.constraints.isequalto-class.html#mw%5F11d3cc11-7c73-410a-96f1-e570bce70625) 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](matlab.unittest.constraints.isequalto-class.html#mw%5F412ee195-9eb8-46b8-aecd-74b4d887585e) property.

Example: "IgnoringFields","field1"

Comparators to delegate comparison to, specified as an object vector of classes in the matlab.unittest.constraints namespace 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 theIsEqualTo constructor overrides the value specified in theStringComparator 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](matlab.unittest.constraints.isequalto-class.html#mw%5F25ac846b-a49b-43bf-9c2f-95dd4bc9f35f) 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](matlab.unittest.constraints.isequalto-class.html#mw%5Febc4f7d3-1d38-4f77-a1f7-6bbbb0a1a1af) 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 logical0 (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 logical0 (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 namespace that are classified as comparators.

This property is set by the Using 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)))

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

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

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

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: .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)))

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

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

More About

expand all

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 orisequaln 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 first checks if the actual and expected values are object arrays of the same class and size with equal values for all properties. If so, then the constraint is satisfied. Otherwise, the constraint calls isequaln or isequal to make a comparison. (If the class of the expected value defines anisequaln method, the constraint callsisequaln. Otherwise, it calls isequal.) The constraint is satisfied if the call returnstrue.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

expand all

You can use the IsEqualTo constraint to compare MATLAB dictionaries.

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