Main Content

matlab.unittest.diagnostics.ScreenshotDiagnostic Class

Namespace: matlab.unittest.diagnostics

Diagnostic to capture screen as image file

expand all in page

Description

Use the ScreenshotDiagnostic class to create a diagnostic that captures available screens as image files. The files persist after MATLAB® completes the test run, and so they are available for post-test inspection.

Construction

ScreenshotDiagnostic() creates a diagnostic that captures available screens as image files. When the testing framework diagnoses the ScreenshotDiagnostic instance, it saves the screenshots to PNG files. The files each have a unique name consisting of a prefix (Screenshot_', by default), an automatically generated identifier, and the file extension. An example file name is Screenshot_cf95fe7f-5a7c-4310-9c49-16c0c18a969f.png. To view the location of the files, access the FileArtifact object through the TestResult instance.

ScreenshotDiagnostic('Prefix',prefix) creates a diagnostic that saves screenshots to files with names that begin with a specified prefix.

Input Arguments

expand all

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

Example: 'LoggedScreenshot_'

Example: "TestScreenshot-"

Properties

expand all

File name prefix, returned as a character vector. The default prefix is 'Screenshot_'. 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;

Use a ScreenshotDiagnostic to save an image of the desktop as a test diagnostic.

import matlab.unittest.diagnostics.ScreenshotDiagnostic
testCase.verifyTrue(false,ScreenshotDiagnostic)
Interactive verification failed.

----------------
Test Diagnostic:
----------------
Screenshot captured to:
--> C:\work\Temp\Screenshot_e99834ed-75e9-4ee1-9596-2f95e64b0ff1.png

---------------------
Framework Diagnostic:
---------------------
verifyTrue failed.
--> The value must evaluate to "true".

Actual logical:
       0

Create a TestCase for interactive use.

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

Use a ScreenshotDiagnostic to log an image of the desktop as a test diagnostic with a custom prefix.

import matlab.unittest.diagnostics.ScreenshotDiagnostic
testCase.log(ScreenshotDiagnostic('Prefix','LoggedScreenshot_'))
Interactive diagnostic logged.
Screenshot captured to:
--> C:\work\Temp\LoggedScreenshot_35bb1ecb-441a-4f79-9f59-8b18ac3f9d12.png

In a file in your current working folder, create the ScreenShotExampleTest test class. When the failingTest test method fails (it always does in this example), it uses a ScreenshotDiagnostic to capture an image of the screen so you can examine it later. The logScreenshotTest test always captures an image of the screen and saves it in a file prefixed with LoggedScreenshot_.

classdef ScreenShotExampleTest < 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.

res = runtests('ScreenShotExampleTest');
Running ScreenShotExampleTest
.
================================================================================
Verification failed in ScreenShotExampleTest/failingTest.

    ----------------
    Test Diagnostic:
    ----------------
    Screenshot captured to:
    --> C:\Temp\bf0e26d1-8d47-4462-b1f2-673c7d35c236\Screenshot_b24f2219-61a4-4cf8-b4da-fe7e10da92bd.png

    ---------------------
    Framework Diagnostic:
    ---------------------
    verifyFalse failed.
    --> The value must evaluate to "false".
    
    Actual logical:
           1

    ------------------
    Stack Information:
    ------------------
    In C:\work\ScreenShotExampleTest.m (ScreenShotExampleTest.failingTest) at 8
================================================================================
.   [Terse] Diagnostic logged (2016-12-22T11:21:54): 
Screenshot captured to:
--> C:\Temp\bf0e26d1-8d47-4462-b1f2-673c7d35c236\LoggedScreenshot_26def240-9a9d-4147-9d3e-c399ae157c0f.png

.
Done ScreenShotExampleTest
__________

Failure Summary:

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

The framework diagnostics in the Command Window indicate the captured screenshots. You can also access these locations programmatically through the diagnostic records of the test results.

Since the second test fails, the screenshot is saved as part of the test diagnostics. Access the path to the screenshot through the Artifacts object on the TestDiagnosticResults.

res(2).Details.DiagnosticRecord.TestDiagnosticResults.Artifacts.FullPath
ans = 

    "C:\Temp\bf0e26d1-8d47-4462-b1f2-673c7d35c236\Screenshot_b24f2219-61a4-4cf8-b4da-fe7e10da92bd.png"

The third test passes, and the screenshot is saved as part of a logged diagnostic (through the log method on the TestCase). Access the path to the screenshot through the Artifacts object on the LoggedDiagnosticResults.

res(3).Details.DiagnosticRecord.LoggedDiagnosticResults.Artifacts.FullPath
ans = 

    "C:\Temp\bf0e26d1-8d47-4462-b1f2-673c7d35c236\LoggedScreenshot_26def240-9a9d-4147-9d3e-c399ae157c0f.png"

Tips

  • The location of the saved screenshots is a folder with a name unique to a test run within the folder contained in the ArtifactsRootFolder. If you are running a test interactively, the location of the root folder is the value returned by tempdir().

  • To determine the path of the saved screenshots, access the FileArtifact object for a particular test result. For example, assume that you have a TestResult array, res. 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: "Screenshot_f51601ef-86bc-499c-bcec-203969f72a85.png"
    Location: "C:\work\Temp\1f4d3b64-3201-4bde-92ed-ad6859e97051"
    FullPath: "C:\work\Temp\1f4d3b64-3201-4bde-92ed-ad6859e97051\Screenshot_f51601ef-86bc-499c-bcec-203969f72a85.png"

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

Version History

Introduced in R2017a

See Also

|