matlab.automation.streams.ToFile Class

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

Output stream to write text to file

Renamed from matlab.unittest.plugins.ToFile in R2023a

Description

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

Many text-oriented plugins let you direct the text they produce in a configurable manner. You can pass a ToFile instance to these plugins to direct their text output to a file.

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

Creation

Description

stream = matlab.automation.streams.ToFile(filename) creates an output stream to write text to the specified file and sets the Filename property. The text from the stream is appended to the file.

Properties

Filename — Name of file to write text to

character vector

Name of the file to write text to, specified as a string scalar or character vector and returned as a character vector. Specify the value of this property during creation of the stream.

Attributes:

GetAccess	public
SetAccess	immutable

Examples

Write TAP Test Results to File

Write test results in TAP format to a file by using the ToFile class.

In your current folder, create a function-based test file named sampleTest.m. The file contains two tests that pass and one test that fails.

function tests = sampleTest
tests = functiontests(localfunctions);
end

function testA(testCase)      % Test passes
verifyEqual(testCase,2+3,5)
end

function testB(testCase)      % Test fails
verifyGreaterThan(testCase,13,42)
end

function testC(testCase)      % Test passes
verifySubstring(testCase,"Hello World!","llo")
end

Import the classes used in this example.

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

Create a test runner with a plugin that produces TAP test results and writes them to a specific file. To create the plugin, use an instance of the ToFile class.

runner = testrunner("minimal");
filename = "results.tap";
plugin = TAPPlugin.producingVersion13(ToFile(filename));
addPlugin(runner,plugin)

Create a test suite from the test file and run the tests. The test runner runs the tests, and the plugin directs its output to a file named results.tap in your current folder.

suite = testsuite("sampleTest.m");
run(runner,suite);

View the contents of the generated test artifact. The results in the file indicate that testA and testC passed but testB failed due to a verification failure.

disp(fileread(filename))

TAP version 13
1..3
ok 1 - sampleTest/testA
not ok 2 - sampleTest/testB
    ---
    Event:
        Event Name: 'VerificationFailed'
        Event Location: 'sampleTest/testB'
        Framework Diagnostic: |
            verifyGreaterThan failed.
            --> The value must be greater than the minimum value.
            
            Actual Value:
                13
            Minimum Value (Exclusive):
                42
        Stack: |
            In C:\work\sampleTest.m (testB) at 10
    ...
ok 3 - sampleTest/testC

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 R2014a

R2023a: Renamed from matlab.unittest.plugins.ToFile

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

R2023a: Write text to files in thread-based environment

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