matlab.unittest.plugins.QualifyingPlugin Class

Namespace: matlab.unittest.plugins
Superclasses: matlab.unittest.plugins.TestRunnerPlugin

Plugin interface for performing system-wide qualifications

Description

The matlab.unittest.plugins.QualifyingPlugin class enables you to implement plugins that perform system-wide qualifications on a test suite. A qualifying plugin produces test failures apart from your test content and lets you avoid repeating the same qualification in every test. You can decide to apply system-wide qualifications to the test suite by adding the plugin to the test runner for a particular test session.

To create a plugin class that supports system-wide qualifications, derive your class from matlab.unittest.plugins.QualifyingPlugin and override inherited methods using the qualification methods of the QualifyingPlugin class. You can perform system-wide verifications, assumptions, assertions, and fatal assertions in these inherited methods:

Additionally, you can perform system-wide assumptions, assertions, and fatal assertions in these inherited methods:

The matlab.unittest.plugins.QualifyingPlugin class is a handle class.

Methods

expand all

Protected Methods

In addition to these qualification methods, the matlab.unittest.plugins.QualifyingPlugin class inherits methods from the TestRunnerPlugin class.

`assertUsing`	Assert that value satisfies given constraint
`assumeUsing`	Assume that value satisfies given constraint
`fatalAssertUsing`	Fatally assert that value satisfies given constraint
`verifyUsing`	Verify that value satisfies given constraint

Examples

collapse all

Perform Qualifications Using Plugin

Fail test classes that corrupt the MATLAB^® search path by using the QualifyingPlugin class.

In a file named QualifyNoPathChangePlugin.m in your current folder, create the QualifyNoPathChangePlugin plugin class by inheriting from matlab.unittest.plugins.QualifyingPlugin. Implement the class such that the plugin fails the tests in any test class that modifies the path without restoring it. To enable system-wide qualifications through the plugin, use a qualification method when implementing the teardownTestClass method.

classdef QualifyNoPathChangePlugin < ...
        matlab.unittest.plugins.QualifyingPlugin
    properties (Access=private)
        OriginalPath
    end

    methods (Access=protected)
        function setupTestClass(plugin,pluginData)
            plugin.OriginalPath = path;
            % Invoke the superclass method
            setupTestClass@ ...
                matlab.unittest.plugins.QualifyingPlugin(plugin,pluginData)
        end

        function teardownTestClass(plugin,pluginData)
            import matlab.unittest.constraints.IsEqualTo
            % Invoke the superclass method
            teardownTestClass@ ...
                matlab.unittest.plugins.QualifyingPlugin(plugin,pluginData)
            plugin.verifyUsing(pluginData.QualificationContext, ...
                path,IsEqualTo(plugin.OriginalPath), ...
                pluginData.Name + " must not modify the path.")
        end
    end
end

In a file named ExampleTest.m in your current folder, create the ExampleTest test class. For illustrative purposes, the testOne method in the test class modifies the path by creating a folder and adding it to the path.

classdef ExampleTest < matlab.unittest.TestCase
    properties
        folderName = "myFolder_" + string( ...
                datetime("now",Format="yyyyMMdd'T'HHmmss"))
    end
    methods (Test)
        function testOne(testCase)
            mkdir(testCase.folderName)
            addpath(testCase.folderName)
        end

        function testTwo(~)
        end
    end
end

Create a test suite from the test class.

suite = testsuite("ExampleTest");

Run the tests using a test runner configured with a QualifyNoPathChangePlugin instance. Even though the test class itself does not include any qualifications, the plugin fails the tests because the test class modifies the path without restoring it.

runner = testrunner("textoutput");
plugin = QualifyNoPathChangePlugin;
runner.addPlugin(plugin)
result = runner.run(suite);

Running ExampleTest
..
================================================================================
Verification failed while setting up or tearing down ExampleTest.
As a result, all ExampleTest tests failed.
    ----------------
    Test Diagnostic:
    ----------------
    ExampleTest must not modify the path.
    ---------------------
    Framework Diagnostic:
    ---------------------
    IsEqualTo failed.
    --> StringComparator failed.
        --> The character arrays are not equal.
        
        Actual char:
            C:\work\myFolder_20240822T165923; ...

Done ExampleTest
__________

Failure Summary:

     Name                 Failed  Incomplete  Reason(s)
    ==================================================================
     ExampleTest/testOne    X                 Failed by verification.
    ------------------------------------------------------------------
     ExampleTest/testTwo    X                 Failed by verification.

Version History

Introduced in R2015b