Main Content

needsReset

Class: matlab.unittest.fixtures.Fixture
Namespace: matlab.unittest.fixtures

Determine if shared test fixture needs to be reset

Since R2020b

expand all in page

Syntax

tf = needsReset(fixture)

Description

tf = needsReset(fixture) reports the validity of the shared test fixture to the testing framework. If the fixture is invalid and needs to be reset, then the method returns logical 1 (true). Otherwise, it returns logical 0 (false). A shared test fixture is valid if the test environment state, configured by the fixture, is maintained throughout the test session.

For test classes that use a shared test fixture, the framework calls the needsReset method whenever the test runner switches to a subsequent class. If the method returns true, then the framework automatically tears down the shared test fixture and sets it up for the subsequent classes. The framework performs the actions defined by the teardown or addTeardown methods to tear down an invalidated fixture and the actions defined by the setup method to set up the fixture. Therefore, your needsReset implementation must not include code that performs fixture setup or teardown actions.

example

Input Arguments

expand all

Shared test fixture to validate, specified as an instance of the matlab.unittest.fixtures.Fixture class.

Attributes

Accessprotected

To learn about attributes of methods, see Method Attributes.

Examples

expand all

Open Live Script

Create a fixture that removes a folder from the MATLAB® search path, and instruct the testing framework to reset the environment state if the fixture is invalidated. Then, use the fixture as a shared test fixture when running tests in multiple classes.

This example assumes that the subfolder helperFiles within your current folder exists on the path. Create the subfolder if it does not exist and ensure that it is on the path.

if ~isfolder('helperFiles')
    mkdir helperFiles
end
addpath('helperFiles')

In a file in your current folder, create a fixture named RemoveFolderFromPathFixture that sets the environment state by removing a folder from the path. To ensure the same environment state for all of the test classes that use the fixture as a shared test fixture, override the needsReset method. The method returns true if the specified folder is on the path when the test runner switches to the subsequent class.

classdef RemoveFolderFromPathFixture < matlab.unittest.fixtures.Fixture
    properties (SetAccess = immutable)
        Folder (1,1) string % Full path to the folder
    end
    methods
        function fixture = RemoveFolderFromPathFixture(folder)
            fixture.Folder = folder;
        end
        function setup(fixture)
            originalPath = path;
            fixture.addTeardown(@()path(originalPath));
            rmpath(fixture.Folder)
        end
    end
    methods (Access = protected)
        function tf = isCompatible(fixture1,fixture2)
            tf = fixture1.Folder == fixture2.Folder;
        end
        function tf = needsReset(fixture)
            foldersOnPath = split(path,pathsep);
            tf = ismember(fixture.Folder,foldersOnPath);
        end
    end
end

In your current folder, create three test classes that use RemoveFolderFromPathFixture as a shared test fixture.

In a file named SampleTestA.m, create the SampleTestA class.

classdef (SharedTestFixtures = { ...
        RemoveFolderFromPathFixture(fullfile(pwd,'helperFiles'))}) ...
        SampleTestA < matlab.unittest.TestCase
    methods (Test)
        function test1(testCase)
            import matlab.unittest.constraints.ContainsSubstring
            f = testCase.getSharedTestFixtures;
            testCase.assertThat(path,~ContainsSubstring(f.Folder))
        end
    end
end

In a file named SampleTestB.m, create the SampleTestB class. The test in the class adds helperFiles to the path.

classdef (SharedTestFixtures = { ...
        RemoveFolderFromPathFixture(fullfile(pwd,'helperFiles'))}) ...
        SampleTestB < matlab.unittest.TestCase
    methods (Test)
        function test1(testCase)
            import matlab.unittest.constraints.ContainsSubstring
            f = testCase.getSharedTestFixtures;
            addpath('helperFiles')
            testCase.assertThat(path,ContainsSubstring(f.Folder))
        end
    end
end

In a file named SampleTestC.m, create the SampleTestC class.

classdef (SharedTestFixtures = { ...
        RemoveFolderFromPathFixture(fullfile(pwd,'helperFiles'))}) ...
        SampleTestC < matlab.unittest.TestCase
    methods (Test)
        function test1(testCase)
            import matlab.unittest.constraints.ContainsSubstring
            f = testCase.getSharedTestFixtures;
            testCase.assertThat(path,~ContainsSubstring(f.Folder))
        end
    end
end

Create a test suite and run the tests. To validate the shared test fixture, the testing framework calls the needsReset method when the test runner switches to SampleTestB and SampleTestC.

suite = [testsuite('SampleTestA') testsuite('SampleTestB') ...
    testsuite('SampleTestC')];
runner = matlab.unittest.TestRunner.withTextOutput;   
results = runner.run(suite);
Setting up RemoveFolderFromPathFixture
Done setting up RemoveFolderFromPathFixture
__________

Running SampleTestA
.
Done SampleTestA
__________

Running SampleTestB
.
Done SampleTestB
__________

Tearing down RemoveFolderFromPathFixture
Done tearing down RemoveFolderFromPathFixture
__________

Setting up RemoveFolderFromPathFixture
Done setting up RemoveFolderFromPathFixture
__________

Running SampleTestC
.
Done SampleTestC
__________

Tearing down RemoveFolderFromPathFixture
Done tearing down RemoveFolderFromPathFixture
__________

SampleTestA does not corrupt the environment state set by RemoveFolderFromPathFixture. Therefore, the framework uses the established fixture for running SampleTestB. However, SampleTestB corrupts the environment state by adding helperFiles to the path. The framework tears down the fixture and sets it up between calls to SampleTestB and SampleTestC.

Version History

Introduced in R2020b

See Also

|

Topics