Configure Test Settings for Build Tool by Using MATLAB Test Manager

Since R2025a

When you run tests by using the MATLAB^® build tool, you can use test and coverage settings that you specify in the MATLAB Test Manager. Configure the settings in the test manager and then copy a code snippet for the build configuration into your build file. The code snippet specifies the settings for coverage, output detail, logging level, and strict checks, and specifies the tests to run based on the current test suite in the MATLAB Test Manager. To avoid unexpected behavior, do not use the code snippet generated from one project in the build file for a different project.

For more information about MATLAB build tool, see Overview of MATLAB Build Tool.

Create Build File

To define a build for your project, create a build file in your project root folder. A build file is a function file that creates a plan with tasks.

• To create the build file programmatically, in MATLAB, navigate to your project root folder. At the Command Window, execute this code.

  buildtool -init

• To create the build file interactively, open the project. In the Project tab, click Run Build > Create build file.

Both approaches create this basic build file.

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

plan = buildplan(localfunctions);

plan("clean") = CleanTask;
plan("check") = CodeIssuesTask;
plan("test") = TestTask;

plan.DefaultTasks = ["check" "test"];
end

This build file:

• Uses the buildplan function with localfunctions as an input to create a plan that adds the tasks from local task functions to the plan

• Uses the CleanTask class to add a task that deletes the outputs and traces of tasks

• Uses the CodeIssuesTask class to add a task that analyzes files in the project for code issues

• Uses the TestTask class to add a task that runs the tests in the project and fails the build if one of the tests fails

• Makes "check" and "test" the default tasks in the plan

For more information about other tasks that you can include in your build file, see Create and Run Tasks Using Build Tool.

Configure Settings in MATLAB Test Manager

In the MATLAB Test Manager, configure the test and coverage settings to use with the build tool. Specify the tests to run with the build tool by selecting a test suite.

Specify Test and Coverage Settings

To configure test settings for output detail, strict checks, and logging level, in the menu, click the Settings button . Configure the settings in the Test Run Settings dialog box. For more information, see Customize Test Run.

To enable code coverage, in the menu, click the Code Coverage button and select Enable code coverage. Set the code coverage metric level to Statement, Decision, Condition, or MC/DC. For more information about code coverage types, see Types of Code Coverage for MATLAB Source Code.

Specify Tests to Run

To run all tests in the project, in the menu, in the drop-down list on the left, select All Tests in Current Project.

To run a subset of tests in the project, create a custom test suite, and then select it. For more information, see Create, Manage, and Run Test Suites.

Copy Test and Coverage Settings to Build File

Generate and use a code snippet that defines a task that uses test and coverage settings from the MATLAB Test Manager:

1. Generate the code snippet. In the MATLAB Test Manager, in the menu, click the Build Configuration button .

2. Copy the code snippet. In the Copy Current Test Configuration for Build File window, click the Copy button .

3. Open the build file in the MATLAB Editor. Delete the code that defines a task that runs tests.

   plan("test") = TestTask;

4. Paste the code snippet in the build file.

   function plan = buildfile
   import matlab.buildtool.tasks.*
   
   plan = buildplan(localfunctions);
   
   plan("clean") = CleanTask;
   plan("check") = CodeIssuesTask;
   % "plan" refers to the matlab.buildtool.Plan object
   proj = plan.Project;
   testFiles = proj.findFiles(Category= ...
      "Classification", Label="Test", IncludeReferences=true);
   sourceFiles = proj.findFiles(Category= ...
      "Classification", Label="Design", IncludeReferences=true);
   
   import matlab.buildtool.tasks.TestTask
   import matlab.unittest.constraints.EndsWithSubstring
   import matlab.unittest.selectors.*
   plan("test") = TestTask(testFiles, SourceFiles=sourceFiles, ...
      TestResults=fullfile("test-results", "report.html"), ...
      Selector=~HasName(EndsWithSubstring(".p")) ...
      & ~HasName(EndsWithSubstring(".mldatx")), ...
      Strict=false).addCodeCoverage( ...
      fullfile("code-coverage", "report.html"), MetricLevel="statement");
   
   plan.DefaultTasks = ["check" "test"];
   end

   The build file now:

   • Specifies the source code and test code files by using the Project property of the matlab.buildtool.Plan class

   • Uses the TestTask class to add a task that runs the tests using the test and coverage settings that you configured in the MATLAB Test Manager

Run Tests by Using Build Tool

You can use the build tool to run the tests programmatically or interactively.

• To run the tests programmatically, use the buildtool function. You can run only the "test" task by executing this code.

  buildtool test

• To run the tests interactively, in the Project tab, click Run Build > test.

Tip

You can also run only the tests that are impacted by changes since the last run. For more information, see Run Impacted Tests Using MATLAB Build Tool.

To view the test and coverage results, open the test and coverage reports. When you run the tests, the build tool saves an HTML test report to the test-results folder. If the tests run with coverage enabled, the build tool saves an HTML coverage report to the code-coverage folder.