matlab.unittest.fixtures.WorkingFolderFixture Class

R2026b

Namespace: matlab.unittest.fixtures
Superclasses: matlab.unittest.fixtures.Fixture

Fixture for creating and switching to temporary folder

Description

The matlab.unittest.fixtures.WorkingFolderFixture class provides a fixture for creating a temporary folder and setting that folder as the current (working) folder. Using this fixture, a test or the software under test can modify the contents of the folder—for example, by creating files—without affecting the source or test folder structure.

When the testing framework sets up the fixture, the fixture adds the current folder to the path, creates a temporary folder, and changes the current folder to the temporary folder. When the framework tears down the fixture, the fixture deletes the temporary folder and its contents by default, and then restores the current folder to the original working folder.

The matlab.unittest.fixtures.WorkingFolderFixture class is a handle class.

Creation

Description

fixture = matlab.unittest.fixtures.WorkingFolderFixture constructs a fixture for creating a temporary folder and setting that folder as the current folder.

fixture = matlab.unittest.fixtures.WorkingFolderFixture(Name=Value) specifies options using one or more name-value arguments. For example, fixture = matlab.unittest.fixtures.WorkingFolderFixture(PreservingOnFailure=true) constructs a fixture that does not delete the temporary folder in the event of a failure.

Name-Value Arguments

Specify optional pairs of arguments as Name1=Value1,...,NameN=ValueN, where Name is the argument name and Value is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

Example: fixture = matlab.unittest.fixtures.WorkingFolderFixture(PreservingOnFailure=true)

PreservingOnFailure — Option to preserve temporary folder after test failure

false or 0 (default) | true or 1

Option to preserve the temporary folder and its contents after a test failure, specified as a numeric or logical 0 (false) or 1 (true). Failures include verification, assertion, or fatal assertion failures and uncaught errors within the tests that use the fixture.

By default, when the framework encounters a test failure, it tears down the fixture, and the fixture deletes the temporary folder and its contents. If you specify PreservingOnFailure as true, the fixture does not delete the temporary folder and its contents after a failure. Preserving the temporary folder and its contents can help you debug the failure.

This argument sets the PreserveOnFailure property.

WithSuffix — Suffix for temporary folder name

string scalar | character vector

Suffix for the temporary folder name, specified as a string scalar or character vector.

This argument sets the Suffix property.

Example: WithSuffix="_FeatureA"

Properties

In addition to these properties, the WorkingFolderFixture class inherits properties from the Fixture class.

Folder — Absolute path to temporary folder

'' (default) | character vector

Absolute path to the temporary folder that the fixture created during setup, returned as a character vector. The fixture sets this property when the framework sets up the fixture.

Attributes:

GetAccess	public
SetAccess	private

StartingFolder — Absolute path to original working folder

'' (default) | character vector

Absolute path to the original working folder, returned as a character vector. The fixture sets this property when the framework sets up the fixture.

Attributes:

GetAccess	public
SetAccess	private

PreserveOnFailure — Option to preserve temporary folder after test failure

false or 0 (default) | true or 1

Option to preserve the temporary folder and its contents after a test failure, specified as a numeric or logical 0 (false) or 1 (true). Failures include verification, assertion, or fatal assertion failures and uncaught errors within the tests that use the fixture. By default, when the framework encounters a failure, it tears down the fixture, and the fixture deletes the temporary folder and its contents.

You can set this property during fixture creation by using the PreservingOnFailure name-value argument.

Attributes:

GetAccess	public
SetAccess	private

Suffix — Suffix for temporary folder name

'' (default) | string scalar | character vector

Suffix for the temporary folder name, specified as a string scalar or character vector, and stored as a character vector.

You can set this property during fixture creation by using the WithSuffix name-value argument.

Attributes:

GetAccess	public
SetAccess	private

Examples

Create Temporary Working Folder for Testing

Create a temporary working folder for testing by using a WorkingFolderFixture instance.

In a file named ExampleTest.m in your current folder, create the ExampleTest class that uses a fixture to change the current folder to a temporary folder. To simplify this example, the test displays the absolute path to the current folder before and after the change and then verifies saving and loading data in the temporary working folder.

classdef ExampleTest < matlab.unittest.TestCase
    methods (Test)
        function test1(testCase)
            import matlab.unittest.fixtures.WorkingFolderFixture
            fixture = testCase.applyFixture(WorkingFolderFixture);

            disp("Original working folder: " + fixture.StartingFolder)
            disp("Temporary working folder: " + pwd)

            x = 1:10;
            save("data.mat","x")
            S = load("data.mat","x");
            testCase.verifyEqual(S.x,x)
        end
    end
end

Run the test. The test displays the folder paths and passes.

results = runtests("ExampleTest");

Running ExampleTest
Original working folder: C:\work
Temporary working folder: C:\Users\username\AppData\Local\Temp\tp42cfe19a_611b_4464_ad3e_a36460c2d9fb
.
Done ExampleTest
__________

Test with Persistent Temporary Folder

Use a temporary folder for testing that persists after a test failure.

In a file named PersistentFolderTest.m in your current folder, create the PersistentFolderTest class. In the test class, create a temporary folder that persists after a test failure by using a WorkingFolderFixture instance. For illustration purposes, the test in this example intentionally fails.

classdef PersistentFolderTest < matlab.unittest.TestCase
    methods (Test)
        function testWithTemporaryFolder(testCase)
            import matlab.unittest.fixtures.WorkingFolderFixture
            testCase.applyFixture(WorkingFolderFixture( ...
                PreservingOnFailure=true,WithSuffix="_TestData"))

            % Failing test
            x = 1:10;
            save("data.mat","x")
            S = load("data.mat","x");
            testCase.verifyEqual(S,x)
        end
    end
end

Run the test. The test fails, but the temporary folder persists. The test diagnostics contain the absolute path to the temporary folder.

result = runtests("PersistentFolderTest");

Running PersistentFolderTest

================================================================================
Verification failed in PersistentFolderTest/testWithTemporaryFolder.
    ---------------------
    Framework Diagnostic:
    ---------------------
    verifyEqual failed.
    --> Classes do not match.
        
        Actual Class:
            struct
        Expected Class:
            double
    
    Actual Value:
      struct with fields:
    
        x: [1 2 3 4 5 6 7 8 9 10]
    Expected Value:
         1     2     3     4     5     6     7     8     9    10
    ----------------------
    Additional Diagnostic:
    ----------------------
    Temporary folder preserved on failure: C:\Users\username\AppData\Local\Temp\tpaeaf1157_f0b6_4769_86fb_83f4984afda3_TestData
    ------------------
    Stack Information:
    ------------------
    In C:\work\PersistentFolderTest.m (PersistentFolderTest.testWithTemporaryFolder) at 12
================================================================================
.
Done PersistentFolderTest
__________

Failure Summary:

     Name                                          Failed  Incomplete  Reason(s)
    ===========================================================================================
     PersistentFolderTest/testWithTemporaryFolder    X                 Failed by verification.

Tips

• Both the WorkingFolderFixture and TemporaryFolderFixture classes create a fixture that results in a temporary folder. However, the fixture created with WorkingFolderFixture also sets the temporary folder as the current folder.

Version History

Introduced in R2016a