Automate Equivalence Tests by Using MATLAB Build Tool

Since R2026a

You can use the MATLAB^® build tool to automate running equivalence tests that:

• Generate C/C++ code using MATLAB Coder™ or Embedded Coder^®. For more information, see Generate C/C++ Code and Test for Equivalence.

• Generate deployed code artifacts using MATLAB Compiler SDK™. For more information, see Generate Deployed Code Artifacts and Test for Equivalence.

To automate running equivalence test by using the MATLAB build tool, create a build file, add a task to the build file, then run the tests and view the results. You can configure the task to generate test reports, customize test run settings, collect coverage for generated code, and more.

Alternatively, you can use the MATLAB Test Manager to generate a code snippet that defines a test task using the test and coverage settings from the MATLAB Test Manager. For more information, see Configure Test Settings for Build Tool by Using MATLAB Test Manager.

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

Create Build File

First, define a build file in your project. A build file is a function file that creates a plan with build tasks. Use one of these approaches to create a build file:

• To create the build file programmatically, in MATLAB, navigate to the project root folder. In 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.

The build file contains this code:

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 current folder and its subfolders for code issues

• Uses the TestTask class to add a task that runs the tests in the current folder and its subfolders 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 a build file, see Create and Run Tasks Using Build Tool.

Add and Configure Task

Add a task to the build file that specifies the tests to run. You can specify the location of a test or folder that contains tests or you can specify theTag or Selector properties of the matlab.buildtool.tasks.TestTask class. For example:

• This example code assigns a task to the plan called "equivalenceTest" that runs tests in the equivalenceTests folder.

  plan("equivalenceTest") = TestTask("equivalenceTests");

• This example code assigns a task to the plan called "equivalenceTest" that runs only the tests in the project that have the equivalence tag.

  plan("equivalenceTest") = TestTask(Tag="equivalence");

You can optionally specify other testing-related properties to customize the test run, generate test reports, and collect coverage for generated C/C++ code. For more information, see the Properties section of matlab.buildtool.tasks.TestTask. You must specify these properties when you add the task to the build file.

This table lists some common testing goals, the relevant TestTask properties and methods, and a example code snippet for each.

Goal	Related Properties and Methods	Example Task
Generate a test report	TestResults	This example task runs tests in the equivalenceTests folder and creates an HTML test report called myTestReport.html. plan("equivalenceTest") = TestTask("equivalenceTests", ... TestResults="myTestReport.html");
Customize test run settings	OutputDetail LoggingLevel Strict	This example task runs tests in the equivalenceTests folder with the maximum verbosity. plan("equivalenceTest") = TestTask("equivalenceTests", ... OutputDetail="verbose");
Run only the tests impacted by code or data changes	RunOnlyImpactedTests BaseRevision	This example task runs tests in the equivalenceTests folder and runs only the tests impacted by code or data changes. plan("equivalenceTest") = TestTask("equivalenceTests", ... RunOnlyImpactedTests=true);
Collect code coverage for MATLAB source code	SourceFiles property — Specify MATLAB source code files addCodeCoverage method — Specify the results file and format and coverage metric level	This example task runs tests in the equivalenceTests folder and collects decision coverage for the source code in the src folder and creates an HTML coverage report called myCovReport.html. plan("equivalenceTest") = TestTask("equivalenceTests", ... SourceFiles="src").addGeneratedCodeCoverage(... "myCovReport.html",MetricLevel="decision")
Collect coverage for generated C/C++ code	addGeneratedCodeCoverage method — Specify the results file and format and coverage metric level Note You can collect generated code coverage only for equivalence tests that generate static C/C++ libraries and that execute using software-in-the-loop (SIL) or processor-in-the-loop (PIL) verification. Collecting generated code coverage requires Embedded Coder. For more information, see Collect Coverage for Generated C/C++ Code in Equivalence Tests.	This example task runs tests in the equivalenceTests folder, creates an interactive HTML code coverage report called myCovReport.html, and collects decision coverage for the generated C/C++ code. plan("equivalenceTest") = TestTask(... "equivalenceTests").addGeneratedCodeCoverage(... "myCovReport.html",MetricLevel="decision");

Run Tests and View Results

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 to source and test code since the last run. For more information, see Test Impact Analysis Using MATLAB Build Tool.

To view the test and coverage results, open the test and coverage reports.