matlab.buildtool.tasks.TestTask Class

Namespace: matlab.buildtool.tasks
Superclasses: matlab.buildtool.Task

Task for running tests

Since R2023b

expand all in page

Description

The matlab.buildtool.tasks.TestTask class provides a task for running a suite of tests using the MATLAB® unit testing framework.

To improve build performance, a TestTask instance supports incremental builds as well as running only the tests impacted by changes:

  • If the task is up to date, then the build tool skips the task. For details on how the build tool handles the task in incremental builds, see Up-To-Date Check.

  • If you have a MATLAB Test™ license, you can configure the task to run only the tests impacted by changes since the last successful task run. For more information, see Run Impacted Tests Using MATLAB Build Tool (MATLAB Test). (since R2025a)

Creation

Description

task = matlab.buildtool.tasks.TestTask creates a task for running the tests in the current folder and its subfolders. The task fails if any of the tests fail.

example

task = matlab.buildtool.tasks.TestTask(tests) creates a task that runs the tests in the specified files and folders, including their subfolders.

task = matlab.buildtool.tasks.TestTask(___,Name=Value) sets writable properties using one or more name-value arguments in addition to any of the input argument combinations in previous syntaxes. You can also set the Description and Dependencies properties, which the class inherits from the Task class, using name-value arguments. For example, task = matlab.buildtool.tasks.TestTask(TestResults="results.xml") creates a task that produces test results in JUnit-style XML format.

example

Input Arguments

expand all

Test files and folders to run, specified as a string vector, character vector, cell vector of character vectors, or matlab.buildtool.io.FileCollection vector. For example, you can specify a test file, a folder that contains test files, or a project folder that contains test files. By default, the task runs the tests in the current folder and its subfolders.

This argument sets the Tests property.

Properties

expand all

In addition to these properties, the TestTask class inherits properties from the Task class. Of the inherited properties, you can set the Description and Dependencies properties using name-value arguments during task creation.

Test files and folders to run, specified as a string vector, character vector, cell vector of character vectors, or matlab.buildtool.io.FileCollection vector, and stored as a matlab.buildtool.io.FileCollection row vector. For example, you can specify a test file, a folder that contains test files, or a project folder that contains test files. By default, the task runs the tests in the current folder and its subfolders.

If Tests contains tests created using Simulink® Test, the task provides access to their results. You must have a Simulink Test license to run tests created using Simulink Test. (since R2024a)

Attributes:

GetAccess
public
SetAccess
public

Source files and folders under test, specified as a string vector, character vector, cell vector of character vectors, or matlab.buildtool.io.FileCollection vector, and stored as a matlab.buildtool.io.FileCollection row vector. Set this property if you use the CodeCoverageResults property or addCodeCoverage method to collect code coverage information. The specified source code must be on the MATLAB search path when the task runs the tests and collects code coverage information.

Note

If you do not set the SourceFiles property, the build tool does not skip the task. For more information on how the build tool treats the task in incremental builds, see Up-To-Date Check.

Attributes:

GetAccess
public
SetAccess
public

Since R2025a

Supporting files and folders used by the tests, specified as a string vector, character vector, cell vector of character vectors, or matlab.buildtool.io.FileCollection vector, and stored as a matlab.buildtool.io.FileCollection row vector. Use this property to specify auxiliary files and folders that tests depend on in addition to the files and folders in SourceFiles, such as test data and helper files.

Note

When performing a code coverage analysis, the task does not include the files and folders in SupportingFiles. To specify the files and folders to collect coverage for, use the SourceFiles property.

Attributes:

GetAccess
public
SetAccess
public

Option to run the tests in subfolders, specified as a numeric or logical 1 (true) or 0 (false). By default, the task runs the tests in the specified folders and their subfolders.

Attributes:

GetAccess
public
SetAccess
public

Test tag, specified as a string vector, character vector, or cell vector of character vectors. If you specify test tags, the task filters the test suite and runs only the tests that have at least one of the specified tags. For more information about test tags, see Tag Unit Tests.

Attributes:

GetAccess
public
SetAccess
public

Since R2025a

Test selector, specified as a matlab.unittest.selectors.Selector object. If you specify a selector, the task filters the test suite and runs only the tests that satisfy the conditions set by the specified selector. For example, create a task that runs the tests in the feature1 subfolder of your current folder that have the "Unit" tag.

import matlab.buildtool.tasks.TestTask
import matlab.unittest.selectors.*

task = TestTask(Selector= ...
    HasBaseFolder(fullfile(pwd,"feature1")) & HasTag("Unit"));

Attributes:

GetAccess
public
SetAccess
public

Since R2025a

Option to run only the tests impacted by code or data changes since the last successful task run, specified as a numeric or logical 0 (false) or 1 (true). By default, the task runs all the tests in the test suite when it reruns. However, if RunOnlyImpactedTests is true, the task runs only these tests:

  • Modified or new tests

  • Tests with a modified test class folder or test superclass

  • Tests that depend on modified or new source files (specified in the SourceFiles property)

  • Tests that depend on modified or new supporting files (specified in the SupportingFiles property)

To identify impacted tests, the task runs a dependency analysis similar to that of the Dependency Analyzer app. For more information about dependency analysis and its limitations, see Dependency Analyzer Scope and Limitations.

Note

The task runs all the tests regardless of the value of RunOnlyImpactedTests if either of these conditions is true:

  • You do not have a MATLAB Test license.

  • You have not specified any source code (the SourceFiles property is empty).

In addition to using the RunOnlyImpactedTests property, you can choose whether to run only the impacted tests at task run time by specifying the RunOnlyImpactedTests task argument. For more information, see RunOnlyImpactedTests Task Argument.

Attributes:

GetAccess
public
SetAccess
public

Display level of event details, specified as an integer scalar from 0 through 4, a matlab.automation.Verbosity enumeration object, or a text representation of the enumeration.

Numeric RepresentationEnumeration Member NameVerbosity Description
0None

No information

1Terse

Minimal information

2Concise

Moderate amount of information

3Detailed

Some supplemental information

4Verbose

Lots of supplemental information

By default, the task displays failing and logged events at the matlab.automation.Verbosity.Detailed level (level 3) and test run progress at the matlab.automation.Verbosity.Terse level (level 1).

Example: task = matlab.buildtool.tasks.TestTask(OutputDetail="verbose") creates a task that displays event details at the matlab.automation.Verbosity.Verbose level.

Attributes:

GetAccess
public
SetAccess
public

Verbosity level of logged diagnostics, specified as an integer scalar from 0 through 4, a matlab.automation.Verbosity enumeration object, or a text representation of the enumeration. The task includes diagnostics logged at the specified level and below.

Numeric RepresentationEnumeration Member NameVerbosity Description
0None

No information

1Terse

Minimal information

2Concise

Moderate amount of information

3Detailed

Some supplemental information

4Verbose

Lots of supplemental information

By default, the task includes diagnostics logged at the matlab.automation.Verbosity.Terse level (level 1). To exclude logged diagnostics, specify LoggingLevel as matlab.automation.Verbosity.None (level 0).

Logged diagnostics are diagnostics that you supply to the unit testing framework with the log (TestCase) and log (Fixture) methods.

Example: task = matlab.buildtool.tasks.TestTask(LoggingLevel="detailed") creates a task that includes diagnostics logged at the matlab.automation.Verbosity.Detailed level and below.

Attributes:

GetAccess
public
SetAccess
public

Option to apply strict checks when running the tests, specified as a numeric or logical 0 (false) or 1 (true). If the value is true, the task produces a qualification failure when a test issues a warning. By default, the task does not apply strict checks when running the tests.

Attributes:

GetAccess
public
SetAccess
public

Since R2024a

Test results, specified as a string vector, character vector, cell vector of character vectors, or matlab.buildtool.io.File vector, and stored as a matlab.buildtool.io.File row vector. You can set this property during creation of the task.

The task can produce test results in various formats. Specify formats by using file extensions:

  • .html — Produce test results as a single-file HTML test report.

  • .pdf — Produce test results as a PDF test report.

  • .xml — Produce test results in JUnit-style XML format.

  • .mat — Save the matlab.unittest.TestResult array to a MAT file.

  • .mldatx — Export Simulink Test Manager results in MLDATX format (requires Simulink Test). (since R2024a)

Example: task = matlab.buildtool.tasks.TestTask(TestResults="test-results/report.html") creates a task that produces a single-file HTML test report.

Example: task = matlab.buildtool.tasks.TestTask(TestResults=["test-results/results.xml" "test-results/results.mat"]) creates a task that produces test results in both JUnit-style XML and MAT-file formats.

Attributes:

GetAccess
public
SetAccess
private

Since R2024a

Code coverage results, specified as a string vector, character vector, cell vector of character vectors, or matlab.buildtool.io.File vector, and stored as a matlab.buildtool.io.File row vector. You can set this property during creation of the task. Alternatively, you can set this property by using the addCodeCoverage method, which gives you more flexibility in producing code coverage results. For example, the method provides access to additional coverage metrics (requires MATLAB Test).

The task can produce code coverage results in various formats. Specify formats by using file extensions when you assign a value to the property:

  • .html — Produce an interactive HTML code coverage report.

  • .xml — Produce code coverage results in Cobertura XML format.

  • .mat — Save the matlab.coverage.Result array to a MAT file.

Note

To collect code coverage information, you must specify your MATLAB source code by setting the SourceFiles property.

Example: task = matlab.buildtool.tasks.TestTask(SourceFiles="mySource",CodeCoverageResults="code-coverage/report.html") creates a task that produces an interactive HTML code coverage report for the specified source code.

Example: task = matlab.buildtool.tasks.TestTask(SourceFiles="mySource",CodeCoverageResults=["code-coverage/results.xml" "code-coverage/results.mat"]) creates a task that produces code coverage results in both Cobertura XML and MAT-file formats for the specified source code.

Attributes:

GetAccess
public
SetAccess
private

Since R2024a

Model coverage results for the models in Simulink Test and MATLAB-based Simulink tests of the Tests property (requires Simulink Test and Simulink Coverage™), specified as a string vector, character vector, cell vector of character vectors, or matlab.buildtool.io.File vector, and stored as a matlab.buildtool.io.File row vector. You can set this property during creation of the task. Alternatively, you can set this property by using the addModelCoverage method, which gives you more flexibility in producing model coverage results. For example, the method lets you customize the model coverage options instead of relying on the options already applied in Simulink Test.

The task can produce model coverage results in various formats. Specify formats by using file extensions:

  • .html — Produce an HTML model coverage report.

  • .xml — Produce model coverage results in Cobertura XML format.

Example: task = matlab.buildtool.tasks.TestTask(ModelCoverageResults="model-coverage/report.html") creates a task that produces an HTML model coverage report.

Example: task = matlab.buildtool.tasks.TestTask(ModelCoverageResults=["model-coverage/report.html" "model-coverage/results.xml"]) creates a task that produces an HTML model coverage report as well as model coverage results in Cobertura XML format.

Attributes:

GetAccess
public
SetAccess
private

Methods

expand all

Examples

collapse all

Open Live Script

Run the tests in your project by using the TestTask class.

Open the example and then navigate to the test_task_example folder, which contains a build file, a source file named quadraticSolver.m, and a test file named SolverTest.m. For more information about the source and test files used in this example, see Write Simple Test Case Using Classes.

cd test_task_example

This code shows the contents of the build file. The build file contains one task that runs the tests in the current folder and its subfolders and fails the build if any of the tests fail.

function plan = buildfile
import matlab.buildtool.tasks.TestTask

% Create a plan with no tasks
plan = buildplan;

% Add a task to run the tests in the project
plan("test") = TestTask;
end

Run the "test" task. In this example, all the tests pass, and the task runs successfully. 

buildtool test
** Starting test
...

Test Summary:
    Total Tests: 3
         Passed: 3
         Failed: 0
     Incomplete: 0
       Duration: 0.04164 seconds testing time.
                 
** Finished test
Open Live Script

Run your tests and generate test and coverage results by using the TestTask class.

Open the example and then navigate to the test_task_example1 folder, which contains a build file, a source file named quadraticSolver.m, and a test file named SolverTest.m. For more information about the source and test files used in this example, see Write Simple Test Case Using Classes.

cd test_task_example1

This code shows the contents of the build file. The build file contains one task that:

  • Runs the tests in the current folder and its subfolders and fails the build if any of the tests fail

  • Produces test results in JUnit-style XML format

  • Produces code coverage results in Cobertura XML format for the source code in quadraticSolver.m

function plan = buildfile
import matlab.buildtool.tasks.TestTask

% Create a plan with no tasks
plan = buildplan;

% Add a task to run tests and generate test and coverage results
plan("test") = TestTask(SourceFiles="quadraticSolver.m", ...
    TestResults="test-results/results.xml", ...
    CodeCoverageResults="code-coverage/results.xml");
end

Run the "test" task. The task runs the tests and saves the test and coverage results to the specified locations in your current folder. In this example, all the tests pass, and the task runs successfully. 

buildtool test
** Starting test
...

Test Summary:
    Total Tests: 3
         Passed: 3
         Failed: 0
     Incomplete: 0
       Duration: 0.023641 seconds testing time.
                 

Test Results:
    JUnit: test-results\results.xml

Code Coverage:
    Cobertura: code-coverage\results.xml
** Finished test

More About

expand all

Tips

  • A TestTask instance respects the build output verbosity level specified at run time using the -verbosity option of the buildtool command. The run-time verbosity level takes precedence over any values specified in the OutputDetail and LoggingLevel properties. (since R2024b)

  • To select tests by tag, use the Tag or Selector property. For example, using the Tag property, create a task that runs the tests with the "Feature1" tag.

    task = matlab.buildtool.tasks.TestTask(Tag="Feature1");

    Alternatively, create a task that runs the same tests by using the Selector property. (since R2025a)

    task = matlab.buildtool.tasks.TestTask( ...
    Selector=matlab.unittest.selectors.HasTag("Feature1"));

    If you specify tags by using both the Tag and Selector properties, then the task runs only the tests that have all the specified tags. For example, this code creates a task that runs the tests with both the "Feature1" and "Feature2" tags.

    task = matlab.buildtool.tasks.TestTask( ...
    Tag="Feature1",Selector=matlab.unittest.selectors.HasTag("Feature2"));

  • You cannot overwrite or remove the action of a built-in task, but you can specify additional task actions. For example, append an action to the Actions property of a built-in task.

    plan("myTask").Actions(end+1) = @myAction;

  • If you use MATLAB Test Manager to manage your tests (requires MATLAB Test), you can generate a code snippet that includes a TestTask instance configured with the test and coverage settings from the test manager. For more information, see Configure Test Settings for Build Tool by Using MATLAB Test Manager (MATLAB Test). (since R2025a)

Version History

Introduced in R2023b

expand all

See Also

Functions

Topics