Main Content

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

expand all in page

Description

The matlab.automation.streams.ToUniqueFile class creates 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. Each instance of ToUniqueFile creates a file with a unique filename. For example, this output stream is useful for running tests in parallel while redirecting output to a file.

MATLAB® creates the unique filename for the output stream, but you can specify a file prefix and extension.

Construction

stream = matlab.automation.streams.ToUniqueFile(folder) creates an output stream to write text to a unique file in the specified folder.

stream = matlab.automation.streams.ToUniqueFile(folder,Name,Value) creates a unique file with additional options specified by one or more name-value arguments. You can specify several name-value arguments in any order as Name1,Value1,...,NameN,ValueN.

Input Arguments

expand all

Name of existing folder, specified as a character vector or string scalar. The output stream writes to a file in folder.

Example: 'myOutput'

Example: pwd

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.

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

Example: matlab.automation.streams.ToUniqueFile(pwd,'WithPrefix','myOutput_') creates an output stream to write to a file in the current folder that starts with 'myOutput_'.

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

Example: 'outputA_'

Extension for the filename, specified as a character vector or string scalar. By default, the filename has the extension '.txt'. Extensions must begin with a period.

Example: '.xml'

Properties

expand all

Full name of the file to redirect text output from the plugin, returned as a string scalar.

Copy Semantics

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

Examples

collapse all

Produce TAP output for a suite of tests that you run in parallel. To avoid having the framework overwrite the TAP file, direct the output from each group of tests to a unique file. To run tests in parallel, this example requires Parallel Computing Toolbox™.

Create the following parameterized test in a file in your current working folder.

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 logarithmicly spaced sizes up to 100
    sizes = num2cell(round(logspace(0,2,10)));
end

At the command prompt, create a folder for output files.

mkdir myOutput

Create a suite from TestRand.m and a test runner with terse output. The suite contains 1200 test elements.

suite = matlab.unittest.TestSuite.fromClass(?TestRand);
runner = matlab.unittest.TestRunner.withTextOutput('OutputDetail',1);

Create an instance of a stream that writes to a unique file in the myOutput folder. Then create a TAPPlugin instance and direct the output to the stream. Each created file begins with 'myTapFile_' and ends with the '.tap' extension.

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

stream = ToUniqueFile('myOutput','WithPrefix','myTapFile_','WithExtension','.tap');
plugin = TAPPlugin.producingOriginalFormat(stream);

Add the plugin to the test runner, and run the test suite in parallel. Your test groups and the output filenames might vary.

runner.addPlugin(plugin)
result = runner.runInParallel(suite);
Split tests into 18 groups and running them on 6 workers.
----------------
Finished Group 5
----------------
..................................................
.......................

----------------
Finished Group 6
----------------
..................................................
.....................

----------------
Finished Group 4
----------------
..................................................
........................

----------------
Finished Group 1
----------------
..................................................
............................

----------------
Finished Group 3
----------------
..................................................
..........................

----------------
Finished Group 2
----------------
..................................................
...........................

----------------
Finished Group 7
----------------
..................................................
....................

----------------
Finished Group 8
----------------
..................................................
...................

-----------------
Finished Group 11
-----------------
..................................................
...............

----------------
Finished Group 9
----------------
..................................................
.................

-----------------
Finished Group 12
-----------------
..................................................
.............

-----------------
Finished Group 10
-----------------
..................................................
................

-----------------
Finished Group 16
-----------------
..................................................
........

-----------------
Finished Group 18
-----------------
..................................................
....

-----------------
Finished Group 17
-----------------
..................................................
.......

-----------------
Finished Group 13
-----------------
..................................................
............

-----------------
Finished Group 14
-----------------
..................................................
...........

-----------------
Finished Group 15
-----------------
..................................................
.........

View the output files in the myOutput folder. Since MATLAB ran the tests in 18 groups, the framework created 18 instances of the ToUniqueFile output stream. There are 18 associated output files.

dir myOutput
.                                                   
..                                                  
myTapFile_22dc996d-e1e9-44e2-af3a-e8e9c68c6941.tap  
myTapFile_2de69eb4-591f-4456-9890-31626e57792f.tap  
myTapFile_3e88b1fb-5679-4489-b9c9-a2b22ac76cb1.tap  
myTapFile_4b660dae-9e33-4e89-bd1b-27c874749476.tap  
myTapFile_56d584a8-2bf2-4677-ad25-5f268628c179.tap  
myTapFile_632c3723-c300-40a6-8ffa-a7dbd0d07d65.tap  
myTapFile_66276292-5062-489a-9219-cc2664f48fb8.tap  
myTapFile_78d69693-720a-4a14-86b3-de687b1ddf91.tap  
myTapFile_7df3915c-60de-4c7f-8968-b5260d4c2933.tap  
myTapFile_827a6d46-54c6-4ee3-bfbb-0d46d4024fcf.tap  
myTapFile_97af3692-7b4a-4f80-a81a-96fc0f86beed.tap  
myTapFile_9cb0cdb1-4f30-40a0-8f5f-51da8af7bb86.tap  
myTapFile_b8820e56-7c92-41eb-b040-94f55399766b.tap  
myTapFile_c1bfd286-7fa4-4365-b456-4babf2a995da.tap  
myTapFile_c53c2906-14a7-41eb-a87c-d1fd727e6d9e.tap  
myTapFile_decbc713-84c0-4139-b3e4-d2b8c2e273bf.tap  
myTapFile_e1687147-f8a7-4f6d-aea0-a3e885246dd6.tap  
myTapFile_f78c98a7-6c14-4981-ae03-fc8ffbeddaf8.tap

Extended Capabilities

Version History

Introduced in R2018a

expand all

See Also

| | |