matlab.unittest.diagnostics.FigureDiagnostic Class

Namespace: matlab.unittest.diagnostics
Superclasses: matlab.automation.diagnostics.Diagnostic

Diagnostic to save specified figure

Description

Use the matlab.unittest.diagnostics.FigureDiagnostic class to create a diagnostic for saving a MATLAB^® figure during a test run. The saved figure persists after the test run and is available for post-test inspection.

The matlab.unittest.diagnostics.FigureDiagnostic class is a handle class.

Creation

Description

diag = matlab.unittest.diagnostics.FigureDiagnostic(fig) creates a diagnostic to save the specified figure. When the testing framework diagnoses the FigureDiagnostic object, the framework saves fig as both a FIG file and a PNG file. Each file has a unique name consisting of a prefix ("Figure_", by default), an automatically generated identifier, and the file extension. An example filename is Figure_cf95fe7f-5a7c-4310-9c19-16c0c17a969f.png. To view the location of the saved figure, access the FileArtifact object through the corresponding TestResult instance.

diag = matlab.unittest.diagnostics.FigureDiagnostic(fig,Name=Value) specifies additional options using one or more name-value arguments. For example, diag = matlab.unittest.diagnostics.FigureDiagnostic(fig,Formats="png") saves the specified figure as a PNG file only.

Input Arguments

fig — Figure to save

Figure object

Figure to save when the testing framework diagnoses the FigureDiagnostic object, specified as a Figure object created with either the figure or uifigure function.

This argument sets the Figure property.

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: diag = matlab.unittest.diagnostics.FigureDiagnostic(fig,Formats="png")

Formats — File formats for saved figure

["fig" "png"] (default) | "fig" | "png"

File formats for the saved figure, specified as a string vector, character vector, or cell vector of character vectors. By default, the framework saves the figure as both a FIG file and a PNG file. To save the figure as a single file instead, specify Formats as "fig" or "png".

This argument sets the Formats property.

Data Types: string | char | cell

Prefix — Filename prefix

"Figure_" (default) | string scalar | character vector

Filename prefix, specified as a string scalar or character vector. If you do not specify a prefix, the FIG and PNG filenames start with "Figure_".

This argument sets the Prefix property.

Example: Prefix="LoggedFigure_"

Example: Prefix="TestFig-"

Properties

In addition to these properties, the FigureDiagnostic class inherits properties from the Diagnostic class.

Figure — Figure to save

Figure object

Figure to save when the testing framework diagnoses the FigureDiagnostic object, specified as a Figure object. You must set the Figure property during diagnostic creation.

Attributes:

GetAccess	public
SetAccess	immutable

Formats — File formats for saved figure

["fig" "png"] (default) | string vector | character vector | cell vector of character vectors

File formats for the saved figure, specified as a string vector, character vector, or cell vector of character vectors, and stored as a string vector. By default, the value is ["fig" "png"], and the framework saves the figure as both a FIG file and a PNG file. To save the figure as a single file instead, set the Formats property to "fig" or "png" during diagnostic creation.

Attributes:

GetAccess	public
SetAccess	private

Prefix — Filename prefix

'Figure_' (default) | string scalar | character vector

Filename prefix, specified as a string scalar or character vector, and stored as a character vector. By default, the value is 'Figure_'. You can set the Prefix property during diagnostic creation.

Attributes:

GetAccess	public
SetAccess	private

Examples

Save Figure When Test Fails

Import the FigureDiagnostic class.

import matlab.unittest.diagnostics.FigureDiagnostic

Create a figure that includes a surface plot.

fig = figure;
ax = axes(fig);
surf(ax,peaks)

Create a test case for interactive testing.

testCase = matlab.unittest.TestCase.forInteractiveUse;

Test whether the figure has no children, and use a FigureDiagnostic object to save the figure as a test diagnostic. Because the test fails, the Command Window displays the diagnostics, including links to the generated FIG and PNG files.

testCase.verifyEmpty(fig.Children,FigureDiagnostic(fig))

Verification failed.
    ----------------
    Test Diagnostic:
    ----------------
    Figure saved to:
    --> C:\Users\username\AppData\Local\Temp\Figure_2a9642a0-6709-4055-92cc-50db0b0b68ad.fig
    --> C:\Users\username\AppData\Local\Temp\Figure_2a9642a0-6709-4055-92cc-50db0b0b68ad.png
    ---------------------
    Framework Diagnostic:
    ---------------------
    verifyEmpty failed.
    --> The value must be empty.
    --> The value has a size of [1  1].
    
    Actual Value:
      Axes with properties:
    
                 XLim: [0 50]
                 YLim: [0 50]
               XScale: 'linear'
               YScale: 'linear'
        GridLineStyle: '-'
             Position: [0.130000000000000 0.110000000000000 0.775000000000000 0.815000000000000]
                Units: 'normalized'
    
      Use get to show all properties

Specify File Format and Filename Prefix

Import the FigureDiagnostic class.

import matlab.unittest.diagnostics.FigureDiagnostic

Create a figure that includes a surface plot.

fig = uifigure;
ax = axes(fig);
surf(ax,membrane(6))

Create a test case for interactive testing.

testCase = matlab.unittest.TestCase.forInteractiveUse;

Use a FigureDiagnostic object to log the figure as a test diagnostic. Customize the object so that the framework saves the figure only as a PNG file and uses "LoggedFigure_" as the filename prefix.

testCase.log(FigureDiagnostic(fig,Formats="png",Prefix="LoggedFigure_"))

[Concise] Diagnostic logged (2025-12-22 14:36:09):
Figure saved to:
--> C:\Users\username\AppData\Local\Temp\LoggedFigure_e8405833-21a2-4368-b123-adb2cab2e1b6.png

Create Test Report That Includes Artifacts

In a file named FigurePropertiesTest.m in your current folder, create the FigurePropertiesTest test class. The failingTest method of the test class, which intentionally fails, uses a FigureDiagnostic object to save the figure so you can examine it later.

classdef FigurePropertiesTest < matlab.unittest.TestCase
    properties
        TestFigure
    end

    methods (TestMethodSetup)
        function createFigure(testCase)
            testCase.TestFigure = figure;
            testCase.addTeardown(@close,testCase.TestFigure)
        end
    end

    methods (Test)
        function defaultCurrentPoint(testCase)
            cp = testCase.TestFigure.CurrentPoint;
            testCase.verifyEqual(cp,[0 0], ...
                "Default current point must be [0 0].")
        end

        function defaultCurrentObject(testCase)
            import matlab.unittest.constraints.IsEmpty
            co = testCase.TestFigure.CurrentObject;
            testCase.verifyThat(co,IsEmpty, ...
                "Default current object must be empty.")
        end

        function failingTest(testCase)
            import matlab.unittest.diagnostics.FigureDiagnostic
            fig = testCase.TestFigure;
            ax = axes(fig);
            surf(ax,peaks)
            testCase.verifyEmpty(testCase.TestFigure.Children, ...
                FigureDiagnostic(testCase.TestFigure))
        end
    end
end

Import the classes used in this example.

import matlab.unittest.plugins.DiagnosticsRecordingPlugin
import matlab.unittest.plugins.TestReportPlugin

Create a test suite from the test class.

suite = testsuite("FigurePropertiesTest");

Create a test runner that records diagnostics and generates a PDF test report.

runner = testrunner("minimal");
runner.addPlugin(DiagnosticsRecordingPlugin)
runner.addPlugin(TestReportPlugin.producingPDF("report.pdf"))

Set the ArtifactsRootFolder property of the test runner so that the framework saves any diagnostic artifacts produced during the test run to your current folder.

runner.ArtifactsRootFolder = pwd;

Run the tests in the test suite. One of the tests fails.

results = runner.run(suite)

Generating test report. Please wait.
    Preparing content for the test report.
    Adding content to the test report.
    Writing test report to file.
Test report has been saved to:
 C:\work\report.pdf

results = 

  1×3 TestResult array with properties:

    Name
    Passed
    Failed
    Incomplete
    Duration
    Details

Totals:
   2 Passed, 1 Failed (rerun), 0 Incomplete.
   1.6241 seconds testing time.

Display the diagnostic result for the failed test. The returned DiagnosticResult object indicates that the framework saved two artifacts related to the third test. By default, a FigureDiagnostic object results in both a FIG file and a PNG file.

results(3).Details.DiagnosticRecord.TestDiagnosticResults

ans = 

  DiagnosticResult with properties:

         Artifacts: [1×2 matlab.automation.diagnostics.FileArtifact]
    DiagnosticText: 'Figure saved to:↵--> C:\Users\username\AppData\Local\Temp\817b4071-9d9d-471e-bead-eb0f93a89f1b\Figure_c79a5df0-04fc-4ebc-9eb6-920b23feba40.fig↵--> C:\Users\username\AppData\Local\Temp\817b4071-9d9d-471e-bead-eb0f93a89f1b\Figure_c79a5df0-04fc-4ebc-9eb6-920b23feba40.png'

Display the location of the first artifact. To inspect the image related to the failed test, open the file at the location shown in the FullPath property. The generated PDF test report also includes the captured image and the artifact paths.

results(3).Details.DiagnosticRecord.TestDiagnosticResults.Artifacts(1)

ans = 

  FileArtifact with properties:

        Name: "Figure_c79a5df0-04fc-4ebc-9eb6-920b23feba40.fig"
    Location: "C:\Users\username\AppData\Local\Temp\817b4071-9d9d-471e-bead-eb0f93a89f1b"
    FullPath: "C:\Users\username\AppData\Local\Temp\817b4071-9d9d-471e-bead-eb0f93a89f1b\Figure_c79a5df0-04fc-4ebc-9eb6-920b23feba40.fig"

Tips

• The location of the saved figure is a folder with a name unique to a test run within the artifacts root folder (specified in the ArtifactsRootFolder property of the test runner). If you run tests interactively, the location is the value returned by tempdir.

• To determine the path of a saved figure, access the FileArtifact object for a particular test result. For example, suppose that the variable results represents your TestResult array. This code determines the location of the generated FIG file for the second test result.

  results(2).Details.DiagnosticRecord.TestDiagnosticResults.Artifacts(1)

  ans = 
  
    FileArtifact with properties:
  
          Name: "Figure_3984704d-b884-44c2-b3ee-7ed10d36e967.fig"
      Location: "C:\Users\username\AppData\Local\Temp\a1f80242-8f8a-4678-9124-415980432d08"
      FullPath: "C:\Users\username\AppData\Local\Temp\a1f80242-8f8a-4678-9124-415980432d08\Figure_3984704d-b884-44c2-b3ee-7ed10d36e967.fig"

Version History

Introduced in R2017a