matlab.unittest.plugins.QualifyingPlugin Class

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

Interface for plugins that perform system-wide qualifications

Description

Use qualifying plugins to produce test failures apart from your test content. Qualifications at the plugin level are useful because you can avoid repeating the same qualification in every test. You can decide to apply system-wide qualifications to the test suite periodically by simply adding the plugin to the test runner for a particular test session.

The QualifyingPlugin interface enables test runner plugin authors to implement plugins that perform system-wide qualifications on a test suite. You can perform verifications, assumptions, assertions, and fatal assertions in these inherited methods:

• setupTestClass

• teardownTestClass

• setupTestMethod

• teardownTestMethod

You can perform only assumptions, assertions, and fatal assertions in these inherited methods:

• setupSharedTestFixture

• teardownSharedTestFixture

Methods

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

Inherited Methods

createSharedTestFixture	Extend creation of shared test fixtures
createTestClassInstance	Extend creation of class-level TestCase instances
createTestMethodInstance	Extend creation of method-level TestCase instances
reportFinalizedResult	Extend reporting of finalized test results
reportFinalizedSuite	Extend reporting of finalized TestSuite array
runSession	Extend running of test session
runTest	Extend running of single Test element
runTestClass	Extend running of Test elements from same class or function
runTestMethod	Extend running of single Test method
runTestSuite	Extend running of TestSuite array
setupSharedTestFixture	Extend setting up shared test fixture
setupTestClass	Extend setting up test class
setupTestMethod	Extend setting up Test method
teardownSharedTestFixture	Extend tearing down shared test fixture
teardownTestClass	Extend tearing down test class
teardownTestMethod	Extend tearing down Test method

Copy Semantics

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

Examples

Test Using Qualification in Plugin

Create a plugin to ensure that test files leave the MATLAB^® path unchanged. If the path after running a test file is different from the original path, the test fails.

Create a class, VerifyNoPathChangePlugin, that inherits from the matlab.unittest.plugins.QualifyingPlugin class.

classdef VerifyNoPathChangePlugin < matlab.unittest.plugins.QualifyingPlugin
    properties (Access=private)
        OriginalPath
    end
    
    methods (Access=protected)
        function setupTestClass(plugin, pluginData)
            plugin.OriginalPath = path;
            [e-mail](plugin,pluginData);
        end
        function teardownTestClass(plugin, pluginData)
            import matlab.unittest.constraints.IsEqualTo;
            [e-mail](plugin,pluginData);
            plugin.verifyUsing(pluginData.QualificationContext, ...
                path, IsEqualTo(plugin.OriginalPath), ...
                sprintf('%s modified the path.', pluginData.Name));
        end
    end
end

Create the following test class. The test modifies the path, but does not restore the original path.

classdef LeavesModifiedPath < matlab.unittest.TestCase
    methods (Test)
        function test1(~)
            addpath(pwd);
        end
    end
end

For purposes of this example, at the command prompt, remove the present working folder from the path.

rmpath(pwd)

Create a test suite, add the plugin to the test runner, and run the suite. The test fails because the path after the test is different from the starting path.

suite = matlab.unittest.TestSuite.fromClass(?LeavesModifiedPath);
runner = matlab.unittest.TestRunner.withTextOutput;
runner.addPlugin(VerifyNoPathChangePlugin);
runner.run(suite);

Running LeavesModifiedPath
.
================================================================================
Verification failed while setting up or tearing down LeavesModifiedPath.
As a result, all LeavesModifiedPath tests failed.

    ----------------
    Test Diagnostic:
    ----------------
    LeavesModifiedPath modified the path.

    ---------------------
    Framework Diagnostic:
    ---------------------
    IsEqualTo failed.
    --> StringComparator failed.
        --> The character arrays are not equal.
    
    Actual char:
        C:\work;C:\Program Files\MATLAB\R2015b\toolbox\matlab\...
   Expected char:
        C:\Program Files\MATLAB\R2015b\toolbox\matlab\...

    ------------------
    Stack Information:
    ------------------
    In C:\work\VerifyNoPathChangePlugin.m (VerifyNoPathChangePlugin.teardownTestClass) at 14
================================================================================

Done LeavesModifiedPath
__________

Failure Summary:

     Name                      Failed  Incomplete  Reason(s)
    =======================================================================
     LeavesModifiedPath/test1    X                 Failed by verification.

Version History

Introduced in R2015b