Main Content

matlab.automation.diagnostics.Diagnostic Class

Namespace: matlab.automation.diagnostics

Fundamental interface for diagnostics

Renamed from matlab.unittest.diagnostics.Diagnostic in R2023a

expand all in page

Description

The matlab.automation.diagnostics.Diagnostic class provides an interface that you can use to package diagnostic information. All diagnostics are derived from the Diagnostic class, whether they are user-supplied diagnostics or framework diagnostics. Diagnostic subclasses encode the diagnostic actions to be performed and produce a diagnostic result that can be used by an automation framework, such as the unit testing framework, and displayed as appropriate for that framework.

To create a custom diagnostic class:

  • Derive your class from matlab.automation.diagnostics.Diagnostic.

  • Implement the diagnose method to encode the diagnostic actions to be performed.

  • Set the DiagnosticText property within the diagnose method to make information available to consumers of the diagnostic.

When used with the testing framework, any Diagnostic implementation can be used directly with the matlab.unittest.qualifications qualification methods, which perform the diagnostic actions and store the result to be used by the framework. As a convenience, the framework creates appropriate Diagnostic instances for user-supplied diagnostics that are string arrays, character arrays, or function handles. To retain good performance, the framework converts these values to Diagnostic instances only when needed, typically in the event of a test failure.

The matlab.automation.diagnostics.Diagnostic class is a handle class.

Class Attributes

Abstract
true

For information on class attributes, see Class Attributes.

Properties

expand all

Artifacts produced during the latest diagnostic evaluation, returned as a row vector of artifacts. The data type of the artifacts depends on the diagnostic evaluation. For example, if the diagnostic evaluation results in capturing screenshots, the property contains the screenshots as a row vector of matlab.automation.diagnostics.FileArtifact objects.

Attributes:

GetAccess
public
SetAccess
Restricts access

Text used to communicate diagnostic information, returned as a character vector. Set this property within the diagnose method in your custom diagnostic class implementation.

The DiagnosticText property makes information available to consumers of diagnostics, such as testing frameworks.

Attributes:

GetAccess
public
SetAccess
protected

Methods

expand all

Examples

collapse all

Create a custom diagnostic that provides the status of the active processes. Classes that define diagnostics must derive from matlab.automation.diagnostics.Diagnostic, implement the diagnose method, and set the DiagnosticText property.

In a file named ProcessStatusDiagnostic.m in your current folder, create the ProcessStatusDiagnostic class by subclassing matlab.automation.diagnostics.Diagnostic. Add these elements to the class:

  • HeaderText property — Add this property to customize the diagnostic text during diagnostic construction.

  • ProcessStatusDiagnostic method — Implement this constructor method to set the HeaderText property.

  • diagnose method — Implement this method to encode the diagnostic actions. Access the process status information and use this information to set the DiagnosticText property.

classdef ProcessStatusDiagnostic < matlab.automation.diagnostics.Diagnostic
    properties (SetAccess=immutable)
        HeaderText
    end

    methods
        function diagnostic = ProcessStatusDiagnostic(header)
            arguments
                header (1,1) string = "Process Status Information"
            end
            diagnostic.HeaderText = header;
        end

        function diagnose(diagnostic)
            [~,processInfo] = system("ps");
            diagnostic.DiagnosticText = diagnostic.HeaderText + ...
                newline + processInfo;
        end
    end
end

Create a test case for interactive testing.

testCase = matlab.unittest.TestCase.forInteractiveUse;

To display custom diagnostic information when a test fails, pass a ProcessStatusDiagnostic object to your qualification method.

testCase.verifyFail(ProcessStatusDiagnostic)
Verification failed.
    ----------------
    Test Diagnostic:
    ----------------
    Process Status Information
          PID    PPID    PGID     WINPID   TTY         UID    STIME COMMAND
        22488       1   22488      22488  ?        2964717 10:24:31 /usr/bin/ps

Customize the diagnostic text by specifying the optional input when you create a ProcessStatusDiagnostic object.

testCase.verifyFail(ProcessStatusDiagnostic("Status of Active Processes"))
Verification failed.
    ----------------
    Test Diagnostic:
    ----------------
    Status of Active Processes
          PID    PPID    PGID     WINPID   TTY         UID    STIME COMMAND
        22828       1   22828      22828  ?        2964717 10:24:53 /usr/bin/ps

Version History

Introduced in R2013a

expand all

See Also

Classes

Topics