matlab.unittest.fixtures.TemporaryFolderFixture Class

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

Fixture for creating temporary folder

Description

The matlab.unittest.fixtures.TemporaryFolderFixture class provides a fixture for creating a temporary folder. When the testing framework sets up the fixture, the fixture creates a temporary folder. When the framework tears down the fixture, the fixture deletes the folder and its contents. Before deleting the folder, the fixture first clears from memory any functions, MEX files, and classes that are defined in the temporary folder.

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

Creation

Description

fixture = matlab.unittest.fixtures.TemporaryFolderFixture constructs a fixture for creating a temporary folder.

fixture = matlab.unittest.fixtures.TemporaryFolderFixture(Name,Value) sets additional options using one or more name-value arguments. For example, fixture = matlab.unittest.fixtures.TemporaryFolderFixture("WithSuffix","_FeatureA") constructs a fixture that creates a temporary folder with the specified suffix for the folder name.

Input Arguments

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.TemporaryFolderFixture(WithSuffix="_FeatureA")

Before R2021a, use commas to separate each name and value, and enclose Name in quotes.

Example: fixture = matlab.unittest.fixtures.TemporaryFolderFixture("WithSuffix","_FeatureA")

PreservingOnFailure — Whether to preserve temporary folder after test failure

false or 0 (default) | true or 1

Whether 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 the value as true, the fixture does not delete the temporary folder and its contents after a failure. Preserving the temporary folder and its contents can aid in debugging the cause of 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.

Properties

Folder — Full path to temporary folder

'' (default) | character vector

Full 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

PreserveOnFailure — Whether to preserve temporary folder after test failure

false or 0 (default) | true or 1

Whether to preserve the temporary folder and its contents after a test failure, returned as a 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.

This property is set by the PreservingOnFailure name-value argument.

Attributes:

GetAccess	public
SetAccess	private

Suffix — Suffix for temporary folder name

character vector

Suffix for the temporary folder name, returned as a character vector.

This property is set by the WithSuffix name-value argument.

Attributes:

GetAccess	public
SetAccess	private

Examples

Create Temporary Folder for Testing

Create a temporary folder for testing by using a TemporaryFolderFixture instance.

In a file named WritingToFileTest.m in your current folder, create the WritingToFileTest class. Define a Test method in the class that writes to a file in a temporary folder and then verifies the contents of the file. To create a temporary folder for your test, use a TemporaryFolderFixture instance.

classdef WritingToFileTest < matlab.unittest.TestCase
    methods (Test)
        function testWithTemporaryFolder(testCase)
            import matlab.unittest.fixtures.TemporaryFolderFixture
            fixture = testCase.applyFixture(TemporaryFolderFixture);
            
            file = fullfile(fixture.Folder,"myFile.txt");
            fid = fopen(file,"w");
            testCase.addTeardown(@fclose,fid)
            testCase.assertNotEqual(fid,-1,"IO Problem")
            txt = repmat("ab",1,1000);
            dataToWrite = join(txt);
            fprintf(fid,"%s",dataToWrite);
            testCase.verifyEqual(string(fileread(file)),dataToWrite)
        end
    end
end

Run the test. The testing framework sets up the fixture, which creates a temporary folder. After testing, the framework tears down the fixture, which removes the temporary folder and its contents. In this example, the test passes.

runtests("WritingToFileTest");

Running WritingToFileTest
.
Done WritingToFileTest
__________

Test with Persistent Temporary Folder

Create 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 TemporaryFolderFixture 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.TemporaryFolderFixture
            testCase.applyFixture(TemporaryFolderFixture ...
                ("PreservingOnFailure",true,"WithSuffix","_TestData"));

            % Failing test
            act = 3.1416;
            exp = pi;
            testCase.verifyEqual(act,exp)
        end
    end
end

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

runtests("PersistentFolderTest");

Running PersistentFolderTest

================================================================================
Verification failed in PersistentFolderTest/testWithTemporaryFolder.
    ---------------------
    Framework Diagnostic:
    ---------------------
    verifyEqual failed.
    --> The numeric values are not equal using "isequaln".
    --> Failure table:
            Actual        Expected               Error               RelativeError    
            ______    ________________    ____________________    ____________________
                                                                                      
            3.1416    3.14159265358979    7.34641020683213e-06    2.33843499679617e-06
    
    Actual Value:
       3.141600000000000
    Expected Value:
       3.141592653589793
    ----------------------
    Additional Diagnostic:
    ----------------------
    Temporary folder preserved on failure: C:\Temp\tpa00d0db0_45f0_4b3f_9ce9_3323db8df9de_TestData
    ------------------
    Stack Information:
    ------------------
    In C:\work\PersistentFolderTest.m (PersistentFolderTest.testWithTemporaryFolder) at 11
================================================================================

[Terse] Diagnostic logged (2022-10-04 09:23:49):
Because of a failure in the test using the TemporaryFolderFixture, the following folder will not be deleted:
C:\Temp\tpa00d0db0_45f0_4b3f_9ce9_3323db8df9de_TestData
.
Done PersistentFolderTest
__________

Failure Summary:

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

Tips

• Instead of using the TemporaryFolderFixture class, you can use the createTemporaryFolder method to create a temporary folder for your test. However, more functionality is available when you create a temporary folder using the TemporaryFolderFixture class.

• Both the TemporaryFolderFixture and WorkingFolderFixture 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 R2013b