Identify and Run Tests in MATLAB Projects

MATLAB^® projects provide tools to improve productivity, portability, collaboration, and maintainability of your MATLAB and Simulink^® code. Testing is an important aspect of software development and maintenance. To ensure the reproducibility, reliability, and accuracy of your code, MATLAB projects helps you identify and run tests easily.

Label Test Files

To easily identify and group tests and create test suites, label your test files. When you add test files to a MATLAB project, the project automatically associates the Test labels with Simulink Test files (.mldatx) and class-based MATLAB unit tests.

Label other test files manually using the Test classification label.

In the project Files view or in the Dependency Analyzer graph, select and right-click the files, and then click Add Label.
From the list, select the Test label and click OK.

Alternatively, add the Test label programmatically using the addLabel function.

For projects under source control, the labels you add persist across file revisions.

Project Files view that shows the list of files, a Status Column, a Git Column, and a Classification column. Red boxes on the files labeled Test in the Classification column.

Identify and Run All Tests in Project

In projects that have tests in different folders, you can use project filters to group and run all test files from the project interface. Use filtering to identify and group tests in large projects.

To show only the files with the Test label in the project view, follow these steps.

In the project Files view, click the filter icon.
In the Filter Builder dialog box, select the Test label.
Click Apply.

Steps to create a filter for test files. Project interface with an arrow that points to the filter icon in the top right. Filter Builder dialog that lists all labels including the Test label.

To run all the tests in the project, follow these steps.

In the project filtered Files view, select all the test files by using Ctrl+A.
Right-click your selection and click Run.

Project files view with the test filtered applied. All tests files are selected and a context menu appears over them. The mouse points to the Run option in the context menu.

Alternatively, run all the tests with the Test label in the current project by using the runtests function.

Create Test Suite from Project Test Files

If you run tests frequently by using project shortcuts or custom tasks, or if you need to run tests in continuous integration (CI) pipelines, create a test suite and run tests programmatically.

To create a test suite from all files with the Test label in the opened project and its referenced projects, use the testsuite function.

proj = currentProject;
suite = testsuite(proj.RootFolder,IncludingReferencedProjects=true);
results = run(suite)

results = 

  1×9 TestResult array with properties:

    Name
    Passed
    Failed
    Incomplete
    Duration
    Details

Totals:
   9 Passed, 0 Failed, 0 Incomplete.
   1.2533 seconds testing time.

Run Impacted Tests to Reduce Qualification Runtime

For projects with a large number of tests, running all tests is often time consuming.

To reduce qualification run time locally or in CI jobs, run only the tests that are impacted by the changes you make to your project.

List modified files in the current project.
```
proj = currentProject;
modifiedFiles = listModifiedFiles(proj);
```
The listModifiedFiles function lists only local modifications. If you need the list of modified files between revision identifiers for CI workflows, for example, when you want to run tests after you merge your Git™ branch into the main branch, use these commands instead.
```
proj = currentProject;
[status,modifiedFiles] = system("git diff --name-only main..newBranch :!resources");
modifiedFiles = split(modifiedFiles);
modifiedFiles = modifiedFiles(1:(end-1));
```
Find all files that are impacted by the modified files in your project.
```
impactedFiles = listImpactedFiles(proj,modifiedFiles);
```
Tip
- You can use the Dependency Analyzer to interactively identify and create a test suite from the tests you need to run to qualify your change. For more information, see Perform Impact Analysis with a Project.
- To reduce qualification time on local machines and CI servers, you can also share the dependency cache file. Using a prepopulated dependency cache file, you can perform an incremental impact analysis and cut down the runtime of a full impact analysis. For more information, see Reduce Test Runtime Using Dependency Cache and Impact Analysis.
Find all test files in your project.
```
testFiles = findFiles(proj,Label="Test");
```
Find and run test files that are impacted by the modified project files.
```
impactedTests = intersect(testFiles,impactedFiles);
runtests(impactedTests);
```

Alternatively, you can create a filtered test suite based on source code dependency by using the matlabtest.selectors.DependsOn class. For an example, see Select Tests That Depend on Modified Files in Project (MATLAB Test).