Main Content

matlab.automation.streams.OutputStream Class

Namespace: matlab.automation.streams

Interface that determines where to send text output

Renamed from matlab.unittest.plugins.OutputStream in R2023a

expand all in page

Description

The matlab.automation.streams.OutputStream class provides an interface that you can use to specify where plugins direct their text output. To create a custom output stream, implement a print method that handles the formatted text information passed to it. Many text-oriented plugins accept an OutputStream instance to redirect the text they produce in a configurable manner.

The matlab.automation.streams.OutputStream class is a handle class.

Methods

expand all

Examples

collapse all

In a file in your current folder, create a class named ToFigure that redirects the plugin output to a figure and displays it in a list box within the figure. Define the Figure and ListBox properties to represent the figure and the handle to the list box, respectively.

classdef ToFigure < matlab.automation.streams.OutputStream
    
    properties(SetAccess = private)
        Figure
    end
    properties(Access = private)
        ListBox
    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.

    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 = strjoin([oldStr,newStr]);
            fullStrArray = strsplit(fullStr,'\n','CollapseDelimiters',false);
            
            % Set the string and selection
            stream.ListBox.String = fullStrArray';
            stream.ListBox.Value = numel(fullStrArray);
            drawnow
        end
    end

In a methods block with private access, implement a helper method named createFigure that creates the figure and the list box used by the plugin.

    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

Save the ToFigure class. Now, in your current folder, create a file named ExampleTest.m containing the following test class. The verifyEqual qualification in testOne causes a test failure. The verification in testTwo passes. The test corresponding to testThree passes without producing an output.

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

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

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

suite = testsuite('ExampleTest');

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

runner = TestRunner.withTextOutput;

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

plugin = DiagnosticsValidationPlugin(ToFigure);

Add the plugin to the runner and run the tests.

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

================================================================================
Verification failed in ExampleTest/testOne.
    ----------------
    Test Diagnostic:
    ----------------
    Testing 5==4
    ---------------------
    Framework Diagnostic:
    ---------------------
    verifyEqual failed.
    --> The numeric values are not equal using "isequaln".
    --> Failure table:
            Actual    Expected    Error    RelativeError
            ______    ________    _____    _____________
                                                        
              5          4          1          0.25     
    
    Actual Value:
         5
    Expected Value:
         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 DiagnosticsOutputPlugin 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 this 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.

Version History

Introduced in R2014a

expand all

See Also

| | |

Topics