suite = nelson.unittest.discover(targets)
suite = nelson.unittest.select(suite, Name, Value)
plan = nelson.unittest.plan(suite, Name, Value)
results = nelson.unittest.run(targets, Name, Value)
results = nelson.unittest.run(plan, Name, Value)
proposal = nelson.unittest.tuneWeights(results, Name, Value)
proposal = nelson.unittest.tuneReuse(targets, Name, Value)
status = nelson.unittest.report(results, Name, Value)
nelson.unittest.assume(condition, reason)
| Parameter | Description |
|---|---|
| targets | a module name, file name, directory, or cell array of targets. |
| Name, Value | selection, planning, execution, and reporting options. |
| Parameter | Description |
|---|---|
| suite | a TestSuite structure containing discovered TestCase entries. |
| plan | a TestPlan structure containing selected tests, shard information, workers, and resource groups. |
| results | a TestRunResult structure containing summary, normalized cases, registry information, and raw compatibility data. |
The nelson.unittest namespace provides the modern test runner API.
The runner separates discovery, selection, planning, execution, and reporting while preserving compatibility wrappers such as test_run, test_makeref, and skip_testsuite.
test_run, test_makeref, and skip_testsuite are compatibility entry points implemented on top of this namespace.
Runner internals are private implementation details and are not part of the user API.
Each test and bench is executed in a child process supervised by the runner. There is no in-process execution mode for tests or benches.
The native process supervisor captures output, applies timeouts, and returns diagnostics such as command, process id, timeout, reason, and job id.
Normalized cases expose these native details in results.cases(k).diagnostics. The diagnostics structure contains kind, index, metadata, job_id, pid, timeout, reason, executable, and process_arguments.
Supported selection options include Name, Module, File, Kind, Tags, ExcludeTags, Match, and Exclude.
Kind accepts test, bug, bench, all_tests, and all.
Supported execution options include Workers, Timeout, StopOnFail, Retry, RetryOnlyOn, Shuffle, Seed, ShardIndex, and ShardCount.
Process reuse is explicit. Test and bench files without the <--REUSE PROCESS--> tag run in separated child processes. Tagged files can reuse the same child process when their mode and resources allow it.
The native supervisor schedules files through a dynamic weighted queue. Use <--WEIGHT N--> for an explicit positive scheduling weight.
nelson.unittest.tuneWeights can derive and explicitly apply these source-controlled weights from a TestRunResult. It does not use a duration cache and performs a dry run by default.
nelson.unittest.tuneReuse can audit existing reuse tags or explicitly propose additions. It uses isolated and reused native campaigns with deterministic orders, does not use a cache, and performs a dry run by default.
If a tagged reusable worker crashes or returns no result, the runner retries the affected file once with the isolated fallback path. Timeouts are reported directly.
Discovery always reads current file metadata and tags. Test results are progressively displayed in a stable order with an elapsed time on every line.
LogDir writes one JSON log file per normalized test case when requested.
Supported report formats are console, json, junit, tap, and html. JUnit output is XML, TAP output follows TAP13, and HTML output is a standalone single-file report.
HTML reports include slowest case and module summaries, sortable case tables, quick filters, reproduction commands, embedded JSON data, and a JSON sidecar next to the HTML file.
suite = nelson.unittest.discover('string', 'Kind', 'all_tests');
suite = nelson.unittest.select(suite, 'Match', 'strfind');
plan = nelson.unittest.plan(suite, 'Workers', 1);
results = nelson.unittest.run(plan, 'Format', 'json', 'OutputFile', [tempdir(), 'tests.json']);
proposal = nelson.unittest.tuneWeights(results);
reuseProposal = nelson.unittest.tuneReuse('string');
nelson.unittest.report(results, 'Format', 'tap', 'OutputFile', [tempdir(), 'tests.tap']);
nelson.unittest.report(results, 'Format', 'html', 'OutputFile', [tempdir(), 'tests.html']);