matlab.unittest.diagnostics.ScreenshotDiagnostic Class

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

Diagnostic to capture screens as image files

expand all in page

Description

Use the matlab.unittest.diagnostics.ScreenshotDiagnostic class to create a diagnostic for capturing available screens as image (PNG) files during a test run. The screenshots persist after the test run and are available for post-test inspection.

Note

The number of PNG files produced by a ScreenshotDiagnostic object depends on the operating system:

  • On Windows® and Linux® systems, the testing framework generates a single PNG file, regardless of the number of available screens.

  • On macOS systems, the framework generates one PNG file for each available screen.

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

Creation

Description

diag = matlab.unittest.diagnostics.ScreenshotDiagnostic creates a diagnostic to capture available screens as image files. When the testing framework diagnoses the ScreenshotDiagnostic object, the framework saves the screenshots to one or more PNG files. A generated PNG file has a unique name consisting of a prefix ("Screenshot_", by default), an automatically generated identifier, and the file extension. An example filename is Screenshot_cf95fe7f-5a7c-4310-9c49-16c0c18a969f.png. To view the location of the screenshots, access the FileArtifact object through the corresponding TestResult instance.

example

diag = matlab.unittest.diagnostics.ScreenshotDiagnostic(Prefix=prefix) creates a diagnostic that saves screenshots to files whose names start with the specified prefix.

example

Input Arguments

expand all

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

This argument sets the Prefix property.

Example: "LoggedScreenshot_"

Example: "TestScreenshot-"

Properties

expand all

In addition to the following property, the ScreenshotDiagnostic class inherits properties from the Diagnostic class.

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

Attributes:

GetAccess
public
SetAccess
private

Examples

collapse all

Import the ScreenshotDiagnostic class.

import matlab.unittest.diagnostics.ScreenshotDiagnostic

Create a test case for interactive testing.

testCase = matlab.unittest.TestCase.forInteractiveUse;

Use a ScreenshotDiagnostic object to save a screenshot of the desktop when a test fails.

testCase.verifyFail(ScreenshotDiagnostic)
Verification failed.
    ----------------
    Test Diagnostic:
    ----------------
    Screenshot captured to:
    --> C:\Users\username\AppData\Local\Temp\Screenshot_15ff377e-78dc-48e4-9bd2-fc68e5954d72.png

Import the ScreenshotDiagnostic class.

import matlab.unittest.diagnostics.ScreenshotDiagnostic

Create a test case for interactive testing.

testCase = matlab.unittest.TestCase.forInteractiveUse;

Use a ScreenshotDiagnostic object to log an image of the desktop as a PNG file with a custom filename prefix.

testCase.log(ScreenshotDiagnostic(Prefix="LoggedScreenshot_"))
[Concise] Diagnostic logged (2025-12-19 16:32:08):
Screenshot captured to:
--> C:\Users\username\AppData\Local\Temp\LoggedScreenshot_04520d24-6cdb-4d94-bc4b-971f262b795c.png

In a file named ExampleTest.m in your current folder, create the ExampleTest test class. The failingTest method of the test class, which intentionally fails, uses a ScreenshotDiagnostic object to capture an image of the screen so you can examine it later. The logScreenshotTest method logs an image of the screen and saves it to a PNG file whose name starts with "LoggedScreenshot_".

classdef ExampleTest < matlab.unittest.TestCase
    methods (Test)
        function passingTest(testCase)
            testCase.verifyEqual(7,4+3)
        end

        function failingTest(testCase)
            import matlab.unittest.diagnostics.ScreenshotDiagnostic
            testCase.verifyFalse(true,ScreenshotDiagnostic)
        end

        function logScreenshotTest(testCase)
            import matlab.unittest.diagnostics.ScreenshotDiagnostic
            testCase.verifySubstring("Some Long Message","sage")
            testCase.log(1,ScreenshotDiagnostic(Prefix="LoggedScreenshot_"))
        end
    end
end

Run the tests in the test class. The Command Window displays diagnostics, including links to the generated PNG files.

results = runtests("ExampleTest");
Running ExampleTest
.
================================================================================
Verification failed in ExampleTest/failingTest.
    ----------------
    Test Diagnostic:
    ----------------
    Screenshot captured to:
    --> C:\Users\username\AppData\Local\Temp\3c127818-4750-404b-bc8f-9aee2b459149\Screenshot_cd010009-27e2-476a-94d3-1118f185fe65.png
    ---------------------
    Framework Diagnostic:
    ---------------------
    verifyFalse failed.
    --> The value must evaluate to "false".
    
    Actual Value:
      logical
    
       1
    ------------------
    Stack Information:
    ------------------
    In C:\work\ExampleTest.m (ExampleTest.failingTest) at 9
================================================================================
.
[Terse] Diagnostic logged (2026-01-21 14:23:54):
Screenshot captured to:
--> C:\Users\username\AppData\Local\Temp\3c127818-4750-404b-bc8f-9aee2b459149\LoggedScreenshot_2ff55aee-25ca-476d-b80a-96b3e0df69ca.png
.
Done ExampleTest
__________

Failure Summary:

     Name                     Failed  Incomplete  Reason(s)
    ======================================================================
     ExampleTest/failingTest    X                 Failed by verification.

You can also access screenshots programmatically from the diagnostic records of test results. For example, display the location of the screenshot saved for the failed test by accessing the FileArtifact object from the second test result.

results(2).Details.DiagnosticRecord.TestDiagnosticResults.Artifacts
ans = 

  FileArtifact with properties:

        Name: "Screenshot_cd010009-27e2-476a-94d3-1118f185fe65.png"
    Location: "C:\Users\username\AppData\Local\Temp\3c127818-4750-404b-bc8f-9aee2b459149"
    FullPath: "C:\Users\username\AppData\Local\Temp\3c127818-4750-404b-bc8f-9aee2b459149\Screenshot_cd010009-27e2-476a-94d3-1118f185fe65.png"

Display the location of the screenshot logged for the third test.

results(3).Details.DiagnosticRecord.LoggedDiagnosticResults.Artifacts
ans = 

  FileArtifact with properties:

        Name: "LoggedScreenshot_2ff55aee-25ca-476d-b80a-96b3e0df69ca.png"
    Location: "C:\Users\username\AppData\Local\Temp\3c127818-4750-404b-bc8f-9aee2b459149"
    FullPath: "C:\Users\username\AppData\Local\Temp\3c127818-4750-404b-bc8f-9aee2b459149\LoggedScreenshot_2ff55aee-25ca-476d-b80a-96b3e0df69ca.png"

Tips

  • The location of the saved screenshots 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 saved screenshots, 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 saved screenshots for the first test result.

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

  FileArtifact with properties:

        Name: "Screenshot_f51601ef-86bc-499c-bcec-203969f72a85.png"
    Location: "C:\Users\username\AppData\Local\Temp\1f4d3b64-3201-4bde-92ed-ad6859e97051"
    FullPath: "C:\Users\username\AppData\Local\Temp\1f4d3b64-3201-4bde-92ed-ad6859e97051\Screenshot_f51601ef-86bc-499c-bcec-203969f72a85.png"

  • If you are using a macOS system, in System Settings, allow the Terminal app to record the contents of your screens. This permission enables ScreenshotDiagnostic to include open windows, such as the MATLAB® desktop, when it captures the available screens as image files.

Version History

Introduced in R2017a

See Also

Classes