Main Content

matlab.unittest.constraints.NumericComparator class

Package: matlab.unittest.constraints

Comparator for numeric arrays


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




c = matlab.unittest.constraints.NumericComparator creates a comparator for numeric arrays. The comparator is satisfied if the actual and expected values have the same numeric class, size, complexity, and sparsity, and the isequaln function finds them equal.


c = matlab.unittest.constraints.NumericComparator("Within",tol) uses the specified tolerance in comparison. When you use this syntax, the comparator first checks for equal class, size, and sparsity of the actual and expected values. If any of these checks fail, the comparator is not satisfied. If the checks pass, but the complexity check or isequaln check fails, the comparator delegates comparison to tol.

Input Arguments

expand all

Tolerance, specified as a matlab.unittest.constraints.Tolerance object.

This argument sets the Tolerance property.

Example: matlab.unittest.constraints.AbsoluteTolerance(1)

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


expand all

Tolerance, returned as a matlab.unittest.constraints.Tolerance object.

This property is set by the tol input argument.




collapse all

Compare actual and expected values using the NumericComparator class.

First, import the classes used in this example.

import matlab.unittest.TestCase
import matlab.unittest.constraints.IsEqualTo
import matlab.unittest.constraints.NumericComparator
import matlab.unittest.constraints.AbsoluteTolerance

Create a test case for interactive testing.

testCase = TestCase.forInteractiveUse;

Use a NumericComparator instance to compare a number to itself. The test passes.

Verification passed.

Compare the value of pi to 3.14. The test fails.

Verification failed.
    Framework Diagnostic:
    IsEqualTo failed.
    --> NumericComparator failed.
        --> The numeric values are not equal using "isequaln".
        --> Failure table:
                     Actual         Expected           Error              RelativeError    
                ________________    ________    ___________________    ____________________
                3.14159265358979      3.14      0.00159265358979299    0.000507214519042354
        Actual Value:
        Expected Value:
    Stack Information:
    In C:\work\CompareValuesUsingNumericComparatorExample.m (CompareValuesUsingNumericComparatorExample) at 21

Repeat the test using an absolute tolerance of 0.01. The test passes.

testCase.verifyThat(pi,IsEqualTo(3.14, ...
Verification passed.


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

    Use a NumericComparator instance when you need to override the comparison performed by the IsEqualTo class. For example, if you want the comparison to fail when actual and expected values are nonnumeric, include a NumericComparator instance in your test. You also can use NumericComparator to restrict the values contained in cell arrays, structures, dictionaries, tables, and public properties of MATLAB® object arrays. In this example, MATLAB throws an error because the actual and expected values are cell arrays.

    import matlab.unittest.TestCase
    import matlab.unittest.constraints.IsEqualTo
    import matlab.unittest.constraints.NumericComparator
    testCase = TestCase.forInteractiveUse;
    exp = {1,2,3}; 
    act = exp;

Version History

Introduced in R2013a