runtests — Discover and run MATLAB-style tests through RunMat's shared test engine.
runtests freezes the selected sources, uses Core's semantic test discovery, executes exact test procedures through the shared lifecycle engine, and returns homogeneous matlab.unittest.TestResult-compatible object arrays.
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 homogeneous TestResult object row. |
Errors
| Identifier | When | Message |
|---|---|---|
RunMat:Testing:RequiresExecutor | `runtests` is dispatched outside an active Core test executor. | runtests: requires an active Core test executor |
RunMat:runtests:InvalidInput | A target or option value has an unsupported type or value. | runtests: invalid input |
RunMat:runtests:UnsupportedOption | A documented option requires an execution mode not available through the in-program adapter. | 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 |
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,
functiontests(localfunctions), and class-based tests use semantic procedure identities rather than generated source calls. Function, method, class, and shared fixtures retain declared setup/teardown ordering. - Each test executes in an isolated Core test context. Variables assigned by a test do not leak into the caller workspace.
- Each result object includes
Name,TestFile,Passed,Failed,Incomplete,Duration,Details, and qualification data. Multiple results use a homogeneous TestResult object array. - 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.Coverage=trueenables the shared interpreter/JIT/WASM coverage collector.CodeCoveragePlugin.forFolderselects recursive or non-recursive coverage roots through the same policy.UseParallel=falseis accepted. Product and CLI runners provide parallel process or Web Worker execution; in-functionUseParallel=trueremains unsupported.
Does RunMat run runtests on the GPU?
runtests is a Core test-service 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?⌄
Yes. Use Coverage=true or matlab.unittest.plugins.CodeCoveragePlugin.forFolder; RunMat collects stable function and statement sites across interpreter, JIT, and WASM execution.
Does runtests return MATLAB object arrays?⌄
Yes. Results are projected as homogeneous matlab.unittest.TestResult-compatible object arrays.
Does runtests support the full matlab.unittest framework?⌄
RunMat supports script, function, and class suites; functiontests(localfunctions); common TestCase qualifications; fixtures; parameters; tags; plugins; and coverage. Unsupported MATLAB APIs fail explicitly rather than selecting a different execution path.
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.