matlab.automation.streams.OutputStream - Interface that determines where to send text output - MATLAB (original) (raw)

Namespace: matlab.automation.streams

Interface that determines where to send text output

Renamed from matlab.unittest.plugins.OutputStream in R2023a

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.

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 ofOutputStream. 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. TheverifyEqual 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 theToFigure 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, theDiagnosticsValidationPlugin 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

To reflect support for additional automated workflows,matlab.unittest.plugins.OutputStream is now namedmatlab.automation.streams.OutputStream. The behavior of this class remains the same, and existing instances of matlab.unittest.plugins.OutputStream in your code continue to work as expected. There are no plans to remove support for existing instances of matlab.unittest.plugins.OutputStream.