Main Content

matlab.unittest.diagnostics.FigureDiagnostic class

Package: matlab.unittest.diagnostics

Diagnostic to save specified figure

expand all in page

Description

Use the FigureDiagnostic class to create a diagnostic that saves a figure to a file. The file persists after MATLAB® completes the test run, and so it is available for post-test inspection.

Construction

FigureDiagnostic(fig) creates a diagnostic to save a specified figure. When the testing framework diagnoses the FigureDiagnostic instance, it saves fig to a FIG file and to 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 file name is Figure_cf95fe7f-5a7c-4310-9c19-16c0c17a969f.png. To view the location of the file, access the FileArtifact object through the TestResult instance.

FigureDiagnostic(fig,Name,Value) creates a diagnostic with additional options specified by one or more Name,Value pair arguments. You can specify several name-value pair arguments in any order as Name1,Value1,...,NameN,ValueN. For example, FigureDiagnostic(fig,'Prefix','LoggedFigure_','Formats','png') saves fig as a PNG file only, and uses the prefix 'LoggedFigure_' instead of 'Figure_'.

Input Arguments

expand all

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

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.

Before R2021a, use commas to separate each name and value, and enclose Name in quotes.

Example: FigureDiagnostic(testFig,'Formats','fig')

File format of figure, specified as ["fig" "png"], "fig", or "png". You can specify these values as character vectors, as {'fig','png'}, 'fig', or 'png'. Within the object, MATLAB stores them as strings.

File name prefix, specified as text. If you do not specify a prefix, the default prefix is 'Figure_'. Specify the value as a character vector or string scalar. Within the object, MATLAB stores it as character vectors.

Example: 'LoggedFigure_'

Example: "TestFig-"

Properties

expand all

Figure to save when the testing framework diagnoses the FigureDiagnostic instance, returned as a Figure object. The Figure property is read-only, and its value is set during construction.

File format for the saved figure, returned as ["fig" "png"], "fig", or "png". The Formats property is read-only, and its value is set during construction.

File name prefix, returned as a character vector. The default prefix is 'Figure_'. The Prefix property is read-only, and its value is set during construction.

Copy Semantics

Handle. To learn how handle classes affect copy operations, see Copying Objects.

Examples

collapse all

Create a TestCase for interactive use.

import matlab.unittest.TestCase
testCase = TestCase.forInteractiveUse;

Create a figure.

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

Use a FigureDiagnostic to save the figure as a test diagnostic. Verify that the figure has no children. This qualification fails and MATLAB displays the test diagnostic.

import matlab.unittest.diagnostics.FigureDiagnostic
testCase.verifyEmpty(fig.Children,FigureDiagnostic(fig))
Interactive verification failed.

----------------
Test Diagnostic:
----------------
Figure saved to:
--> C:\work\Temp\Figure_0b3da19f-5248-442b-aebf-3fb6d707fd1b.fig
--> C:\work\Temp\Figure_0b3da19f-5248-442b-aebf-3fb6d707fd1b.png

---------------------
Framework Diagnostic:
---------------------
verifyEmpty failed.
--> The value must be empty.
--> The value has a size of [1  1].

Actual matlab.graphics.axis.Axes:
      Axes with properties:
    
                 XLim: [0 50]
                 YLim: [0 60]
               XScale: 'linear'
               YScale: 'linear'
        GridLineStyle: '-'
             Position: [0.130000000000000 0.110000000000000 0.775000000000000 0.815000000000000]
                Units: 'normalized'
    
      Use get to show all properties

Create a TestCase for interactive use.

import matlab.unittest.TestCase
testCase = TestCase.forInteractiveUse;

Create a figure.

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

Use a FigureDiagnostic to log the figure as a test diagnostic. Save the file only as a PNG and use a custom prefix for the file name.

import matlab.unittest.diagnostics.FigureDiagnostic
testCase.log(FigureDiagnostic(fig,'Formats','png','Prefix','LoggedFigure_'))
Interactive diagnostic logged.
Figure saved to:
--> C:\work\Temp\LoggedFigure_0a02faa1-3e14-4783-9954-b56caa6b326d.png

In a file in your current working folder, create the FigurePropTest test class. If the failingTest test method fails (it always does in this example), it uses a FigureDiagnostic to save the figure so you can examine it later.

classdef FigurePropTest < matlab.unittest.TestCase
    properties
        TestFigure
    end
    methods (TestMethodSetup)
        function createFigure(testCase)
            testCase.TestFigure = figure;
        end
    end
    methods (TestMethodTeardown)
        function closeFigure(testCase)
            close(testCase.TestFigure)
        end
    end
    methods (Test)
        function defaultCurrentPoint(testCase)
            cp = testCase.TestFigure.CurrentPoint;
            testCase.verifyEqual(cp,[0 0], ...
                'Default current point is incorrect')
        end
        function defaultCurrentObject(testCase)
            import matlab.unittest.constraints.IsEmpty
            co = testCase.TestFigure.CurrentObject;
            testCase.verifyThat(co,IsEmpty, ...
                'Default current object should 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

At the command prompt, create a test suite.

suite = testsuite('FigurePropTest');

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

import matlab.unittest.plugins.DiagnosticsRecordingPlugin
import matlab.unittest.plugins.TestReportPlugin
runner = matlab.unittest.TestRunner.withNoPlugins;
runner.addPlugin(DiagnosticsRecordingPlugin)
runner.addPlugin(TestReportPlugin.producingPDF('MyTestReport.pdf'))

Change the default artifact root to your current working folder.

runner.ArtifactsRootFolder = pwd;

Run the tests. The third test 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:\wok\MyTestReport.pdf

results = 

  1×3 TestResult array with properties:

    Name
    Passed
    Failed
    Incomplete
    Duration
    Details

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

Display the test diagnostic results for the third test. The testing framework saved two artifacts related to the third test. By default, a FigureDiagnostic object saves a figure as both a PNG file and a FIG file.

results(3).Details.DiagnosticRecord.TestDiagnosticResults
ans = 

  DiagnosticResult with properties:

         Artifacts: [1×2 matlab.automation.diagnostics.FileArtifact]
    DiagnosticText: 'Figure saved to:↵--> C:\work\530aa31c-86c7-4712-a064-d9f00ce041fb\Figure_dfd8c611-8387-4579-804f-6384642ba4ff.fig↵--> C:\work\530aa31c-86c7-4712-a064-d9f00ce041fb\Figure_dfd8c611-8387-4579-804f-6384642ba4ff.png'

Display the stored location of the first artifact.

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

  FileArtifact with properties:

        Name: "Figure_dfd8c611-8387-4579-804f-6384642ba4ff.fig"
    Location: "C:\work\530aa31c-86c7-4712-a064-d9f00ce041fb"
    FullPath: "C:\work\530aa31c-86c7-4712-a064-d9f00ce041fb\Figure_dfd8c611-8387-4579-804f-6384642ba4ff.fig"

To inspect the image related to the failed test, open the file at the location shown in the FullPath field. Additionally, since you generated a PDF test report, the image is captured in MyTestReport.pdf. The test report also contains the path to the artifacts.

Tips

  • The location of the saved figure is a folder with a name unique to a test run within the folder contained in the ArtifactsRootFolder. If you are running a test without a TestRunner, for example with matlab.unittest.TestCase.forInteractiveUse, the root folder is the value returned by tempdir().

  • To determine the path of the saved figure, access the FileArtifact object for a particular test result. For example, assume that res is a TestResult array. Determine the location of the saved figure for the first element of the array as follows.

    res(1).Details.DiagnosticRecord.TestDiagnosticResults.Artifacts
    ans = 

  FileArtifact with properties:

        Name: "Figure_3984704d-b884-44c2-b3ee-7ed10d36e967.png"
    Location: "C:\mywork\Temp\a1f80242-8f8a-4678-9124-415980432d08"
    FullPath: "C:\mywork\Temp\a1f80242-8f8a-4678-9124-415980432d08\Figure_3984704d-b884-44c2-b3ee-7ed10d36e967.png"

Version History

Introduced in R2017a

See Also

|