Skip to main content

Executing Unit Tests Using the %UnitTest.Manager Methods

Launch tests using the methods included in the %UnitTest.ManagerOpens in a new tab class.

This is the general workflow to execute unit tests using the %UnitTest framework:

  1. Inform the system where to find your tests by setting the ^UnitTestRoot global:

    USER>set ^UnitTestRoot = "C:\UnitTests"
  2. Execute your tests, using the RunTests() or DebugRunTestCase() method of the %UnitTest.ManagerOpens in a new tab class:

    USER>do ##class(%UnitTest.Manager).RunTests("MyTests")
  3. View the results of your tests.


By default, RunTests() loads any test classes it finds within the ^UnitTestRoot directory, compiles them, executes any tests they contain, and deletes them from memory.

However, this may not be the most efficient paradigm when you are developing your code. That is, you may not want to reload and recompile your tests every time you make a small change to the method being tested. As a result, unit test classes are often stored externally. You can use the arguments of the RunTests() method to explicitly control whether to load tests and from where, whether to delete them, and other considerations. See Arguments of RunTest() and DebugRunTestCase() for details.

%UnitTest Test Execution Methods

The default behavior when running unit tests is for the tests to be loaded into InterSystems IRIS, compiled, executed, and then deleted. This prevents test code from cluttering your InterSystems IRIS namespace. To deviate from this default behavior, you can either use DebugRunTestCase() or you can add flags to the qualifiers argument of either of these methods. For example, you may want to develop your test cases locally, within your namespace, without having to reload them every time you make a change. In that case, you could pass the /nodelete flag as part of the qualifiers argument.

RunTest (“testSpec”, “qualifiers”, “userparam”)

Executes a test or set of tests within the directory specified in the global ^UnitTestRoot. Once tests are executed, deletes from InterSystems IRIS all loaded tests and test classes.

USER>Do ##class(%UnitTest.Manager).RunTest("MyTests")
DebugRunTestCase (“testSpec”, “qualifiers”, “userparam”)

Executes a test or set of tests without loading or deleting any test classes.

USER>Do ##class(%UnitTest.Manager).DebugRunTestCase("MyTests", "/display=none/debug", "/log")

Arguments of RunTest() and DebugRunTestCase()


You can execute tests from one or more test classes in a test suite. The testSpec argument determines which tests to run and where to find them. If no value is passed, the system finds all test classes within ^UnitTestRoot and its subdirectories, and executes all tests within those classes. The general format is testSuite[:testCase[:testMethod][;testcase[:testmethod]]...]. Note that testCase:testMethod pairs are separated by semicolons. For example:


You can use the same syntax to include more than one tests from the same class; to do so, specify the class for each method. For example:


Arguments are as follows:

  • testSuite

    A directory containing test class files. The directory must be a subdirectory of the ^UnitTestRoot directory. By default, the test manager executes all tests in all of the files contained in this directory and its subdirectories.

  • testCase

    Each included testCase specifies a single class containing test methods to execute. The syntax is PackageName.ClassName. When this argument is specified, the test manager executes only the tests in the named classes.

  • testMethod

    Each included testMethod singles out a method of the test class indicated by the associated testCase to execute.


Specifies various options for running the test. General syntax is /option1/option2/.../optionN. You can include the following qualifiers:

  • /load

    Load the test from a directory. Use /noload to load no tests and execute the tests already contained in InterSystems Iris. Default is /load.

  • /run

    Run the test. Use /norun to load but not run any tests. Default is /run.

  • /delete

    Delete the test case from InterSystems IRIS after executing. Use /nodelete to save the class. Default is /delete.

  • /recursive

    Look for tests in subdirectories of the named directory. Use /norecursive to not execute tests in subdirectories. Default is /recursive.

  • /debug

    With /debug, no tests are executed after the first test failure. When executing from the Terminal, the Terminal will enter debug mode after the first failure. To avoid this behavior, use /nodebug or simply do not use /debug. Default is /nodebug.

  • /autoload

    Use /autoload=dir to load tests from subdirectory dir of the ^UnitTestRoot directory. The default subdirectory is _autoload.

  • /display

    Use /display=all to display extended information when the method is run. Use /display=none to display limited information. Default is /display=all.


An arbitrary argument passed in by the caller. The manager recognizes one value, /log, by default. This tells the manager to minimize output to the terminal and write the detailed results to a file called UNITTEST.LOG in the <install-dir>/mgr directory.

FeedbackOpens in a new tab