Testing

Generate, structure, and run MATLAB unit tests using the matlab.unittest framework. Covers class-based tests, parameterized testing, fixtures, mocking, coverage analysis, CI/CD integration, and app testing via MCP.

When to Use

• User asks to write tests for a MATLAB function or class
• User wants to run an existing test suite
• User needs coverage analysis or CI/CD configuration
• Test-driven development — writing tests before implementation
• Testing App Designer apps with programmatic gestures (see reference/app-testing-guidance.md)

When NOT to Use

• Testing Simulink models — use Simulink test skills
• Performance benchmarking — use profiling workflows

Must-Follow Rules

• Present a test plan first — For non-trivial test suites, propose test methods and edge cases for user approval before writing code
• Always use class-based tests — Every test file must inherit from matlab.unittest.TestCase. Never use script-based tests
• No logic in test methods — No if, switch, for, or try/catch. Follow Arrange-Act-Assert. If a test needs conditionals, split into separate methods
• Test public interfaces, not implementation — Never test private methods directly
• Execute via MCP — Use run_matlab_test_file or evaluate_matlab_code to run tests

Workflow

Simple tests (clear behavior, limited scope)

1. Briefly state what you'll test (methods + key edge cases)
2. Write the test file after user confirms

Standard tests (large codebase, multiple files)

1. Gather requirements — Code to test, expected behaviors, error conditions, scope, dependencies
2. Present test plan — List test methods, edge cases, parameterization strategy for approval
3. Implement — Write tests following the patterns below
4. Run — Execute via run_matlab_test_file MCP tool
5. Check coverage — Identify untested paths, add tests

Key Functions

| Category | Functions | Purpose | |----------|-----------|---------| | Equality | verifyEqual, verifyNotEqual | Compare values (use AbsTol for floats) | | Boolean | verifyTrue, verifyFalse | Check logical conditions | | Size/type | verifySize, verifyClass, verifyEmpty | Structural checks | | Errors | verifyError | Confirm error is thrown with correct ID | | Warnings | verifyWarning, verifyWarningFree | Check warning behavior | | Infra | runtests, TestSuite, TestRunner | Run and organize tests | | Coverage | CodeCoveragePlugin, CoverageResult | Measure test coverage |

Qualification Levels

| Level | On failure | When to use | |-------|-----------|-------------| | verify | Continues test | Default — most assertions | | assert | Stops current test | Setup validation | | fatal | Stops entire suite | Environment preconditions | | assume | Skips test | Conditional execution (e.g., toolbox check) |

Patterns

Basic Test Class

matlab
classdef computeAreaTest < matlab.unittest.TestCase
    %computeAreaTest Tests for the computeArea function.

    methods (Test)
        function testSquare(testCase)
            result = computeArea(5, 5);
            testCase.verifyEqual(result, 25);
        end

        function testFloatingPoint(testCase)
            result = computeArea(1/3, 3);
            testCase.verifyEqual(result, 1, AbsTol=1e-12);
        end

        function testNegativeInputErrors(testCase)
            testCase.verifyError( ...
                @() computeArea(-1, 5), 'computeArea:negativeInput');
        end
    end
end

Parameterized Tests

Parameterize only when assertion logic is identical across all cases — only the data varies. Use struct for readable test names:

matlab
classdef unitConverterTest < matlab.unittest.TestCase

    properties (TestParameter)
        conversionCase = struct( ...
            'freezing', struct('input', 0, 'expected', 32), ...
            'boiling',  struct('input', 100, 'expected', 212), ...
            'bodyTemp', struct('input', 37, 'expected', 98.6));
    end

    methods (Test)
        function testCelsiusToFahrenheit(testCase, conversionCase)
            result = celsiusToFahrenheit(conversionCase.input);
            testCase.verifyEqual(result, conversionCase.expected, AbsTol=1e-10);
        end
    end
end

For advanced parameterization (combinations, dynamic parameters, ClassSetupParameter), see reference/parameterized-tests-guidance.md.

Setup, Teardown, and Fixtures

Prefer addTeardown over TestMethodTeardown blocks. Use PathFixture to add source folders:

matlab
classdef fileProcessorTest < matlab.unittest.TestCase

    methods (TestClassSetup)
        function addSourceToPath(testCase)
            srcFolder = fullfile(fileparts(fileparts(mfilename('fullpath'))), 'src');
            testCase.applyFixture(matlab.unittest.fixtures.PathFixture(srcFolder, ...
                IncludingSubfolders=true));
        end
    end

    methods (Test)
        function testProcessFile(testCase)
            tmpDir = string(tempname);
            mkdir(tmpDir);
            testCase.addTeardown(@() rmdir(tmpDir, 's'));

            testFile = fullfile(tmpDir, "data.csv");
            writematrix(rand(10, 3), testFile);

            result = processFile(testFile);
            testCase.verifySize(result, [10 3]);
        end
    end
end

For built-in fixtures, custom fixtures, and shared fixtures, see reference/fixtures-guidance.md.

Determinism

Seed the RNG and restore it in teardown for reproducible tests:

matlab
methods (TestMethodSetup)
    function resetRandomSeed(testCase)
        originalRng = rng;
        testCase.addTeardown(@() rng(originalRng));
        rng(42, "twister");
    end
end

Test Tags

Use TestTags for selective execution:

matlab
methods (Test, TestTags = {'Unit'})
    function testFastCalculation(testCase)
        % ...
    end
end

methods (Test, TestTags = {'Integration', 'Slow'})
    function testFullPipeline(testCase)
        % ...
    end
end

Run by tag: runtests('tests', Tag='Unit') or runtests('tests', ExcludeTag='Slow').

Running Tests

Via MCP

Use the run_matlab_test_file MCP tool for test files. For inline runs with filtering:

matlab
results = runtests('tests');                            % all tests in folder
results = runtests('tests', Tag='Unit');                % by tag
results = runtests('tests', Name='*Calculator*');       % by name pattern
results = runtests('tests', UseParallel=true);          % parallel execution
results = runtests('tests', Strict=true);               % warnings = failures

Analyzing Results

matlab
disp(results);

for r = results([results.Failed])
    fprintf('\nFAILED: %s\n', r.Name);
    disp(r.Details.DiagnosticRecord.Report);
end

Coverage Analysis

matlab
import matlab.unittest.TestRunner
import matlab.unittest.plugins.CodeCoveragePlugin
import matlab.unittest.plugins.codecoverage.CoverageResult
import matlab.unittest.plugins.codecoverage.CoverageReport

runner = TestRunner.withTextOutput;
covFormat = CoverageResult;
runner.addPlugin(CodeCoveragePlugin.forFolder('src', ...
    Producing=[covFormat, CoverageReport('coverage-report')]));
results = runner.run(testsuite('tests'));

covResults = covFormat.Result;
disp(covResults);

For coverage gap analysis, use the printCoverageGaps script in reference/test-execution-guidance.md.

CI/CD Integration

Use buildtool with a buildfile.m for CI pipelines. See reference/test-execution-guidance.md for buildfile.m templates and CI configs (GitHub Actions, Azure DevOps, GitLab CI).

App Designer Testing

For testing apps with programmatic UI gestures (press, choose, type, drag), see reference/app-testing-guidance.md.

Key points:

• Inherit from matlab.uitest.TestCase (not matlab.unittest.TestCase)
• Call drawnow after app creation, before first gesture
• Compare uilabel.Text with char ('text'), not string ("text")
• Compare .Enable with matlab.lang.OnOffSwitchState.on/.off

References

Load these on demand — most tests only need what's in this file.

| Load when... | Reference | |---|---| | Tests need setup/teardown, temp dirs, path management, shared state | reference/fixtures-guidance.md | | Floating-point tolerance selection, constraint objects, custom constraints | reference/constraints-guidance.md | | Multiple parameters, dynamic parameters, combination strategies | reference/parameterized-tests-guidance.md | | Code depends on external services, needs mock objects or dependency injection | reference/mocking-guidance.md | | Running tests in CI, buildtool config, coverage gap analysis | reference/test-execution-guidance.md | | Testing App Designer apps with gestures, dialogs, async callbacks | reference/app-testing-guidance.md |

Conventions

• Always use class-based tests inheriting from matlab.unittest.TestCase
• Name test files <functionName>Test.m and place in tests/ directory
• Use verify qualifications by default — they let all tests run even if one fails
• Use AbsTol for every floating-point comparison — never rely on exact equality
• No logic in test methods — follow Arrange-Act-Assert
• Use addTeardown for cleanup — it runs even if the test fails
• Use struct-based TestParameter for readable parameterized test names
• Keep test methods focused — test one behavior per method
• Tests must be independent and compatible with parallel execution
• Run tests via the run_matlab_test_file MCP tool for automatic result capture

Copyright 2026 The MathWorks, Inc.