Main Content

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

assertUsingAssert that value satisfies given constraint
assumeUsingAssume that value satisfies given constraint
fatalAssertUsingFatally assert that value satisfies given constraint
verifyUsingVerify 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
reportFinalizedResultExtend reporting of finalized test results
reportFinalizedSuiteExtend reporting of finalized TestSuite array
runSessionExtend 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
runTestSuiteExtend running of TestSuite array
setupSharedTestFixtureExtend setting up shared test fixture
setupTestClass Extend setting up test class
setupTestMethodExtend setting up Test method
teardownSharedTestFixtureExtend tearing down shared test fixture
teardownTestClassExtend tearing down test class
teardownTestMethodExtend tearing down Test method

Copy Semantics

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

Examples

collapse all

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;
            setupTestClass@matlab.unittest.plugins.QualifyingPlugin(plugin,pluginData);
        end
        function teardownTestClass(plugin, pluginData)
            import matlab.unittest.constraints.IsEqualTo;
            teardownTestClass@matlab.unittest.plugins.QualifyingPlugin(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