test_run searches 'test_*.m' and 'bug_*.m' files by default, executes them, and displays a report about success or failures.

Use the explicit all option to include 'bench_*.m' files, or use bench_run to execute benchmarks separately.

test_run is a compatibility wrapper over nelson.unittest.run.

The optional 'Launcher', 'webview' pair may be placed anywhere in the argument list. It routes ADV-CLI-tagged tests to nelson-adv-cli --webview so figures use the headless web (RenderWeb) backend; CLI and GUI tags are unchanged. The same choice can be set with the NELSON_UNITTEST_LAUNCHER environment variable.

Each test or bench is executed by a supervised child process. Process reuse requires the explicit <--REUSE PROCESS--> tag.

That enables the current command to continue, even if the test as created an unstable environment.

It also enables the tests to be independent from one another.

Use test_run(module_name, test_name) to run one test file from a module tests directory.

Some special tags can be inserted in the .m files to help the processing of the corresponding test.

These tags are expected to be found in Nelson comments:

<--NOT FIXED--> This test is skipped because it is a reported bug, but it is not yet fixed.

<--INTERACTIVE TEST--> This test is skipped because it is interactive test.

<--CLI MODE--> This test will be executed by nelson-cli executable (default).

<--ADV-CLI MODE--> This test will be executed by nelson-adv-cli executable.

<--GUI MODE--> This test will be executed by nelson-gui executable.

<--CHECK REF--> This test will compare .ref available in same directory with output generated. see test_makeref to generate .ref file.

<--ENGLISH IMPOSED--> This test will be executed with the en_US language.

<--WINDOWS ONLY--> This test will be executed only on Windows.

<--MACOS ONLY--> This test will be executed only on Macos.

<--UNIX ONLY--> This test will be executed only on Unix.

<--WITH DISPLAY--> This test will be executed only if a display output is available.

<--RELEASE ONLY--> This test will be executed only if nelson is an release (not in debug mode).

<--EXCEL REQUIRED--> This test will be executed only if excel is detected (on Windows).

<--MPI MODE--> This test will be executed in MPI mode.

<--AUDIO INPUT REQUIRED--> This test will be executed if an audio input is available.

<--AUDIO OUTPUT REQUIRED--> This test will be executed if an audio output is available.

<--AUDIO REQUIRED--> This test requires the audio module (its file functions such as audioread and audiowrite) but no physical audio device. The module is loaded even in a test that belongs to another module; the test is not skipped when no audio device is present.

<--C/C++ COMPILER REQUIRED--> This test will be executed if an C/C++ compiler is available.

<--INDEX 64 BIT REQUIRED--> This test will be executed if 64 bit index is available.

<--NO USER MODULES--> This test will be executed without load user modules.

<--IPC REQUIRED--> This test will be executed if IPC is available.

<--SEQUENTIAL TEST REQUIRED--> This test will be executed sequentially (1 worker).

<--NATIVE ARCHITECTURE TEST REQUIRED--> This test will be executed if application's build and architecture are same.

<--FILE WATCHER REQUIRED--> This test will be executed if file watcher is available.

<--PYTHON ENVIRONMENT REQUIRED--> This test will be executed if python environment is available and configured.

<--JULIA ENVIRONMENT REQUIRED--> This test will be executed if julia environment is available and configured.

<--REUSE PROCESS--> This test or bench authorizes the runner to reuse the same child process for several tagged files.

nelson.unittest.tuneReuse audits these tags with isolated and reused native campaigns. Adding tags requires the explicit AllowAdd option; source changes require Apply.

<--WEIGHT N--> Positive scheduling weight. Heavier files are started first by the dynamic worker queue.

nelson.unittest.tuneWeights can propose or explicitly update these tags from measured results.

<--TIMEOUT N--> Positive per-file execution timeout, in seconds, that overrides the default timer for this file only. It does not change the scheduling priority (that is <--WEIGHT N-->). Use it for a legitimately long test or bench that would otherwise be killed by the default timer. The global Timeout run option, when set, still takes precedence over the tag.

Test can also skipped dynamically using skip_testsuite function.

To avoid to block the application, tests have an execution timer of 2 minutes and the benchs have a timer of 6 minutes, unless a <--TIMEOUT N--> tag sets a per-file value.

test_run uses workers to execute tests. Untagged files are executed in separated child processes; files tagged with <--REUSE PROCESS--> can share a child process.

Results are displayed progressively in a stable order. Each result line contains a status icon and its elapsed time using the 🟢[ 9.800s] format.

Tests with <--SEQUENTIAL TEST REQUIRED--> are evaluated last.

Benchs use one worker when five threads or fewer are available, and two workers otherwise.

For the namespaced API, use nelson.unittest.discover, nelson.unittest.select, nelson.unittest.plan, nelson.unittest.run, nelson.unittest.tuneWeights, nelson.unittest.tuneReuse, and nelson.unittest.report.

The internal test file executor is private and is not documented as a user function.

bench_runasserttest_makerefskip_testsuitenelson.unittestnelson.unittest.tuneReusenelson.unittest.tuneWeights