matlab.unittest.constraints.StructComparator Class

Namespace: matlab.unittest.constraints

Comparator for structure arrays

Description

The matlab.unittest.constraints.StructComparator class provides a comparator for structure arrays. To use this comparator in your tests, create a StructComparator instance, and specify it as the value of the Using name-value argument of the IsEqualTo constraint constructor.

Creation

Description

c = matlab.unittest.constraints.StructComparator creates a comparator for empty structure arrays and structure arrays with no fields. The comparator is satisfied if the actual and expected values are structure arrays with the same size and fields.

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

c = matlab.unittest.constraints.StructComparator(___,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.StructComparator("Recursively",true) creates a comparator that operates recursively when comparing the values contained in the structure arrays.

Input Arguments

comp — Comparators used to compare values in structure arrays

object array of comparator classes

Comparators used to compare the values contained in the structure arrays, 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.StructComparator(Recursively=true)

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

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

IgnoringFields — Fields to ignore during comparison

string array | cell array of character vectors

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

This argument sets the IgnoredFields property.

Example: "IgnoringFields","field1"

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 fields of the actual and expected structure arrays also can be structure arrays, and the comparator recursively compares these values. When the value is false, all values in fields of the actual and expected structure arrays must have a type that is supported by comp. For example, in the following code, both c1 and c2 can compare structure arrays that contain numeric values in their fields. However, only c2 can compare structure arrays that contain either structure arrays or numeric values in their fields.

import matlab.unittest.constraints.StructComparator
import matlab.unittest.constraints.NumericComparator

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

This argument sets the Recursive property.

Properties

IgnoredFields — Fields to ignore during comparison

cell array of character vectors

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

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

Attributes:

GetAccess	public
SetAccess	private

Recursive — Whether to operate recursively

false or 0 (default) | true or 1

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

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

Attributes:

GetAccess	public
SetAccess	private

Examples

Compare Structure Arrays That Contain No Data

Compare structure arrays that contain no data using the StructComparator class.

First, import the classes used in this example.

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

Create a test case for interactive testing.

testCase = TestCase.forInteractiveUse;

Use a StructComparator instance to compare two structure arrays with no fields. The test fails because the sizes do not match.

testCase.verifyThat(struct,IsEqualTo([struct struct], ...
    "Using",StructComparator))

Verification failed.
    ---------------------
    Framework Diagnostic:
    ---------------------
    IsEqualTo failed.
    --> StructComparator failed.
        --> Sizes do not match.
            
            Actual size:
                 1     1
            Expected size:
                 1     2
        
        Actual Value:
          struct with no fields.
        Expected Value:
          1×2 struct array with no fields.
    ------------------
    Stack Information:
    ------------------
    In C:\work\CompareStructureArraysThatContainNoDataExample.m (CompareStructureArraysThatContainNoDataExample) at 18

Compare two empty structure arrays. Even though the sizes are equal, the test fails because the actual and expected structure arrays do not have the same fields.

testCase.verifyThat(struct([]),IsEqualTo(struct("f1",{},"f2",{}), ...
    "Using",StructComparator))

Verification failed.
    ---------------------
    Framework Diagnostic:
    ---------------------
    IsEqualTo failed.
    --> StructComparator failed.
        --> Structures contain different fields.
            --> Missing fields in Actual:
                    'f1'
                    'f2'
        
        Actual Value:
          0×0 empty struct array with no fields.
        Expected Value:
          0×0 empty struct array with fields:
        
            f1
            f2
    ------------------
    Stack Information:
    ------------------
    In C:\work\CompareStructureArraysThatContainNoDataExample.m (CompareStructureArraysThatContainNoDataExample) at 24

Verify that struct([]) and struct.empty result in the same empty structure array.

testCase.verifyThat(struct([]),IsEqualTo(struct.empty, ...
    "Using",StructComparator))

Verification passed.

Compare Structures That Contain Data

Compare structures that contain data using the StructComparator class.

First, import the classes used in this example.

import matlab.unittest.TestCase
import matlab.unittest.constraints.IsEqualTo
import matlab.unittest.constraints.StructComparator
import matlab.unittest.constraints.NumericComparator
import matlab.unittest.constraints.StringComparator
import matlab.unittest.constraints.RelativeTolerance

Create a test case for interactive testing.

testCase = TestCase.forInteractiveUse;

Create two structures whose fields contain numeric values.

s1 = struct("ID",10,"score",90);
s2 = struct("score",90,"ID",10);

Use a StructComparator instance to compare the structures. When structure arrays contain data, pass an appropriate comparator to the StructComparator constructor. The test passes.

testCase.verifyThat(s1,IsEqualTo(s2, ...
    "Using",StructComparator(NumericComparator)))

Verification passed.

Change one of the values contained in s2 and compare the structures again. The test fails.

s2.score = 95;
testCase.verifyThat(s1,IsEqualTo(s2, ...
    "Using",StructComparator(NumericComparator)))

Verification failed.
    ---------------------
    Framework Diagnostic:
    ---------------------
    IsEqualTo failed.
    --> Path to failure: <Value>.score
        --> NumericComparator failed.
            --> The numeric values are not equal using "isequaln".
            --> Failure table:
                    Actual    Expected    Error       RelativeError   
                    ______    ________    _____    ___________________
                                                                      
                      90         95        -5      -0.0526315789473684
            
            Actual Value:
                90
            Expected Value:
                95
    
    Actual Value:
      struct with fields:
    
           ID: 10
        score: 90
    Expected Value:
      struct with fields:
    
        score: 95
           ID: 10
    ------------------
    Stack Information:
    ------------------
    In C:\work\CompareStructuresThatContainDataExample.m (CompareStructuresThatContainDataExample) at 31

For the test to pass, specify that corresponding values must be equal within a relative tolerance of 0.1.

testCase.verifyThat(s1,IsEqualTo(s2, ...
    "Using",StructComparator(NumericComparator( ...
    "Within",RelativeTolerance(0.1)))))

Verification passed.

Compare nested structures containing strings by instructing the comparator to operate recursively. The test fails because the nested structures are not equal.

s3 = struct("name",struct("first","Mary","last","Smith"), ...
    "location","Apartment 4");
s4 = struct("name",struct("first","Sam","last","Smith"), ...
    "location","Apartment 4");
testCase.verifyThat(s3,IsEqualTo(s4, ...
    "Using",StructComparator(StringComparator,"Recursively",true)))

Verification failed.
    ---------------------
    Framework Diagnostic:
    ---------------------
    IsEqualTo failed.
    --> Path to failure: <Value>.name.first
        --> StringComparator failed.
            --> The strings are not equal.
            
            Actual Value:
                "Mary"
            Expected Value:
                "Sam"
    
    Actual Value:
      struct with fields:
    
            name: [1×1 struct]
        location: "Apartment 4"
    Expected Value:
      struct with fields:
    
            name: [1×1 struct]
        location: "Apartment 4"
    ------------------
    Stack Information:
    ------------------
    In C:\work\CompareStructuresThatContainDataExample.m (CompareStructuresThatContainDataExample) at 47

Tips

• In most cases, you are not required to use a StructComparator instance. The IsEqualTo class creates a constraint to test for the equality of various data types, including structure arrays.

  Use a StructComparator instance when you need to override the comparison performed by the IsEqualTo class. For example, if you want the comparison to fail when structure arrays contain nonnumeric values, include a StructComparator instance in your test. In this example, MATLAB^® throws an error because the actual and expected structures contain nonnumeric values.

  import matlab.unittest.TestCase
  import matlab.unittest.constraints.IsEqualTo
  import matlab.unittest.constraints.StructComparator
  import matlab.unittest.constraints.NumericComparator
  
  testCase = TestCase.forInteractiveUse;
  exp = struct("f1",zeros(1,10),"f2",'a',"f3",{'b','c'});
  act = exp;
  testCase.verifyThat(act,IsEqualTo(exp,"Using",StructComparator(NumericComparator)))
  

Version History

Introduced in R2013a