Write Tests

Generate, structure, and organize MATLAB unit tests using the matlab.unittest and matlab.uitest frameworks.

When to Use

• User asks to write tests for a MATLAB function or class
• User wants to add test methods or parameterize existing tests
• User needs fixtures, mocking, or dependency injection in tests
• Test-driven development — writing tests before implementation
• Testing App Designer apps with programmatic gestures
• Baseline/regression tests against stored reference data (golden file, snapshot, characterization tests)

When NOT to Use

• Running tests, analyzing failures, or filtering test suites — use matlab-run-tests
• Collecting or analyzing code coverage — use matlab-run-tests
• CI/CD pipeline configuration — use matlab-run-tests
• Testing Simulink models — use Simulink test skills

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 — Inherit from the appropriate TestCase superclass. 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 after writing. For advanced test execution (coverage, filtering, CI), see the matlab-run-tests skill

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
3. Run via run_matlab_test_file MCP tool to confirm tests pass

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. Verify — Run via run_matlab_test_file MCP tool to confirm tests pass

Key Functions

Qualification Levels

Patterns

Basic Test Class

classdef computeAreaTest < matlab.unittest.TestCase

    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:

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

Error testing — identical verifyError logic, only inputs and error IDs vary:

properties (TestParameter)
    InvalidInput = struct( ...
        'zeroDivisor', struct('input', {{5, 0}}, 'errorId', 'fn:zeroDivisor'), ...
        'stringArg',   struct('input', {{'hello', 1}}, 'errorId', 'fn:nonNumeric'), ...
        'cellArg',     struct('input', {{{1}, 2}}, 'errorId', 'fn:nonNumeric'))
end

methods (Test)
    function testInvalidInputThrows(testCase, InvalidInput)
        testCase.verifyError(@() fn(InvalidInput.input{:}), InvalidInput.errorId);
    end
end

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

Setup, Teardown, and Fixtures

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

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 references/fixtures-guidance.md.

Determinism

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

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

Test Tags

Use TestTags for selective execution:

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

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

App Designer Testing

For testing apps with programmatic UI gestures (press, choose, type, drag), see references/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

Baseline Tests

For baseline, regression, gold-file, snapshot, or characterization tests, use matlabtest.parameters.matfileBaseline + verifyEqualsBaseline (requires MATLAB Test, R2024b+) instead of hardcoding expected values or manually loading reference data.

Workflow

1. Define parameterization — One TestParameter property per baseline value, using matlabtest.parameters.matfileBaseline with VariableName. Consolidate related baselines into a single MAT file.
2. Write test methods — Each method accepts the baseline parameter and calls verifyEqualsBaseline. Pass AbsTol or RelTol for floating-point tolerance.
3. Generate baseline data — Run the function under test, save results to the baseline MAT file.
4. Run tests — Execute the test file to confirm actual values match baselines.

properties (TestParameter)
    result = matlabtest.parameters.matfileBaseline( ...
        "baselines/output.mat", VariableName="result")
end

methods (Test)
    function testOutput(testCase, result)
        actual = myFunction(inputData);
        testCase.verifyEqualsBaseline(actual, result);
    end
end

Never use verifyEqual with hardcoded or manually-computed expected values for baseline/regression/gold-file tests. Always use matfileBaseline + verifyEqualsBaseline — even when tolerance is needed (pass AbsTol/RelTol to verifyEqualsBaseline).

Store baselines in baselines/ relative to the test file. For detailed patterns, multiple-variable consolidation, and baseline generation, see references/baseline-tests-guidance.md.

References

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

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
• Prefer: parameterized error testing over repeated methods when multiple inputs trigger the same verifyError pattern
• 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.