# How to Write and Run Tests Using the tests_manager with xUnit Export in Nelson > Learn to write and run tests using Nelson's tests_manager with xUnit export. Execute test suites and export results for CI integration using the test_run function. - Repository: [The Nelson Programming Language/nelson](https://github.com/nelson-lang/nelson) - Tags: how-to-guide - Published: 2026-03-08 --- **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: ```matlab 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`: ```matlab 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`: ```matlab 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 `` 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: ```matlab 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: ```matlab % 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 ``` 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`: ```matlab status = test_runfile('my_tests.m', [], 'report.xml'); ``` Stop execution immediately upon the first assertion failure using the `-stoponfail` flag: ```matlab 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`.