matlab.unittest.plugins.DiagnosticsValidationPlugin class

Package: matlab.unittest.plugins

Plugin to help validate diagnostic code

Description

The DiagnosticsValidationPlugin creates a plugin to help validate diagnostic code.

Add the DiagnosticsValidationPlugin to the TestRunner to confirm that user-supplied diagnostics execute correctly. This plugin is useful because typically tests do not encounter failure conditions. A failure can result in unexercised diagnostic code. If a programming error exists in this diagnostic code, the error is not evident unless the test fails. However, at this point in the testing process, the diagnostics for the failure condition are lost due to the error in the diagnostic code.

Use this plugin to unconditionally evaluate the diagnostics supplied by the test writer, regardless of whether the test results in a passing or failing condition. This approach helps you to confirm that all of the diagnostic code is free from programming errors.

The diagnostic analysis can reduce the test performance and can result in very verbose text output. Be aware of these impacts before using this plugin for routine testing.

Construction

matlab.unittest.plugins.DiagnosticsValidationPlugin creates a plugin to help validate diagnostic code.

matlab.unittest.plugins.DiagnosticsValidationPlugin(stream) redirects all the text output to the output stream, stream. If you do not specify the output stream, the plugin uses the default ToStandardOutput stream.

Input Arguments

stream

Location where the plugin directs text output, specified as an OutputStream.

Default: ToStandardOutput

Copy Semantics

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

Examples

collapse all

Add Plugin to TestRunner

In your working folder, create a file, ExampleTest.m, containing the following test class. In this example, the testThree method has an intentional error. The method should use a function handle to the dir function as a FunctionHandleDiagnostic, but dir is misspelled.

classdef ExampleTest < matlab.unittest.TestCase
    methods(Test)
        function testOne(testCase)
            % test code
        end
        function testTwo(testCase)
            % test code
        end
        function testThree(testCase)
            % The following should use @dir as a function handle,
            % but there is a typo
            testCase.verifyEqual('myfile','myfile', @dri)
        end
    end
end

All of the tests in ExampleTest.m result in a passing condition, but there is an error in the diagnostic.

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

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

suite = TestSuite.fromClass(?ExampleTest);

Create a test runner configured with text output.

runner = TestRunner.withTextOutput;

Run the tests.

result1 = runner.run(suite);

Running ExampleTest
...
Done ExampleTest
__________

No diagnostic output is displayed because all the tests passed. The testing framework does not encounter the bug in the FunctionHandleDiagnostic of testThree.

Add DiagnosticValidationPlugin to the runner and run the tests.

runner.addPlugin(DiagnosticsValidationPlugin)
result2 = runner.run(suite);

Running ExampleTest
..
------------------------------
Validation of Test Diagnostic:
------------------------------
Error occurred while capturing diagnostics:
Error using evalc
Undefined function or variable 'dri'.

Error in ExampleTest/testThree (line 12)
            testCase.verifyEqual('myfile','myfile', @dri);

.
Done ExampleTest
__________

The framework executes the diagnostic provided by the FunctionHandleDiagnostic, even though none of the tests fails. Without this plugin, the test framework only encounters the bug if the test fails.

Documentation