---

name: matlab-write-tests description: > Generate and structure MATLAB unit tests using matlab.unittest and matlab.uitest features, including class-based tests, parameterized testing, fixtures, mocking, and app testing with gestures. Use when writing, generating, or adding tests, creating test classes, adding test methods, parameterizing tests, setting up fixtures, mocking dependencies, or testing App Designer apps. Do NOT use for running tests, collecting coverage, or CI/CD configuration. license: https://www.mathworks.com/content/dam/mathworks/license/pmrl/license.md metadata: author: MathWorks version: "1.0"

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

| 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 |

Qualification Levels

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

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.

| Load when... | Reference | |---|---| | Tests need setup/teardown, temp dirs, path management, shared state | references/fixtures-guidance.md | | Floating-point tolerance selection, constraint objects, custom constraints | references/constraints-guidance.md | | Multiple parameters, dynamic parameters, combination strategies | references/parameterized-tests-guidance.md | | Code depends on external services, needs mock objects or dependency injection | references/mocking-guidance.md | | Testing App Designer apps with gestures, dialogs, async callbacks | references/app-testing-guidance.md | | Baseline/regression tests against stored reference data, golden file tests | references/baseline-tests-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
• 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.

---