matlab.unittest.diagnostics.ConstraintDiagnostic Class
Namespace: matlab.unittest.diagnostics
Superclasses: matlab.automation.diagnostics.Diagnostic
Diagnostic with fields common to constraints
Description
The matlab.unittest.diagnostics.ConstraintDiagnostic
class provides a
diagnostic with fields that are common to constraints. These fields include the description,
conditions, actual value, and expected value. For more information, see Diagnostic Fields.
The ConstraintDiagnostic
class provides a convenient way to add a common
look and feel to diagnostics produced by your custom constraints. You can use
ConstraintDiagnostic
objects to implement the
getDiagnosticFor
method of Constraint
subclasses or the getNegativeDiagnosticFor
method of
BooleanConstraint
subclasses.
The matlab.unittest.diagnostics.ConstraintDiagnostic
class is a handle
class.
Creation
Description
diag = matlab.unittest.diagnostics.ConstraintDiagnostic
creates a
ConstraintDiagnostic
object. You can then set properties of the object to
customize the constraint diagnostic.
Properties
In addition to the following properties, the ConstraintDiagnostic
class
inherits the Artifacts
and DiagnosticText
properties
from the Diagnostic
class.
Description
— General diagnostic information
string scalar | character vector
General diagnostic information, specified as a string scalar or character vector.
Attributes:
GetAccess | public |
SetAccess | public |
DisplayDescription
— Option to display description
false
or 0
(default) | true
or 1
Option to display the text in the Description
property,
specified as a numeric or logical 0
(false
) or
1
(true
). By default, the constraint does not
display the description.
Attributes:
GetAccess | public |
SetAccess | public |
Conditions
— Formatted list of conditions
character vector
Formatted list of conditions, returned as a character vector. When the framework
displays the diagnostic, each condition starts on a new line and begins with an arrow
(-->
) delimiter.
A condition contains information specific to the cause of the test failure and acts
as a “subdiagnostic.” Add conditions to the list using the
addCondition
and addConditionsFrom
methods.
Attributes:
GetAccess | public |
SetAccess | private |
ConditionsCount
— Number of conditions in condition list
nonegative integer scalar
Number of conditions in the condition list stored in the
Conditions
property, returned as a nonegative integer
scalar.
Attributes:
GetAccess | public |
SetAccess | private |
Data Types: double
DisplayConditions
— Option to display condition list
false
or 0
(default) | true
or 1
Option to display the condition list in the Conditions
property, specified as a numeric or logical 0
(false
) or 1
(true
). By
default, the constraint does not display the condition list.
Attributes:
GetAccess | public |
SetAccess | public |
ActVal
— Actual value
any value
Actual value to test, specified as a value of any data type.
Attributes:
GetAccess | public |
SetAccess | public |
ActValHeader
— Header information for actual value
'Actual Value:'
(default) | string scalar | character vector
Header information for the actual value, specified as a string scalar or character vector.
Attributes:
GetAccess | public |
SetAccess | public |
DisplayActVal
— Option to display actual value
false
or 0
(default) | true
or 1
Option to display the actual value and its header information, specified as a
numeric or logical 0
(false
) or
1
(true
). By default, the constraint does not
display the actual value.
Attributes:
GetAccess | public |
SetAccess | public |
ExpVal
— Expected value
any value
Expected value, if applicable, specified as a value of any data type.
Attributes:
GetAccess | public |
SetAccess | public |
ExpValHeader
— Header information for expected value
'Expected Value:'
(default) | string scalar | character vector
Header information for the expected value, specified as a string scalar or character vector.
Attributes:
GetAccess | public |
SetAccess | public |
DisplayExpVal
— Option to display expected value
false
or 0
(default) | true
or 1
Option to display the expected value and its header information, specified as a
numeric or logical 0
(false
) or
1
(true
). By default, the constraint does not
display the expected value.
Attributes:
GetAccess | public |
SetAccess | public |
Methods
Public Methods
In addition to the following methods, the ConstraintDiagnostic
class
inherits the diagnose
and
matlab.automation.diagnostics.Diagnostic.join
methods from the Diagnostic
class.
addCondition |
Add
the condition Input Arguments
|
addConditionsFrom |
Add
all the conditions from another Input Arguments
|
matlab.unittest.diagnostics.ConstraintDiagnostic.getDisplayableString |
Convert
Input Arguments
Output Arguments
|
Protected Methods
You can override these protected methods in ConstraintDiagnostic
subclasses to add more fields to the diagnostic. The framework calls these methods to obtain
fields and inject them into the diagnostic result at the locations specified by the methods.
Each method returns an empty character vector unless overridden.
getPreDescriptionString |
Return
the text to be displayed before the description. Override this method to display
text before the Input Arguments
Output Arguments
|
getPostDescriptionString |
Return
the text to be displayed after the description. Override this method to display
text after the Input Arguments
Output Arguments
|
getPostConditionsString |
Return
the text to be displayed after the condition list. Override this method to display
text after the Input Arguments
Output Arguments
|
getPostActValString |
Return
the text to be displayed after the actual value. Override this method to display
text after the Input Arguments
Output Arguments
|
getPostExpValString |
Return
the text to be displayed after the expected value. Override this method to display
text after the Input Arguments
Output Arguments
|
Examples
Produce Constraint Diagnostic
Create a custom constraint that determines if a value is the same
size as an expected value. To produce diagnostic information for the constraint, implement
its getDiagnosticFor
method by using the
ConstraintDiagnostic
class.
In a file in your current folder, create a class named IsSameSizeAs
that derives from matlab.unittest.constraints.Constraint
, and
implement the satisfiedBy
and getDiagnosticFor
methods. To implement the getDiagnosticFor
method, use instances of the
ConstraintDiagnostic
class. The ConstraintDiagnostic
class provides a convenient way to customize various diagnostic fields for passing or
failing tests.
classdef IsSameSizeAs < matlab.unittest.constraints.Constraint properties (SetAccess=immutable) ValueWithExpectedSize end methods function constraint = IsSameSizeAs(value) constraint.ValueWithExpectedSize = value; end function tf = satisfiedBy(constraint,actual) tf = constraint.sizeMatchesExpected(actual); end function diagnostic = getDiagnosticFor(constraint,actual) if constraint.sizeMatchesExpected(actual) diagnostic = diagnosticForPassingTest; else diagnostic = diagnosticForFailingTest(constraint,actual); end end end methods (Access=private) function tf = sizeMatchesExpected(constraint,actual) tf = isequal(size(actual), ... size(constraint.ValueWithExpectedSize)); end function diag = diagnosticForPassingTest(~,~) import matlab.unittest.diagnostics.ConstraintDiagnostic diag = ConstraintDiagnostic; diag.DisplayDescription = true; diag.Description = "IsSameSizeAs passed."; end function diag = diagnosticForFailingTest(constraint,actual) import matlab.unittest.diagnostics.ConstraintDiagnostic diag = ConstraintDiagnostic; diag.DisplayDescription = true; diag.Description = "IsSameSizeAs failed."; diag.DisplayConditions = true; diag.addCondition("Sizes did not match.") diag.DisplayActVal = true; diag.ActValHeader = "Actual Size:"; diag.ActVal = size(actual); diag.DisplayExpVal = true; diag.ExpValHeader = "Expected Size:"; diag.ExpVal = size(constraint.ValueWithExpectedSize); end end end
Create a test case for interactive testing.
testCase = matlab.unittest.TestCase.forInteractiveUse;
Test a failing case. The framework displays the constraint diagnostic implemented in
the diagnosticForFailingTest
helper method.
testCase.verifyThat(zeros(5),IsSameSizeAs(ones(1,5)))
Verification failed. --------------------- Framework Diagnostic: --------------------- IsSameSizeAs failed. --> Sizes did not match. Actual Size: 5 5 Expected Size: 1 5
Display Text Before Diagnostic Description
Create a constraint diagnostic that injects text before the description field of the diagnostic.
In a file in your current folder, create a class named
CustomConstraintDiagnostic
that derives from
matlab.unittest.diagnostics.ConstraintDiagnostic
. Implement the
getPreDescriptionString
method that the custom diagnostic class
inherits from its superclass to inject text before the optional description field of the
diagnostic.
classdef CustomConstraintDiagnostic < ... matlab.unittest.diagnostics.ConstraintDiagnostic properties (SetAccess=immutable) Context end methods function diag = CustomConstraintDiagnostic(context) arguments context (1,1) string = "Test Outcome Information" end diag.Context = context; end end methods (Access=protected) function str = getPreDescriptionString(diag) str = diag.Context; end end end
Import the classes used in this example.
import matlab.unittest.TestCase import matlab.unittest.constraints.IsEqualTo
Create a constraint diagnostic by instantiating the
CustomConstraintDiagnostic
class.
diagnostic = CustomConstraintDiagnostic;
diagnostic.DisplayDescription = true;
diagnostic.Description = "My Custom Diagnostic";
In practice, you typically use constraint diagnostics to implement custom
constraints. To simplify this example, create a test case for interactive testing, and
display diagnostic information upon a test failure by using the
CustomConstraintDiagnostic
object. The framework displays both the
specified description and the default text injected before the description.
testCase = TestCase.forInteractiveUse; testCase.verifyThat(1,IsEqualTo(2),diagnostic)
Verification failed. ---------------- Test Diagnostic: ---------------- Test Outcome Information My Custom Diagnostic --------------------- Framework Diagnostic: --------------------- IsEqualTo failed. --> NumericComparator failed. --> The numeric values are not equal using "isequaln". --> Failure table: Actual Expected Error RelativeError ______ ________ _____ _____________ 1 2 -1 -0.5 Actual Value: 1 Expected Value: 2
More About
Diagnostic Fields
A constraint diagnostic consists of the following text fields, which are displayed in this order:
Description — General diagnostic information.
Conditions — Formatted list of conditions that describe the causes of the failure. Each condition starts on a new line and begins with an arrow (
-->
) delimiter.Actual Value — Actual value associated with the constraint. The text might be truncated or formatted for proper display.
Expected Value — Expected value associated with the constraint (if applicable).
The ConstraintDiagnostic
class inherits the diagnose
method from matlab.automation.diagnostics.Diagnostic
and implements it to construct the
constraint diagnostic using these fields.
Version History
Introduced in R2013a
MATLAB Command
You clicked a link that corresponds to this MATLAB command:
Run the command by entering it in the MATLAB Command Window. Web browsers do not support MATLAB commands.
Select a Web Site
Choose a web site to get translated content where available and see local events and offers. Based on your location, we recommend that you select: .
You can also select a web site from the following list:
How to Get Best Site Performance
Select the China site (in Chinese or English) for best site performance. Other MathWorks country sites are not optimized for visits from your location.
Americas
- América Latina (Español)
- Canada (English)
- United States (English)
Europe
- Belgium (English)
- Denmark (English)
- Deutschland (Deutsch)
- España (Español)
- Finland (English)
- France (Français)
- Ireland (English)
- Italia (Italiano)
- Luxembourg (English)
- Netherlands (English)
- Norway (English)
- Österreich (Deutsch)
- Portugal (English)
- Sweden (English)
- Switzerland
- United Kingdom (English)