matlab.buildtool.tasks.TestTask Class

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

Task for running tests

Since R2023b

Description

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

Tasks created with the TestTask class support incremental builds. To opt in to this performance optimization, set the SourceFiles property of your TestTask instance to a nonempty value. By default, with an empty SourceFiles property, a TestTask instance executes all tests in the test suite each time it runs:

• Source code and test code are both integral to testing workflows. If the MATLAB source code exercised by the tests changes and the TestTask instance is unaware of it, the build tool cannot assume that the task can be skipped. Specifying the SourceFiles property provides the build tool with the minimum set of task inputs that must be tracked to determine whether an unnecessary task rerun can be avoided. For details on how the build tool handles a TestTask instance in incremental builds, see Up-To-Date Check.

• If you have a MATLAB Test™ license, you can configure your TestTask instance for incremental testing, in addition to incremental building. If you enable incremental testing, the task executes only the tests impacted by changes to code and data, rather than the entire test suite, whenever it reruns. For more information, see Test Impact Analysis 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.

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.

Input Arguments

tests — Test files and folders to run

string vector | character vector | cell vector of character vectors | matlab.buildtool.io.FileCollection vector

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

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.

Tests — Test files and folders to run

string vector | character vector | cell vector of character vectors | matlab.buildtool.io.FileCollection vector

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

SourceFiles — MATLAB source files and folders

string vector | character vector | cell vector of character vectors | matlab.buildtool.io.FileCollection vector

MATLAB 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

SupportingFiles — Supporting files and folders used by tests

string vector | character vector | cell vector of character vectors | matlab.buildtool.io.FileCollection vector

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

IncludeSubfolders — Option to run tests in subfolders

true or 1 (default) | false or 0

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

Tag — Test tag

string vector | character vector | cell vector of character vectors

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

Selector — Test selector

matlab.unittest.selectors.Selector object

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

RunOnlyImpactedTests — Option to run only impacted tests (requires MATLAB Test)

false or 0 (default) | true or 1

Since R2025a

Option to run only the tests impacted by code or data changes, 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)

If the task does not identify any impacted tests, then it runs an empty test suite.

If you specify a source control revision using the BaseRevision property or task argument, then the task considers code and data changes since the specified revision. Otherwise, the task considers changes since its last successful run.

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 at task creation time in the build file, you can choose whether to run only the impacted tests at task run time by specifying the RunOnlyImpactedTests or BaseRevision task argument. For more information, see Task Arguments.

Attributes:

GetAccess	public
SetAccess	public

BaseRevision — Base source control revision for test impact analysis (requires MATLAB Test)

0-by-0 string array (default) | string scalar | character vector

Since R2026a

Base source control revision for test impact analysis, specified as a string scalar or character vector. Use this property with the RunOnlyImpactedTests property or task argument to control the change detection window—that is, the window in which the task detects changes to code and data for test impact analysis. If you specify a revision, the task considers code and data changes since the specified revision and runs the impacted tests in the repository accordingly. By default, the BaseRevision property is empty, so the task considers changes since its last successful run for test impact analysis.

Note

BaseRevision supports only Git™ source control. For more information on how to use Git source control in MATLAB, see Set Up Git Source Control.

Specifying a revision for test impact analysis requires the plan root folder to be inside a Git repository with a revision history. When you specify a revision, the task detects changes to tests, source files, and supporting files since the specified revision by taking into account the following files in the Git repository:

• Committed files

• Modified files

• Untracked files

To set the BaseRevision property, specify the revision as a short, full, or relative commit ID. You can also specify the HEAD revision or use the Git API to programmatically access the commit ID. This table includes examples of supported values.

Revision Specifier	Example
Short commit ID	"08a4c49"
Full commit ID	"08a4c49d249a4dc3d998b473cdda186f1c05dfd0"
Branch name (relative commit ID)	"origin/main"
Reference to last (most recent) commit	"HEAD" or repo.LastCommit.ID

In addition to using the BaseRevision property at task creation time in the build file, you can use the BaseRevision task argument to control the revision at task run time. For more information, see Task Arguments.

Example: task = matlab.buildtool.tasks.TestTask(SourceFiles="source",RunOnlyImpactedTests=true,BaseRevision="HEAD") creates a task that runs the tests impacted by changes since the last commit.

Example: task = matlab.buildtool.tasks.TestTask(SourceFiles="source",RunOnlyImpactedTests=true,BaseRevision="origin/main") creates a task that runs the tests impacted by changes on the current branch since it diverged from the target main branch.

Attributes:

GetAccess	public
SetAccess	public

OutputDetail — Display level of event details

0 | 1 | 2 | 3 | 4 | matlab.automation.Verbosity enumeration object | text representation of enumeration

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 Representation	Enumeration Member Name	Verbosity Description
0	None	No information
1	Terse	Minimal information
2	Concise	Moderate amount of information
3	Detailed	Some supplemental information
4	Verbose	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

LoggingLevel — Verbosity level of logged diagnostics

1 (default) | 0 | 2 | 3 | 4 | matlab.automation.Verbosity enumeration object | text representation of enumeration

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 Representation	Enumeration Member Name	Verbosity Description
0	None	No information
1	Terse	Minimal information
2	Concise	Moderate amount of information
3	Detailed	Some supplemental information
4	Verbose	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

Strict — Option to apply strict checks

false or 0 (default) | true or 1

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

TestResults — Test results

string vector | character vector | cell vector of character vectors | matlab.buildtool.io.File vector

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

CodeCoverageResults — Code coverage results for MATLAB source code

string vector | character vector | cell vector of character vectors | matlab.buildtool.io.File vector

Since R2024a

Code coverage results for the MATLAB source files and folders in the SourceFiles property, 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 using the CodeCoverageResults property or addCodeCoverage method, 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

GeneratedCodeCoverageResults — Code coverage results for generated C/C++ code (requires MATLAB Test)

string vector | character vector | cell vector of character vectors | matlab.buildtool.io.File vector

Since R2026a

Code coverage results for the generated C/C++ code from equivalence tests in the Tests property, 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 addGeneratedCodeCoverage method, which gives you more flexibility in producing code coverage results. For example, the method provides access to additional coverage metrics.

The task can produce generated 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

Code coverage results for generated C/C++ code are supported only for equivalence tests that build static libraries and execute using software-in-the-loop (SIL) or processor-in-the-loop (PIL) verification.

Example: task = matlab.buildtool.tasks.TestTask(GeneratedCodeCoverageResults="code-coverage/report.html") creates a task that produces an interactive HTML code coverage report for generated C/C++ code.

Example: task = matlab.buildtool.tasks.TestTask(GeneratedCodeCoverageResults=["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 generated C/C++ code.

Attributes:

GetAccess	public
SetAccess	private

ModelCoverageResults — Model coverage results (requires Simulink Test)

string vector | character vector | cell vector of character vectors | matlab.buildtool.io.File vector

Since R2024a

Model coverage results for the models in Simulink Test and MATLAB-based Simulink tests in the Tests property, 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

Public Methods

addCodeCoverage	Enable code coverage collection for TestTask instance
addGeneratedCodeCoverage (MATLAB Test)	Enable generated code coverage collection for TestTask instance
addModelCoverage (Simulink Test)	Enable model coverage collection for TestTask instance

Examples

Run Tests in Project

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.023037 seconds testing time.
                 
** Finished test

Build Successful:
    1 Task: 0 Failed, 0 Skipped
    1.4027 sec total build time

Generate Test and Coverage Artifacts

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
...
Cobertura XML code coverage report has been saved to:
 C:\work\ExampleManager\user.examples\matlab-ex68575639\test_task_example1\code-coverage\results.xml

Test Summary:
    Total Tests: 3
         Passed: 3
         Failed: 0
     Incomplete: 0
       Duration: 0.05637 seconds testing time.
                 
Test Results:
    JUnit: C:\work\ExampleManager\user.examples\matlab-ex68575639\test_task_example1\test-results\results.xml
Code Coverage:
    Cobertura: C:\work\ExampleManager\user.examples\matlab-ex68575639\test_task_example1\code-coverage\results.xml
** Finished test

Build Successful:
    1 Task: 0 Failed, 0 Skipped
    5.9464 sec total build time

More About

Up-To-Date Check

The build tool checks whether a TestTask instance is up to date if:

• The SourceFiles property of the task is nonempty.

• The DisableIncremental property of the task is false.

To avoid redundant work, the build tool skips the task if the check passes. The build tool runs the task only if the tests, source files, supporting files, expected test outcome, or artifacts have changed since the last successful task run:

• Tests — If you modify a test file, test class folder, or superclass of a test or if you change the value of the Tests property, the build tool runs the task.

• Source and supporting files — If you have not specified any source files and folders or if you change the value of the SourceFiles or SupportingFiles property, the build tool runs the task.

• Test outcome — If it is possible to have a different test outcome, the build tool runs the task. Therefore, if you change the value of the IncludeSubfolders, Tag, Selector, RunOnlyImpactedTests, BaseRevision, or Strict property, or the value of a task argument, the build tool runs the task.

• Test and coverage artifacts — If you generate a new test or coverage artifact or if you modify or remove an existing artifact, the build tool runs the task.

Task Arguments

You can use the following task arguments to control the behavior of a TestTask instance at run time.

RunOnlyImpactedTests (since R2025a)

If you have a MATLAB Test license, you can choose whether to run only the impacted tests at task run time by specifying the RunOnlyImpactedTests task argument as true or false. Tests impacted by changes include: 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) If you specify a source control revision using the BaseRevision property or task argument, then the task considers code and data changes since the specified revision. Otherwise, the task considers changes since its last successful run. For example, suppose that your build file includes a matlab.buildtool.tasks.TestTask instance named "test" with its RunOnlyImpactedTests property set to false (default value). Because the property value is false, the task runs all the tests in the test suite and does not perform a test impact analysis. Override this behavior at run time by specifying the RunOnlyImpactedTests task argument as true. buildtool test(RunOnlyImpactedTests=true) Now, suppose that the "test" task has its RunOnlyImpactedTests property set to true. To override the task behavior at run time so that it runs all the tests in the test suite, specify the RunOnlyImpactedTests task argument as false. buildtool test(RunOnlyImpactedTests=false) Note If you have not specified any source code (the SourceFiles property is empty), then the task runs all the tests regardless of the value of RunOnlyImpactedTests.

BaseRevision (since R2026a)

If you have a MATLAB Test license, you can specify a base source control revision for test impact analysis using the BaseRevision task argument. You can also use this task argument to override the value specified in the corresponding BaseRevision property during task creation. Tip When you use the BaseRevision task argument, you do not need to specify the RunOnlyImpactedTests property or task argument as true. The task automatically performs impact-based testing given the BaseRevision task argument. Note BaseRevision supports only Git source control. For more information on how to use Git source control in MATLAB, see Set Up Git Source Control. To use BaseRevision, your plan root folder must be inside a Git repository with a revision history. When you specify a revision using the BaseRevision task argument, the task detects changes to tests, source files, and supporting files since the specified revision by considering the following files in the repository, and then runs the tests that are impacted by the detected changes. Committed files Modified files Untracked files You can specify the value of the BaseRevision task argument as a short, full, or relative commit ID. You can also use a commit reference, such as "HEAD". For example, suppose that your build file includes a matlab.buildtool.tasks.TestTask instance named "test" with a nonempty SourceFiles property, which is a requirement of test impact analysis. Run the tests impacted by changes to code and data in your repository since the last commit by specifying the BaseRevision task argument as "HEAD". buildtool test(BaseRevision="HEAD") Now, run the tests impacted by changes on the current branch since it diverged from the target main branch. buildtool test(BaseRevision="origin/main")

For more information about task arguments, see Create Tasks That Accept Arguments.

Tips

• To display the test results associated with a TestTask instance in the Test Browser app, first select the Use Test Browser option in the Run Build section on the MATLAB Toolstrip. Then, run the task interactively from the toolstrip or programmatically by specifying the -ui option of the buildtool command. For more information about the Use Test Browser option, see Run Build from Toolstrip. (since R2026a)

• If you run a build that includes a TestTask instance in parallel (requires Parallel Computing Toolbox™), the build tool schedules that instance to run on the MATLAB client rather than a MATLAB worker in the current parallel pool. The TestTask instance uses the parallelism of the MATLAB unit testing framework to run its tests in parallel.

• 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"));

• 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)

• If you specify the BaseRevision property or task argument (requires MATLAB Test) using a symbolic Git reference, such as "HEAD", the property or task argument value remains fixed to the reference name, even if the reference later moves and points to a different revision. This situation can occur when you update the repository through external Git operations, such as git fetch, which are outside the scope of the build tool. As a result, running a build with the same value of BaseRevision might lead to different results if the repository state has changed due to these external operations. For consistent build outcomes, ensure that the repository is in a known, stable state when using symbolic references. Alternatively, use unique commit IDs to explicitly specify the base revision for test impact analysis. (since R2026a)

• 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;

Version History

Introduced in R2023b

R2026a: Produce code coverage results for generated C/C++ code

If you have a MATLAB Test license, you can produce code coverage results for generated C/C++ code in equivalence tests by setting the GeneratedCodeCoverageResults property during task creation or by using the addGeneratedCodeCoverage method.

R2026a: Run tests impacted since source control revision

If you have a MATLAB Test license, you can specify a source control revision for test impact analysis by using the BaseRevision property or task argument.

R2025a: Run only impacted tests

If you have a MATLAB Test license, you can configure a task to run only the tests impacted by changes to code and data since the last successful task run. To run only the impacted tests, specify the RunOnlyImpactedTests property or task argument as true.

In addition to the RunOnlyImpactedTests property, the matlab.buildtool.tasks.TestTask class has a new property named SupportingFiles, which you can use to specify the supporting files and folders used by the tests. When running impacted tests, the task includes the tests that depend on modified or new supporting files.

R2025a: Filter test suite using selectors

To filter the test suite to run, use the Selector property.

R2024a: Programmatically access test or coverage results

The matlab.buildtool.tasks.TestTask class has three new properties: TestResults, CodeCoverageResults, and ModelCoverageResults. You can use these properties to programmatically access the test or coverage results. For example, you can return the paths to the test results by using p = plan("test").TestResults.paths'. You can also specify the test or coverage results as inputs of other tasks, for instance, plan("archive").Inputs = plan("test").CodeCoverageResults.

R2024a: Collect code coverage information using addCodeCoverage method

You can use the addCodeCoverage method to enable a task to collect code coverage information for your MATLAB source code. If you have a MATLAB Test license, you can also use the method to produce decision coverage, condition coverage, and modified condition/decision coverage (MC/DC) metrics.

R2024a: Produce Simulink Test Manager results and model coverage results

If you have a Simulink Test license, you can export Simulink Test Manager results in MLDATX format by setting the TestResults property during task creation. If you also have a Simulink Coverage™ license, you can produce model coverage results by setting the ModelCoverageResults property during task creation or by using the addModelCoverage method.