matlab.automation.streams.ToUniqueFile Class

Namespace: matlab.automation.streams
Superclasses: matlab.automation.streams.OutputStream

Output stream to write text to unique file

Renamed from matlab.unittest.plugins.ToUniqueFile in R2023a

Description

The matlab.automation.streams.ToUniqueFile class provides an output stream to write text to a unique, UTF-8 encoded file. Whenever text prints to this stream, the output stream opens the file, appends the text, and closes the file.

A ToUniqueFile instance prevents text output from being overwritten when saving data to disk. For example, when running tests in parallel (requires Parallel Computing Toolbox™), you can use this class to direct results from test suite portions to separate files.

The matlab.automation.streams.ToUniqueFile class is a handle class.

Creation

Description

stream = matlab.automation.streams.ToUniqueFile(folderName) creates an output stream to write text to a unique file in the specified folder. The testing framework creates a unique filename for the output stream.

stream = matlab.automation.streams.ToUniqueFile(folderName,Name=Value) specifies options using one or more name-value arguments. For example, stream = matlab.automation.streams.ToUniqueFile(pwd,WithPrefix="myOutput_") creates an output stream to write text to a unique file whose name starts with "myOutput_" in the current folder.

Input Arguments

folderName — Name of folder

string scalar | character vector

Name of an existing folder, specified as a string scalar or character vector. The output stream writes to a unique file in folderName. The value of folderName can be a path relative to the current folder or an absolute path.

Example: pwd

Example: "C:\work\myFolder"

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: stream = matlab.automation.streams.ToUniqueFile(pwd,WithPrefix="myOutput_")

WithPrefix — Prefix for filename

string scalar | character vector

Prefix for the filename, specified as a string scalar or character vector.

Example: WithPrefix="myOutput_"

WithExtension — File extension

".txt" (default) | string scalar | character vector

File extension, specified as a string scalar or character vector that starts with a period. By default, the output stream writes to a file with the ".txt" extension.

Example: WithExtension=".xml"

Properties

Filename — Absolute path of file to write text to

string scalar

Absolute path of the unique file to write text to, represented as a string scalar.

Attributes:

GetAccess	public
SetAccess	private

Examples

Direct Output from Tests That Run in Parallel

Using the ToUniqueFile class, store test results in TAP format when running tests in parallel (requires Parallel Computing Toolbox).

In a file named TestRand.m in your current folder, create the parameterized TestRand test class, which tests the MATLAB^® random number generator. The test class results in 1200 tests.

classdef TestRand < matlab.unittest.TestCase
    properties (TestParameter)
        dim1 = createDimensionSizes;
        dim2 = createDimensionSizes;
        dim3 = createDimensionSizes;
        type = {'single','double'};
    end

    methods (Test)
        function testRepeatable(testCase,dim1,dim2,dim3)
            state = rng;
            firstRun = rand(dim1,dim2,dim3);
            rng(state)
            secondRun = rand(dim1,dim2,dim3);
            testCase.verifyEqual(firstRun,secondRun)
        end
        function testClass(testCase,dim1,dim2,type)
            testCase.verifyClass(rand(dim1,dim2,type),type)
        end
    end
end

function sizes = createDimensionSizes
% Create logarithmically spaced sizes up to 100
sizes = num2cell(round(logspace(0,2,10)));
end

Import the classes used in this example.

import matlab.unittest.plugins.TAPPlugin
import matlab.automation.streams.ToUniqueFile

In your current folder, create a folder named myOutput to contain the results of running the TestRand class.

mkdir myOutput

Create a test runner with a plugin that produces TAP test results and writes them to a unique file, whose name starts with "myFile_" and ends with ".tap", in the myOutput folder. When creating the plugin, specify an instance of the ToUniqueFile class.

runner = testrunner;
stream = ToUniqueFile("myOutput", ...
    WithPrefix="myFile_",WithExtension=".tap");
plugin = TAPPlugin.producingOriginalFormat(stream);
runner.addPlugin(plugin)

Create a test suite from the test class and run the tests in parallel. In this example, the testing framework divides the test suite into 18 groups and runs each group on the parallel pool. All the tests pass.

suite = testsuite("TestRand");
results = runner.runInParallel(suite);

Starting parallel pool (parpool) using the 'Processes' profile ...
Connected to parallel pool with 6 workers.
Split tests into 18 groups and running them on 6 workers.
----------------
Finished Group 1
----------------
Running TestRand
.......... .......... .......... .......... ..........
.......... .......... ........
Done TestRand
__________


----------------
Finished Group 2
----------------
Running TestRand
.......... .......... .......... .......... ..........
.......... .......... .......
Done TestRand
__________


----------------
Finished Group 3
----------------
Running TestRand
.......... .......... .......... .......... ..........
.......... .......... ......
Done TestRand
__________


----------------
Finished Group 4
----------------
Running TestRand
.......... .......... .......... .......... ..........
.......... .......... ....
Done TestRand
__________


----------------
Finished Group 5
----------------
Running TestRand
.......... .......... .......... .......... ..........
.......... .......... ...
Done TestRand
__________


----------------
Finished Group 6
----------------
Running TestRand
.......... .......... .......... .......... ..........
.......... .......... .
Done TestRand
__________


----------------
Finished Group 9
----------------
Running TestRand
.......... .......... .......... .......... ..........
.......... .......
Done TestRand
__________


----------------
Finished Group 7
----------------
Running TestRand
.......... .......... .......... .......... ..........
.......... ..........
Done TestRand
__________


----------------
Finished Group 8
----------------
Running TestRand
.......... .......... .......... .......... ..........
.......... .........
Done TestRand
__________


-----------------
Finished Group 10
-----------------
Running TestRand
.......... .......... .......... .......... ..........
.......... ......
Done TestRand
__________


-----------------
Finished Group 11
-----------------
Running TestRand
.......... .......... .......... .......... ..........
.......... .....
Done TestRand
__________


-----------------
Finished Group 12
-----------------
Running TestRand
.......... .......... .......... .......... ..........
.......... ...
Done TestRand
__________


-----------------
Finished Group 18
-----------------
Running TestRand
.......... .......... .......... .......... ..........
....
Done TestRand
__________


-----------------
Finished Group 16
-----------------
Running TestRand
.......... .......... .......... .......... ..........
........
Done TestRand
__________


-----------------
Finished Group 17
-----------------
Running TestRand
.......... .......... .......... .......... ..........
.......
Done TestRand
__________


-----------------
Finished Group 14
-----------------
Running TestRand
.......... .......... .......... .......... ..........
.......... .
Done TestRand
__________


-----------------
Finished Group 13
-----------------
Running TestRand
.......... .......... .......... .......... ..........
.......... ..
Done TestRand
__________


-----------------
Finished Group 15
-----------------
Running TestRand
.......... .......... .......... .......... ..........
.........
Done TestRand
__________

Verify that the test results exist in the myOutput folder. Because the framework divided the test suite into 18 groups, it also created 18 unique files to store the outputs from each corresponding group.

dir myOutput

.                                                myFile_4d8ec4ef-7102-4e68-bb75-23918b005f7c.tap  myFile_8fb7489c-e6fb-4489-87fb-1ed1b2aa81ce.tap  myFile_cb3271a0-58ce-4e63-b1fc-4983b7f487a8.tap  
..                                               myFile_4e92877d-a0a8-4f8d-874e-02fc4bddfe94.tap  myFile_8ff46633-a0d4-4344-baf3-d10a345099d1.tap  myFile_e08e6235-3db4-421a-a4f3-d4ff830fcc42.tap  
myFile_0e306ce6-a466-40a8-8f53-d72cfa3eb2f2.tap  myFile_77d9a7c3-0e4f-4783-b36c-dc8077fd0a6e.tap  myFile_b508184f-898d-4526-92cd-39c6905e3ce2.tap  
myFile_125582ae-8817-4a1d-86a7-6e6cce49b16e.tap  myFile_7a5826ee-659c-4671-aa29-a26b7fdaa61e.tap  myFile_b751e51c-8b62-43d8-8d80-7d87fdf4e9ad.tap  
myFile_213d2eb7-d25e-4843-b6a6-68eb5467a9de.tap  myFile_7dcc5a1d-9d30-418d-82f3-165de3f20753.tap  myFile_bbb0a1af-706f-4536-884f-d95b825fba3b.tap  
myFile_359e7eed-10c8-4416-bee4-807b30864a51.tap  myFile_817c2a0a-7de8-45a5-9c2b-b4da5407544d.tap  myFile_c830830c-4551-492e-aac7-68166577d997.tap  

Extended Capabilities

Thread-Based Environment

Run code in the background using MATLAB® backgroundPool or accelerate code with Parallel Computing Toolbox™ ThreadPool.

This class fully supports thread-based environments. For more information, see Run MATLAB Functions in Thread-Based Environment.

Version History

Introduced in R2018a

R2023a: Renamed from matlab.unittest.plugins.ToUniqueFile

To reflect support for additional automated workflows, matlab.unittest.plugins.ToUniqueFile is now named matlab.automation.streams.ToUniqueFile. The behavior of this class remains the same, and existing instances of matlab.unittest.plugins.ToUniqueFile in your code continue to work as expected. There are no plans to remove support for existing instances of matlab.unittest.plugins.ToUniqueFile.

R2023a: Write text to files in thread-based environment

You can use the ToUniqueFile class in a thread-based environment to write text to files.