matlab-write-tests

# 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 ```matlab 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: ```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 ``` Error testing — identical `verifyError` logic, only inputs and error IDs vary: ```matlab 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](references/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 [references/fixtures-guidance.md](references/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 ``` ## App Designer Testing For testing apps with programmatic UI gestures (`press`, `choose`, `type`, `drag`), see [references/app-testing-guidance.md](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. ```matlab 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/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](references/fixtures-guidance.md) | | Floating-point tolerance selection, constraint objects, custom constraints | [references/constraints-guidance.md](references/constraints-guidance.md) | | Multiple parameters, dynamic parameters, combination strategies | [references/parameterized-tests-guidance.md](references/parameterized-tests-guidance.md) | | Code depends on external services, needs mock objects or dependency injection | [references/mocking-guidance.md](references/mocking-guidance.md) | | Testing App Designer apps with gestures, dialogs, async callbacks | [references/app-testing-guidance.md](references/app-testing-guidance.md) | | Baseline/regression tests against stored reference data, golden file tests | [references/baseline-tests-guidance.md](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. ----