Documentation

This is machine translation

Translated by
Mouseover text to see original. Click the button below to return to the English verison of the page.

matlab.unittest.constraints.IsEqualTo class

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

General constraint to compare for equality

Description

The `IsEqualTo` class creates a constraint that compares data for equality. The type of comparison it uses is governed by the data type of the expected value. First, the testing framework checks if the expected value is an object. This check is performed first because it is possible for the object to have overridden methods that are used in subsequent checks (e.g. `islogical`). The following list categorizes and describes the various tests.

Data TypeEquality Comparison Method
MATLAB® & Java® Objects

If the expected value is a MATLAB or Java object, the `IsEqualTo` constraint calls the `isequaln` method if it is defined on the expected value object, otherwise it calls `isequal`. If the check returns false and a supported tolerance is specified, the `IsEqualTo` constraint checks the actual and expected values for equivalent class, size, and sparsity before determining if the values are within the tolerance.

Logicals

If the expected value is a `logical`, the constraint checks the actual and expected values for equivalent sparsity. If the sparsity matches, the constraint compares the values with the `isequal` method. Otherwise, the constraint is not satisfied.

Numerics

If the expected value is `numeric`, the constraint checks the actual and expected values for equivalent class, size, and sparsity. If the all these checks match, the constraint uses the `isequaln` method for comparison. If `isequaln` returns `true`, the constraint is satisfied. If the complexity does not match or `isequaln` returns `false`, and a supported tolerance is supplied, the constraint uses the tolerance in the comparison. Otherwise, the constraint is not satisfied.

Strings

If the expected value is a `string`, the constraint uses the `strcmp` function to check the actual and expected values for equality. However, if the `IgnoreCase` property is true, the strings are compared using `strcmpi`. If the `IgnoreWhitespace` is `true`, all whitespace characters are removed from the actual and expected strings before passing them to `strcmp` or `strcmpi`.

Structures

If the expected value is a `struct`, the constraint compares the field count of the actual and expected values. If not equal, the constraint is not satisfied. Otherwise, each field of the expected value `struct` must exist on the actual value `struct`. If any field names are different, the constraint is not satisfied. Then, the constraint recursively compares the fields in a depth first examination. The recursion continues until a fundamental data type is encountered (that is, logical, numeric, string, or object), and then the values are compared as described above.

Cell Arrays

If the expected value is a cell array, the constraint checks the actual and expected values for size equality. If they are not equal in size, the constraint is not satisfied. Otherwise, each element of the array is recursively compared in a manner identical to fields in a structure, described above.

Tables

If the expected value is a `table`, the actual and expected values are checked for class equality, size equality, and for equal table properties. If they are not equal in class, size, or table properties, the constraint is not satisfied. Then, the constraint recursively compares each row of the table in a depth first examination. The recursion continues until a fundamental data type is encountered (that is, logical, numeric, string, or object), and then the values are compared as described above.

Construction

`IsEqualTo(expVal)` provides a general constraint to compare for equality.

`IsEqualTo(expVal,Name,Value)` provides a constraint with additional options specified by one or more `Name,Value` pair arguments. `Name` must appear inside single quotes (`''`). You can specify several name-value pair arguments in any order as `Name1,Value1,...,NameN,ValueN`.

Input Arguments

 `expVal` The expected value that is compared to the actual value.

Name-Value Pair Arguments

Specify optional comma-separated pairs of `Name,Value` arguments. `Name` is the argument name and `Value` is the corresponding value. `Name` must appear inside single quotes (`' '`). You can specify several name and value pair arguments in any order as `Name1,Value1,...,NameN,ValueN`.

 `'IgnoringCase'` Indicator if the constraint is insensitive to case, specified as `false` or `true` (`logical` `0` or `1`) Default: `false` `'IgnoringFields'` Fields to ignore during struct comparison, specified as a cell array of character vectors. Default: (empty) `'IgnoringWhitespace'` Indicator if the constraint is insensitive to whitespace, specified as `false` or `true` (`logical` `0` or `1`) Default: `false` `'Using'` Particular comparator to use for constraint construction, specified as a `matlab.unittest.constraints.Comparator` object Default: (empty) `'Within'` Tolerance to use in constraint construction, specified as a `matlab.unittest.constraints.Tolerance` object Default: (empty)

Properties

 `Comparator` Specific comparator used in construction of the constraint, specified as a `matlab.unittest.constraints.Comparator` object in the name-value pair argument, `'Using'`. `Expected` The expected value that is compared to the actual value specified in the `expVal` input argument. `IgnoreCase` Indicator if the constraint is insensitive to case, specified in the name-value pair argument, `'IgnoringCase'`. This property applies at all levels of recursion, such as nested structures. `IgnoredFields` Fields to ignore during struct comparison, specified in the name-value pair argument, `'IgnoringFields'`. `IgnoreWhitespace` Indicator if the constraint is insensitive to whitespace, specified in the name-value pair argument, `'IgnoringWhitespace'`. This property applies at all levels of recursion, such as nested structures. `Tolerance` Specific tolerance used in construction of the constraint, specified as a `matlab.unittest.constraints.Tolerance` object in the name-value pair argument, `'Within'`. This property applies at all levels of recursion, such as nested structures.

Copy Semantics

Value. To learn how value classes affect copy operations, see Copying Objects.

Examples

expand all

Create a `TestCase` for interactive testing.

```import matlab.unittest.TestCase import matlab.unittest.constraints.IsEqualTo import matlab.unittest.constraints.AbsoluteTolerance import matlab.unittest.constraints.RelativeTolerance testCase = TestCase.forInteractiveUse;```

Verify that an actual value of 5 is equal to the expected value.

```expVal = 5; testCase.verifyThat(5,IsEqualTo(expVal))```
`Interactive verification passed.`

Assume that the actual value is 4.95. Verify that the difference between the actual value and expected value is less than 0.09.

`testCase.verifyThat(4.95,IsEqualTo(expVal,'Within',AbsoluteTolerance(0.09)))`
`Interactive verification passed.`

Assume that the actual value is 4.9. Verify that the difference between the actual and expected value is less than 1%.

`testCase.verifyThat(4.9,IsEqualTo(expVal,'Within',RelativeTolerance(0.01)))`
```Interactive verification failed. --------------------- Framework Diagnostic: --------------------- IsEqualTo failed. --> NumericComparator failed. --> The values are not equal using "isequaln". --> RelativeTolerance failed. --> The error was not within relative tolerance. --> Failure table: value = 1×5 table array Actual Expected Error RelativeError RelativeTolerance ______ ________ ___________________ ___________________ _________________ 4.9 5 -0.0999999999999996 -0.0199999999999999 0.01 Actual double: 4.900000000000000 Expected double: 5```

The two values differ by more than 1%.

Create a `TestCase` for interactive testing.

```import matlab.unittest.TestCase import matlab.unittest.constraints.IsEqualTo import matlab.unittest.constraints.RelativeTolerance testCase = TestCase.forInteractiveUse;```

Test that `0.1*3 = 0.3`.

```act = 0.1*3; exp = 0.3; testCase.verifyThat(act, IsEqualTo(exp))```
```Interactive verification failed. --------------------- Framework Diagnostic: --------------------- IsEqualTo failed. --> NumericComparator failed. --> The values are not equal using "isequaln". --> Failure table: Actual Expected Error RelativeError ______ ________ ____________________ ____________________ 0.3 0.3 5.55111512312578e-17 1.85037170770859e-16 Actual double: 0.300000000000000 Expected double: 0.300000000000000```

This test fails due to round off error in floating point arithmetic.

Perform the comparison of floating point numbers using a tolerance. Test that `0.1*3 = 0.3` within a relative tolerance of `2*eps`.

```testCase.verifyThat(act, IsEqualTo(exp, ... 'Within', RelativeTolerance(2*eps)))```
`Interactive verification passed.`

Create a `TestCase` for interactive testing.

```import matlab.unittest.TestCase import matlab.unittest.constraints.IsEqualTo testCase = TestCase.forInteractiveUse;```

Verify that two character vectors are equal.

```expVal = 'Hello'; testCase.verifyThat('Hello',IsEqualTo(expVal))```
`Interactive verification passed.`

Change the case of the actual value and test for equality.

`testCase.verifyThat('hello',IsEqualTo(expVal))`
```Interactive verification failed. --------------------- Framework Diagnostic: --------------------- IsEqualTo failed. --> StringComparator failed. --> The character arrays are not equal. Actual char: hello Expected char: Hello```

Ignore case and test again.

`testCase.verifyThat('hello',IsEqualTo(expVal,'IgnoringCase',true))`
`Interactive verification passed.`

Ignore whitespace and test two character vectors.

```expVal = 'a bc'; testCase.verifyThat('abc',IsEqualTo(expVal,'IgnoringWhitespace',true)) testCase.verifyThat('ab c',IsEqualTo(expVal,'IgnoringWhitespace',true))```
```Interactive verification passed. Interactive verification passed.```

Create a test case for interactive testing.

```import matlab.unittest.TestCase import matlab.unittest.constraints.IsEqualTo import matlab.unittest.constraints.RelativeTolerance import matlab.unittest.constraints.PublicPropertyComparator testCase = TestCase.forInteractiveUse;```

Define actual and expected `timeseries` objects. Perturb one of the actual data points by 1%.

```expected = timeseries(1:10); actual = expected; actual.Data(7) = 1.01*actual.Data(7);```

Test that the actual and expected values are equal within a relative tolerance of 2%.

```testCase.verifyThat(actual, IsEqualTo(expected,... 'Within', RelativeTolerance(.02)))```
```Interactive verification failed. --------------------- Framework Diagnostic: --------------------- IsEqualTo failed. --> ObjectComparator failed. --> The objects are not equal using "isequal". --> The tolerance was ignored. The tolerance as specified does not support comparisons of timeseries values. Actual timeseries: timeseries Common Properties: Name: 'unnamed' Time: [10x1 double] TimeInfo: [1x1 tsdata.timemetadata] Data: [1x1x10 double] DataInfo: [1x1 tsdata.datametadata] More properties, Methods Expected timeseries: timeseries Common Properties: Name: 'unnamed' Time: [10x1 double] TimeInfo: [1x1 tsdata.timemetadata] Data: [1x1x10 double] DataInfo: [1x1 tsdata.datametadata] More properties, Methods```

Use the `PublicPropertyComparator` in the construction of the constraint.

```testCase.verifyThat(actual, IsEqualTo(expected,... 'Within', RelativeTolerance(.02),... 'Using', PublicPropertyComparator.supportingAllValues))```
`Interactive verification passed.`

The test passes because the `PublicPropertyComparator` compares each public property individually instead of comparing the object all at once. In the former test, the `ObjectComparator` compares `timeseries` objects, and therefore relies on the `isequal` method of the `timeseries` class. Due to the perturbation in the actual `timeseries`, `isequal` returns `false`. The comparator does not apply the tolerance because the double-valued tolerance cannot apply directly to the `timeseries` object. In the latter test, the comparator applies the tolerance to each public property that contains double-valued data.