How to Write and Run Tests Using the tests_manager with xUnit Export in Nelson

Use the test_run function with a third argument specifying the XML filename to execute Nelson test suites and export results in XUnit format for CI integration.

The nelson-lang/nelson repository includes a built-in tests_manager module that provides a complete unit-testing framework. You can write test suites using standard Nelson script files and export results to XUnit-compatible XML for continuous integration pipelines like Jenkins, GitLab CI, and Azure Pipelines.

Loading the tests_manager Module

Before running tests, ensure the module is loaded into your Nelson session. The loader at modules/tests_manager/loader.m registers the module's gateway and adds its function paths automatically during startup.

If you need to load it manually in an interactive session:

addgateway(modulepath('tests_manager','builtin'),'tests_manager');
addpath(modulepath('tests_manager','functions'),'-frozen');

The modules/tests_manager/etc/startup.m file performs these actions automatically when Nelson starts, provided the module is included in your build configuration via modules/modules.iss.

Writing Test Suites for tests_manager

A test suite is a regular Nelson script file containing one or more test functions. The tests_manager discovers and executes these functions based on specific naming conventions and assertion patterns.

Test Function Naming Conventions

Test functions must follow the test_ prefix convention. Each function represents an individual test case within the suite.

Create a file named my_tests.m:

function test_basic_math()
    % Verify simple arithmetic operations
    assert_equals(2 + 2, 4);
    assert_istrue(isnan(sqrt(-1)));
end

function test_string_operations()
    % Verify string concatenation
    result = strcat('Hello, ', 'World');
    assert_equals(result, 'Hello, World');
end

The module ships with a minimal example at modules/tests_manager/minimal_tests.m that demonstrates the required structure.

Using Assertions and Skipping Tests

The tests_manager provides assertion functions to validate test outcomes. Common assertions include assert_equals, assert_istrue, assert_isfalse, and assert_isapprox.

To conditionally skip a test suite, raise the special exception Nelson:tests_manager:testsuite_skipped:

function test_windows_only()
    % Skip this test on non-Windows platforms
    if ~ispc()
        error('Nelson:tests_manager:testsuite_skipped', ...
              'This test requires Windows');
    end
    assert_istrue(true);
end

Skipped tests appear as <skipped> elements in the XUnit XML output.

Running Tests and Generating XUnit Export

The test_run function in modules/tests_manager/functions/test_run.m serves as the primary entry point for test execution and XUnit export.

Basic test_run Usage

Execute all test suites found in the current path:

status = test_run([], [], []);

The function signature accepts three parameters:

• modules: Cell array of module names, a string path, or empty to search the entire path
• option: Flags such as -stoponfail to halt execution on first failure
• xunitfile: Filename for XUnit XML output (empty string disables export)

Exporting to XUnit XML Format

To generate an XUnit-compatible XML report for CI integration, provide a filename as the third argument:

% Run all tests and export to XUnit XML
status = test_run([], [], 'test_results.xml');

% Run specific module tests with XUnit export
status = test_run({'my_tests'}, [], 'my_report.xml');

The generated XML follows the standard XUnit schema:

<?xml version="1.0" encoding="UTF-8"?>
<testsuite name="my_tests" tests="2" failures="0" errors="0" skipped="0" time="0.012">
    <testcase classname="my_tests" name="test_basic_math" time="0.006"/>
    <testcase classname="my_tests" name="test_skip_example" time="0.006">
        <skipped message="Linux only"/>
    </testcase>
</testsuite>

Jenkins, GitLab CI, Azure Pipelines, and other CI systems can parse this format to display test results and track failures over time.

Advanced tests_manager Options

The tests_manager supports additional workflows through test_runfile and command-line flags.

Run a single test file directly using test_runfile from modules/tests_manager/functions/test_runfile.m:

status = test_runfile('my_tests.m', [], 'report.xml');

Stop execution immediately upon the first assertion failure using the -stoponfail flag:

status = test_run([], '-stoponfail', 'results.xml');

Benchmark timings automatically populate the time attribute in XUnit output when tests execute. The module also handles cleanup via modules/tests_manager/etc/finish.m, which removes paths and gateways when the session ends.

Summary

• The tests_manager module in nelson-lang/nelson provides a complete unit-testing framework with XUnit export capabilities.
• Write test suites as Nelson script files containing functions prefixed with test_ and use assertions like assert_equals and assert_istrue.
• Execute tests using test_run and export results to XUnit XML by providing a filename as the third argument.
• The generated XML integrates with Jenkins, GitLab CI, Azure Pipelines, and other CI tools that support XUnit format.

Frequently Asked Questions

How do I skip a test conditionally in tests_manager?

Raise the error Nelson:tests_manager:testsuite_skipped with a descriptive message. The test runner catches this exception and marks the test as skipped in the XUnit XML output rather than a failure.

Can I run a single test file instead of all discovered tests?

Yes. Use the test_runfile function instead of test_run. Pass the filename as the first argument, options as the second, and the XUnit filename as the third: test_runfile('my_tests.m', [], 'report.xml').

What CI systems support the XUnit format generated by tests_manager?

Any CI platform that parses standard XUnit XML can consume Nelson's output, including Jenkins with the xUnit plugin, GitLab CI with artifacts:reports:junit, Azure Pipelines with PublishTestResults, and GitHub Actions with the test-reporter action.

Where is the test_run function implemented in the Nelson source code?

The primary implementation resides in modules/tests_manager/functions/test_run.m. This file handles test discovery, execution, assertion handling, and XUnit XML generation. The companion function test_runfile is implemented in modules/tests_manager/functions/test_runfile.m.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}