runtests — Discover and run MATLAB-style test files through the RunMat VM.
runtests discovers .m files that look like MATLAB test files, executes each test through the normal RunMat compiler/VM path, and returns RunMat matlab.unittest.TestResult-compatible result objects. Until RunMat has first-class MATLAB object arrays, zero or multiple results are represented as a 1-by-N cell row of result objects rather than a MATLAB object array.
Syntax
results = runtests
results = runtests(tests, Name, Value, ...)Inputs
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
tests | Any | No | current folder | Test file, folder, function name, string array, or cell array of targets. |
Name,Value | Any | Variadic | — | Common options such as IncludeSubfolders, BaseFolder, Name, ProcedureName, and UseParallel. |
Returns
| Name | Type | Description |
|---|---|---|
results | Any | Scalar TestResult object or cell row of TestResult objects. |
Errors
| Identifier | When | Message |
|---|---|---|
RunMat:runtests:RequiresVm | `runtests` is dispatched outside an active VM workspace frame. | runtests: requires VM workspace context |
RunMat:runtests:InvalidInput | A target or option value has an unsupported type or value. | runtests: invalid input |
RunMat:runtests:UnsupportedOption | A documented option requires infrastructure not implemented by this slice. | runtests: unsupported option |
RunMat:runtests:TargetNotFound | A requested test target cannot be resolved to a file or folder. | runtests: test target not found |
RunMat:runtests:FileReadFailed | A discovered test file cannot be read as source text. | runtests: failed to read test file |
RunMat:runtests:WorkspaceStateFailed | The VM cannot isolate or restore the caller workspace around a test case. | runtests: workspace isolation failed |
How runtests works
results = runtestsdiscovers tests in the current folder.results = runtests(target)accepts a test file, folder, function name, string array, or cell array of string targets. Bare names are resolved like MATLAB.mfiles on the active search path.BaseFolderconstrains relative explicit targets to one or more base folders. When no explicit target is supplied, the base folders act as discovery roots.- Folder discovery includes files whose stem starts with
testor ends withTest.IncludeSubfoldersrecursively includes subfolders. - Script-style tests run as isolated test workspaces. Variables assigned by a test file do not leak into the caller workspace.
- Function-style files with local zero-argument
test*or*Testfunctions are split into one test case per function by running the file source plus that function call. Fullfunctiontests(localfunctions),testCasearguments, setup/teardown fixtures, class-based tests, and shared fixture semantics require broadermatlab.unittestinfrastructure and are not implemented by this slice. - Each result object includes
Name,TestFile,Passed,Failed,Incomplete,Duration, andDetailsproperties. A single result is returned as a scalar object; zero or multiple results are returned as a cell row of result objects. - A failing test is captured as a failed result rather than as a
runtestscall failure. Discovery, invalid option, and unsupported infrastructure errors still surface as diagnostics. NameandProcedureNamefilters currently keep cases whose generated test name contains the supplied text. They do not yet implement the full MATLAB selector model.OutputDetailandLoggingLevelare accepted for compatibility but do not affect execution output yet.UseParallel=falseis accepted.UseParallel=true, coverage collection, and tag metadata filtering are explicitly rejected because they require separate parallel ormatlab.unittestinfrastructure.
Does RunMat run runtests on the GPU?
runtests is a host-side filesystem discovery and VM execution boundary. It does not create GPU kernels and does not participate in fusion. Individual test bodies may exercise GPU-capable operations normally.
Examples
Run a single script test file
results = runtests('testSmoke.m')Run tests below a folder
results = runtests('tests', 'IncludeSubfolders', true)Filter discovered cases by name
results = runtests('tests', 'IncludeSubfolders', true, 'Name', 'Solver')Using runtests with coding agents
Open a RunMat example with live inputs, then ask the agent to explain how runtests changes the result.
Run a small runtests example, explain the result, then change one input and compare the output.
FAQ
Does runtests support Parallel Computing Toolbox execution?⌄
No. UseParallel=true is rejected and tracked with the separate parallel/GPU effort. UseParallel=false is accepted.
Does runtests support coverage?⌄
No. Coverage collection is explicitly rejected because RunMat does not yet have the source instrumentation layer required for MATLAB-compatible coverage reports.
Does runtests return MATLAB object arrays?⌄
Not yet. A single result is a matlab.unittest.TestResult object, while zero or multiple results are returned as a cell row until RunMat has first-class MATLAB object-array support.
Does runtests support the full matlab.unittest framework?⌄
No. This slice covers script tests, simple zero-argument function tests, discovery, filtering, isolation, and result objects. Full functiontests(localfunctions), testCase fixtures, setup/teardown, class-based tests, tags, and coverage need additional shared testing/object infrastructure.
Do test variables leak into the caller workspace?⌄
No. RunMat snapshots the caller workspace, runs each test in a temporary workspace, and restores the caller workspace before returning result objects.
Can tests use GPU arrays?⌄
Yes, when the test body calls GPU-capable builtins. runtests itself is not a numeric operation and does not own GPU dispatch.
Related Diagnostics functions
Open-source implementation
Unlike proprietary runtimes, every RunMat function is open-source. Read exactly how runtests is executed, line by line, in Rust.
- View the source for runtests in Rust on GitHub
- Learn how the RunMat runtime works
- Found a bug? Open an issue with a minimal reproduction.
About RunMat
RunMat is an open-source runtime that executes MATLAB-syntax code blazing on any GPU. It is licensed under the Apache 2.0 license.
- RunMat automatically optimizes your math for GPU execution on Apple, Nvidia, and AMD hardware. No code changes needed. Simulations that took hours now take minutes.
- Start running code in seconds. RunMat runs in the browser, on the desktop, or from the CLI. No license server, no IT ticket.