matlab.unittest.plugins.OutputStream class

Package: matlab.unittest.plugins

Interface that determines where to send text output

expand all in page

Description

The OutputStream interface is an abstract interface class that you can use as a base class to specify where plugins direct their text output. To create a custom output stream, implement a print method that correctly handles the formatted text information the testing framework passes to it. Many text-oriented plugins accept an OutputStream to redirect the text they produce in a configurable manner.

Methods

printPrint text to output stream

Copy Semantics

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

Examples

collapse all

In a file in your working directory, create a new output stream class in the file ToFigure.m. This class allows plugin output to be redirected to a figure.

classdef ToFigure < matlab.unittest.plugins.OutputStream
    
    properties(SetAccess=private)
        Figure
    end
    properties(Access=private)
        ListBox
    end

This class uses two properties. Figure is the figure that receives and displays the output. ListBox is a handle to the list box that displays the text.

In the same file, add the following methods block.

    methods
        function print(stream,formatSpec,varargin)
            % Create the figure
            if isempty(stream.Figure) || ~ishghandle(stream.Figure)
                stream.createFigure
            end
            newStr = sprintf(formatSpec,varargin{:});
            oldStr = strjoin(stream.ListBox.String', '\n');
            
            % Create the full message
            fullStr = [oldStr,newStr];
            fullStrCell = strsplit(fullStr,'\n','CollapseDelimiters',false);
            
            % Set the string and selection
            stream.ListBox.String = fullStrCell';
            stream.ListBox.Value = numel(fullStrCell);
            drawnow
        end
    end

You must implement the print method for any subclass of OutputStream. In this example, the method creates a new figure (if necessary), formats the incoming text, and then adds it to the output stream.

In the same file, add the following methods block containing a helper function to create the figure.

    methods(Access=private)
        function createFigure(stream)
            stream.Figure = figure(...
                'Name',         'Unit Test Output', ...
                'WindowStyle',  'docked');
            
            stream.ListBox = uicontrol( ...
                'Parent',       stream.Figure, ...
                'Style',        'listbox', ...
                'String',       {}, ...
                'Units',        'normalized', ...
                'Position',     [.05 .05 .9 .9], ...
                'Max',          2, ...
                'FontName',     'Monospaced', ...
                'FontSize',      13);
        end
    end
end

In an new file in your working folder, create ExampleTest.m containing the following test class.

classdef ExampleTest < matlab.unittest.TestCase
    methods(Test)
        function testOne(testCase)  % Test fails
            testCase.verifyEqual(5, 4, 'Testing 5==4' );
        end
        function testTwo(testCase)  % Test passes
            testCase.verifyEqual(5, 5, 'Testing 5==5' );
        end
        function testThree(testCase)
            % test code
        end
    end
end

The verifyEqual qualification in testOne causes a test failure. The qualifications in testOne and testTwo include an instance of a matlab.unittest.diagnostics.StringDiagnostic.

At the command prompt, create a test suite from the ExampleTest class.

import matlab.unittest.TestSuite
import matlab.unittest.TestRunner
import matlab.unittest.plugins.DiagnosticsValidationPlugin

suite = TestSuite.fromClass(?ExampleTest);

Create a test runner that displays output to the command window.

runner = TestRunner.withTextOutput;

Create a DiagnosticsValidationPlugin that explicitly specifies that its output should go to a figure via the ToFigure output stream.

plugin = DiagnosticsValidationPlugin(ToFigure);

Add the plugin to the TestRunner and run the suite. 

runner.addPlugin(plugin)
result = runner.run(suite);
Running ExampleTest

================================================================================
Verification failed in ExampleTest/testOne.

    ----------------
    Test Diagnostic:
    ----------------
    Testing 5==4

    ---------------------
    Framework Diagnostic:
    ---------------------
    verifyEqual failed.
    --> The values are not equal using "isequaln".
    --> Failure table:
                Actual    Expected    Error    RelativeError
                ______    ________    _____    _____________
            
                5         4           1        0.25         
    
    Actual double:
             5
    Expected double:
             4

    ------------------
    Stack Information:
    ------------------
    In C:\work\ExampleTest.m (ExampleTest.testOne) at 4
================================================================================
...
Done ExampleTest
__________

Failure Summary:

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

Only the test failures produce output to the screen. By default, TestRunner.withTextOutput uses a FailureDiagnosticsPlugin to display output on the screen.

In addition to the default text output being displayed on the screen, the DiagnosticsValidationPlugin output is directed to a docked figure. The figure shows the following text.

------------------------------
Validation of Test Diagnostic:
------------------------------
Testing 5==4
------------------------------
Validation of Test Diagnostic:
------------------------------
Testing 5==5

The DiagnosticsValidationPlugin displays the diagnostic information regardless of whether the tests encounter failure conditions.

See Also

| |

Introduced in R2014a

Was this topic helpful?
MATLAB Documentation
Support