Main Content

matlab.unittest.plugins.OutputStream class

Package: matlab.unittest.plugins

Interface that determines where to send text output

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 instance to redirect the text they produce in a configurable manner.

The matlab.unittest.plugins.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.unittest.plugins.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 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.

Introduced in R2014a