matlab.unittest.plugins.TAPPlugin.producingVersion13

R2026b

Class: matlab.unittest.plugins.TAPPlugin
Namespace: matlab.unittest.plugins

Construct TAPPlugin for version 13 TAP format

Syntax

plugin = matlab.unittest.plugins.TAPPlugin.producingVersion13

plugin = matlab.unittest.plugins.TAPPlugin.producingVersion13(stream)

plugin = matlab.unittest.plugins.TAPPlugin.producingVersion13(___,Name=Value)

Description

plugin = matlab.unittest.plugins.TAPPlugin.producingVersion13 creates a plugin that produces output in version 13 of the Test Anything Protocol (TAP) format. The TAP version 13 output includes test diagnostics in YAML blocks. By default, the plugin uses the ToStandardOutput stream, and the output appears on the screen. In this case, other output sent to the screen can invalidate the TAP stream.

plugin = matlab.unittest.plugins.TAPPlugin.producingVersion13(stream) redirects all the text output to a specified output stream. For example, you can redirect the output to the ToFile stream.

plugin = matlab.unittest.plugins.TAPPlugin.producingVersion13(___,Name=Value) specifies options using one or more name-value arguments in addition to any of the input argument combinations in previous syntaxes. For example, plugin = matlab.unittest.plugins.TAPPlugin.producingVersion13(LoggingLevel="detailed") creates a plugin that includes diagnostics logged at and below the matlab.automation.Verbosity.Detailed level.

Input Arguments

stream — Location where the plugin directs text output

matlab.automation.streams.ToStandardOutput (default) | instance of matlab.automation.streams.OutputStream class

Location where the plugin directs text output, specified as an instance of the OutputStream class. By default, the plugin uses the ToStandardOutput stream.

Example: stream = matlab.automation.streams.ToStandardOutput

Example: stream = matlab.automation.streams.ToFile('myFile.tap')

Name-Value Arguments

Specify optional pairs of arguments as Name1=Value1,...,NameN=ValueN, where Name is the argument name and Value is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

Example: plugin = matlab.unittest.plugins.TAPPlugin.producingVersion13(LoggingLevel="detailed")

IncludingPassingDiagnostics — Include passing event diagnostics

false (default) | true

Whether to include passing event diagnostics, specified as false or true. By default the plugin does not include diagnostics from passing events.

Data Types: logical

LoggingLevel — Maximum verbosity level of logged diagnostics

1 (default) | 0 | 2 | 3 | 4 | matlab.automation.Verbosity enumeration object | text representation of enumeration

Maximum verbosity level of logged diagnostics to include in the test report, specified as an integer scalar from 0 through 4, a matlab.automation.Verbosity enumeration object, or a text representation of the enumeration. The plugin includes diagnostics logged at the specified level and below.

Numeric Representation	Enumeration Member Name	Verbosity Description
0	None	No information
1	Terse	Minimal information
2	Concise	Moderate amount of information
3	Detailed	Some supplemental information
4	Verbose	Lots of supplemental information

By default, the plugin includes diagnostics logged at the matlab.automation.Verbosity.Terse level (level 1). To exclude logged diagnostics, specify LoggingLevel as matlab.automation.Verbosity.None (level 0).

Logged diagnostics are diagnostics that you supply to the testing framework with the log (TestCase) and log (Fixture) methods.

Example: LoggingLevel="detailed"

OutputDetail — Detail level for reported events

3 (default) | 0 | 1 | 2 | 4 | matlab.automation.Verbosity enumeration | enumeration name as string or char vector

Detail level for reported events, specified as an integer value from 0 through 4, a matlab.automation.Verbosity enumeration object, or a string scalar or character vector corresponding to one of the predefined enumeration member names. Integer values correspond to the members of the matlab.automation.Verbosity enumeration.

The plugin reports passing, failing, and logged events with the amount of detail specified by OutputDetail. By default the plugin records events at the matlab.automation.Verbosity.Detailed level (level 3).

Numeric Representation	Enumeration Member Name	Verbosity Description
0	None	No information
1	Terse	Minimal information
2	Concise	Moderate amount of information
3	Detailed	Some supplemental information
4	Verbose	Lots of supplemental information

Examples

Create TAP Plugin

In a 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

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

import matlab.unittest.TestRunner
import matlab.unittest.TestSuite
import matlab.unittest.plugins.TAPPlugin
import matlab.automation.streams.ToFile

suite = TestSuite.fromClass(?ExampleTest);

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

runner = TestRunner.withTextOutput;

Create a TAPPlugin that sends output to the file MyTapOutput.tap.

tapFile = 'MyTAPOutput.tap';
plugin = TAPPlugin.producingVersion13(ToFile(tapFile));

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

Display the file created by the plugin.

disp(fileread(tapFile))

TAP version 13
1..3
not ok 1 - ExampleTest/testOne
    ---
    Event:
        Event Name: 'VerificationFailed'
        Event Location: '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: |
            In C:\work\ExampleTest.m (ExampleTest.testOne) at 4
    ...
ok 2 - ExampleTest/testTwo
ok 3 - ExampleTest/testThree

You can use the TAPPlugin directed to standard output. However, any other text displayed to standard output (such as failed test information) interrupts the stream and has the potential to invalidate it.

Version History

Introduced in R2016b