Skip to main content

%UnitTest.Manager

class %UnitTest.Manager extends %Library.RegisteredObject

The InterSystems IRIS UnitTest framework is composed of several classes that have the package name (prefix) %UnitTest. Of these classes, the %UnitTest.Manager class is the superclass of the UnitTest infrastructure, and is primarily responsible for the following tasks: Developers familiar with the xUnit framework should notice a passing resemblance, as these two frameworks share a common testing philosophy.

Prior to invoking any of the methods within this class, you must first perform the following setup instructions: Once the setup has been completed, launching a UnitTest is as simple as invoking one the following methods: The RunTest()(testspec, spec, userparam) method, more specifically, performs the following tasks:
  1. Evaluate all of the qualifiers specified by the qspec parameter
    • If this parameter contains the qualifiers /cleanup/run/delete, without the /debug qualifier, then all globals, classes, and routines within the current namespace will be recorded before each invocation of the RunOneTestSuite() method. After each invocation of this method, the namespace will be purged of all globals, classes and routines, other than those previously recorded
  2. Evaluate all of the user parameters specified by the userparam parameter
    • If this parameter contains the value /log, then all processing information will be logged to the UNITTEST.LOG file which is located in the mgr directory of the IRIS Instance (e.g. $ZU(12))
  3. Invoke the following method before any UnitTests are run: OnBeforeAllTests()
  4. Collect all UnitTest testsuites (directories) specified by the testspec parameter, and recursively all associated sub-testsuites (sub-directories) (assuming that the /recursive qualifier is on (the default)), whilst skipping all sub-directories whose names begins with an underscore
    See the notes within the RunTest() method for additional details
  5. For each UnitTest's testsuites collected in the previous step, invoke the RunOneTestSuite() method which performs the following tasks:
    1. Collect all UnitTest classes specified by the dir parameter, along with each class's corresponding test methods when the testspec parameter is defined with the following nomenclature:
      [-]testsuite [ :[testcase] [ :testmethod ] [ ;[testcase] [ :testmethod ] ]* ]
    2. Record the start of the testing process based on the specified suite parameter
      See item (3) in the Important Notes section below for addition details
    3. Load and compile all relevant files in the directory specified by the dir parameter
      • If the /loadxml qualifier is true (the default), then all XML files (*.xml, *.XML) will be loaded
      • If the /loadudl qualifier is true (the default), then all UDL files (*.cls, *.mac, *.int, *.inc, *.CLS, *.MAC, *.INT, *.INC) will be loaded
      • To see the current qualifier values, invoke the following method: do $SYSTEM.OBJ.ShowQualifiers()
    4. For each UnitTest class collected in step (5A) above, invoke the RunOneTestCase() method which performs the following tasks:
      1. Record the start of the testing process based on the specified suite and class parameters
        See item (3) in the Important Notes section below for addition details
      2. Instantiate the UnitTest class specified by the class parameter
      3. Record the current Process Values
      4. Invoke the following method: OnBeforeTestCase()
      5. Invoke the following method: class.OnBeforeAllTests()
      6. Collect all UnitTest methods from the specified class parameter, which have the following nomenclature: Test* (e.g. Test1 or TestSQL)
      7. For each method collected in the previous step, perform the following steps:
        1. Record the start of the testing process based on the suite, class and method parameters
          See item (3) in the Important Notes section below for addition details
        2. Invoke the following method: OnBeforeOneTest()
        3. Invoke the following method: class.OnBeforeOneTest()
        4. Invoke the specified UnitTest method (e.g. Test1 or TestSQL)
        5. Invoke the following method: class.OnAfterOneTest()
        6. Invoke the following method: OnAfterOneTest()
        7. Record the end of the testing process based on the suite, class and method parameters
          See item (3) in the Important Notes section below for addition details
      8. Repeat the previous steps (a) through (g) for all of the methods collected in step (VI) above
      9. Invoke the following method: class.OnAfterAllTests()
      10. Invoke the following method: OnAfterAllTests()
      11. Cleanup and Restore any modified Process Values
    5. Repeat the previous steps (I) through (XI) for all of the classes collected in (5A) above
    6. Delete all the classes loaded in step (5C) above
    7. Record the end of the testing process based on the suite parameter
      See item (3) in the Important Notes section below for addition details
  6. Repeat the previous steps (A) through (G) for all testsuites (directories) and all sub-testsuites (sub-directories) collected in step (4) above
IMPORTANT NOTES
  1. Throughout this class, the terms qspec and qualifier will be used interchangeably, as many methods in this class use the qspec parameter, which is a concatenated list of supported system flags and qualifiers documented on the following page:
    System Flags and QualifiersOpens in a new tab

    The qspec parameter can specify qualifiers in the following format: /[no]<qualifier>[=<value>][/[no]<qualifier>[=<value>]]*

  2. The loading, running and deletion tasks can each be skipped by specifying the following qualifiers respectively:
    /noload, /norun and /nodelete

  3. UnitTest results are saved to the following globals. The first global is used by the UnitTest Results CSP Pages, while the second global is used for status processing and debugging:
    • ^|ns|UnitTest.Result(id,suite[,class[,method]])=$LIST(...) of Runtime Information
      ns - The Namespace in which the UnitTest is being invoked (e.g. "USER")
      id - The value of the Name/Value pair Index within the result URL
    • ^IRIS.Temp.UnitState=$LB(suit[,class[,method]])


Property Inventory

Method Inventory

Properties

property CurrentDir;
The directory that contains the current UnitTest.
Property methods: CurrentDirDisplayToLogical(), CurrentDirGet(), CurrentDirIsValid(), CurrentDirLogicalToDisplay(), CurrentDirLogicalToOdbc(), CurrentDirNormalize(), CurrentDirSet()
property Debug;
A Boolean flag that is set to true (1) if the /debug qualifier is enabled (1).
Property methods: DebugDisplayToLogical(), DebugGet(), DebugIsValid(), DebugLogicalToDisplay(), DebugLogicalToOdbc(), DebugNormalize(), DebugSet()
property Display;
A Boolean flag that is set to true (1) if the /display=all qualifier is enabled (1).
Property methods: DisplayDisplayToLogical(), DisplayGet(), DisplayIsValid(), DisplayLogicalToDisplay(), DisplayLogicalToOdbc(), DisplayNormalize(), DisplaySet()
property LoadUDL;
A Boolean flag that is set to true (1) if the /loadudl qualifier is enabled (1).
UDL files: *.cls, *.mac, *.int, *.inc, *.CLS, *.MAC, *.INT, *.INC
Property methods: LoadUDLDisplayToLogical(), LoadUDLGet(), LoadUDLIsValid(), LoadUDLLogicalToDisplay(), LoadUDLLogicalToOdbc(), LoadUDLNormalize(), LoadUDLSet()
property LoadXML;
A Boolean flag that is set to true (1) if the /loadxml qualifier is enabled (1).
Property methods: LoadXMLDisplayToLogical(), LoadXMLGet(), LoadXMLIsValid(), LoadXMLLogicalToDisplay(), LoadXMLLogicalToOdbc(), LoadXMLNormalize(), LoadXMLSet()
deprecated property LogIndex;
DEPRECATED. Use the ResultId property.
Property methods: LogIndexDisplayToLogical(), LogIndexGet(), LogIndexIsValid(), LogIndexLogicalToDisplay(), LogIndexLogicalToOdbc(), LogIndexNormalize(), LogIndexSet()
property ReportVariableLeaks;
A Boolean flag that is set to true (1) if unexpected public variables should trigger an error.
Property methods: ReportVariableLeaksDisplayToLogical(), ReportVariableLeaksGet(), ReportVariableLeaksIsValid(), ReportVariableLeaksLogicalToDisplay(), ReportVariableLeaksLogicalToOdbc(), ReportVariableLeaksNormalize(), ReportVariableLeaksSet()
property ResultId as %Integer;
Property to hold the Result ID (instance slot) in the ^UnitTest.Manager global.
Property methods: ResultIdDisplayToLogical(), ResultIdGet(), ResultIdIsValid(), ResultIdLogicalToDisplay(), ResultIdNormalize(), ResultIdSet()
property UserFields as array of %String;
Set to the RunTest() method's third parameter userparam, if specified as an array. This array is populated from the first level subscripts of the userparam parameter.
Allow users to store additional information, like platform, product version, etc. for each UnitTest. This information can be later cross-referenced in the result.
Property methods: UserFieldsBuildValueArray(), UserFieldsCollectionToDisplay(), UserFieldsCollectionToOdbc(), UserFieldsDisplayToCollection(), UserFieldsDisplayToLogical(), UserFieldsGet(), UserFieldsGetObject(), UserFieldsGetObjectId(), UserFieldsGetSwizzled(), UserFieldsIsValid(), UserFieldsLogicalToDisplay(), UserFieldsLogicalToOdbc(), UserFieldsNormalize(), UserFieldsOdbcToCollection(), UserFieldsSet(), UserFieldsSetObject(), UserFieldsSetObjectId()
property UserParam as %String;
Set to the RunTest() method's third parameter userparam, if specified as a string.
Property methods: UserParamDisplayToLogical(), UserParamGet(), UserParamIsValid(), UserParamLogicalToDisplay(), UserParamLogicalToOdbc(), UserParamNormalize(), UserParamSet()

Methods

method Cleanup(ByRef procVals As %String, kill=0) as %Status

This original internal method is retained for backward compatibility...

method CleanupAllProcVals(ByRef procVals As %String, kill=0) as %Status

This internal method will cleanup all General & Specific Process Values that have changed during the invocation of methods within this class, report any differences, and restore those Process Values that have changed to their original value...

method CleanupGeneralProcVals(checkLocks=1) as %Status

This internal method will cleanup all General Process Values that have changed during the invocation of methods within this class, report any differences, and restore those Process Values that have changed to their original value...

method CleanupSpecificProcVals(ByRef procVals As %String, kill=0) as %Status

This internal method will cleanup all Specific Process Values that have changed after the invocation of each UnitTest, which is handled within the RunOneTestCase() method, via the following steps:

  • Before any UnitTest invocations, Record/Collect the Process Values at the beginning of the RunOneTestCase() method by calling the RecordProcVals() method
  • Compare all Process Values recorded/collected within the array passed to the RecordProcVals() method with their current Process Values
  • For each recorded value that differs from its current value, perform the following steps:
    • Create an $$$ERROR($$$GeneralError,) of the Process Value differences
    • Restore the Process Value to its originally recorded value

classmethod ConvertLogData(pLogIndex, pResultNamespace="", pMachine="", pConfiguration="", pVersion="", pUserParam="", pKillLog=0) as %Status

This method converts old format data in the ^UnitTestLog global to the new format stored in the ^UnitTest.Result global.

Parameters:

pLogIndex
This is the test instance index in the ^UnitTestLog global.
pResultNamespace
This is the namespace for the ^UnitTest.Result global.
pMachine, pConfiguration, pVersion, pUserParam
The new information collected in the ^UnitTest.Result global, but no longer in the ^UnitTestLog global.
This information can be provided manually when doing the conversion.
The pUserParam parameter is used the same way as the userparam parameter of the RunTest() method.
The top node of the pUserParam parameter becomes the value of the UserParam property, and the first level subscripts, along with their values, are used to populate the UserFields array property.

classmethod ConvertStatus(pIndex, pNamespace) as %Status

This method updates the status at each level recursively based on the status of the children.
If the pIndex parameter is omitted or passed the empty-string (""), then all of the nodes within the ^|pNamespace|UnitTest.Result(...) global will be converted.

classmethod DebugLoadTestSuite(testsuite As %String = "", qspec As %String = "") as %Status

This method is used to load, but not run, all corresponding UnitTest classes specified by the testsuite parameter.
Once the UnitTest classes are loaded by this method, the DebugRunTestCase() method can be invoked to run all of the corresponding UnitTests over and over again, without having to reload the UnitTest classes.

Developers should use the DebugLoadTestSuite() method in conjunction with the DebugRunTestCase() method to load all UnitTest classes once, and then run all corresponding UnitTests as often as necessary during the development, debugging and testing process.

classmethod DebugRunTestCase(testsuite As %String = "", testcase As %String = "", qspec As %String = "", testmethod As %String = "", ByRef userparam) as %Status

This method is used to run all UnitTests that were previously loaded by the DebugLoadTestSuite() method.
Both the testsuite and testcase parameters are required.
The testcase parameter is in the form package.class and the testmethod parameter is a method within the UnitTest class.

Developers should refer to the DebugLoadTestSuite() method to see how these two methods are used in conjunction during the development, debugging and testing process.

classmethod GetSubDirectories(root, topdir As %String, level As %Integer, suite As %String, ByRef subdirs As %String, qspec As %String, ByRef testskip As %String) as %Status
classmethod GetTestState(level) as %String
method GetTestStatus(suite, case, method, action) as %Integer

This method returns result for a given suite, case, method, and action.

method IsSuccess(suite, case, method, action) as %Boolean

This method is obsolete; Use the GetTestStatus() method instead!

method LogAssert(success, action, description, extra, location)
method LogMessage(message, location)
method LogStateBegin(testsuite, testcase, testmethod)
method LogStateEnd(duration) as %Integer

This method records the end of a UnitTest and returns the status of its invocation.

method LogStateStatus(status, action)
classmethod OnAfterAllTests(manager As %UnitTest.Manager, dir As %String, ByRef qstruct, ByRef userparam) as %Status

This method is called after all UnitTests are run. If an error status is returned, then it is logged.

method OnAfterOneTest(suite As %String, class As %String, method As %String) as %Status

This method is called after a test (method starting with "Test" in a class extending %UnitTest.TestCase) is run. If an error status is returned, it is logged.

method OnAfterSaveResult(ByRef userparam)

This method is called after the invocation of the SaveResult() method to perform any result aggregation tasks required by subtasks.

method OnAfterTestCase(suite As %String, class As %String, ByRef testcase As %UnitTest.TestCase) as %Status

This method is called after a test case (class extending %UnitTest.TestCase) is run. If an error status is returned, it is logged.

method OnAfterTestSuite(dir As %String, suite As %String, testspec As %String, ByRef qstruct) as %Status

This method is called after a test suite is run. If an error status is returned, it is logged.

classmethod OnBeforeAllTests(manager As %UnitTest.Manager, dir As %String, ByRef qstruct, ByRef userparam) as %Status

This method is called before any UnitTests are run. If an error status is returned, then no UnitTests are run.

method OnBeforeAutoLoad(dir As %String, suite As %String, testspec As %String, ByRef qstruct) as %Status

This method is called before autoload, which occurs before each test suite is run. If an error status is returned, then it is logged and the test suite is not run.

method OnBeforeOneTest(suite As %String, class As %String, method As %String) as %Status

This method is called before a test (method starting with "Test" in a class extending %UnitTest.TestCase) is run. If an error status is returned, it is logged and the test is not run.

method OnBeforeTestCase(suite As %String, class As %String, ByRef testcase As %UnitTest.TestCase) as %Status

This method is called before a test case (class extending %UnitTest.TestCase) is run. If an error status is returned, it is logged and the test case is not run.

method OnBeforeTestSuite(dir As %String, suite As %String, testspec As %String, ByRef qstruct) as %Status

This method is called before a test suite is run. If an error status is returned, it is logged and the test suite is not run. This is called after autoload.

method PrintErrorLine(text, extra)
method PrintLine(text, level=0)
method PrintURL()
classmethod PurgeLog() as %Status
classmethod PurgeResult() as %Status
method Record(ByRef procVals As %String) as %Status

This original internal method is retained for backward compatibility...

method RecordProcVals(ByRef procVals As %String) as %Status

This method records all of the current Process Values within the Pass By Reference (PBR) array parameter procVals...

classmethod Root() as %String

This method returns the root directory of the UnitTest hierarchy, which is typically the value stored in the following global: ^UnitTestRoot

method RunOneTestCase(suite As %String, class As %String, ByRef test As %String = "")
method RunOneTestSuite(dir As %String, suite As %String, testspec As %String, qstruct)
classmethod RunTest(ByRef testspec As %String, qspec As %String, ByRef userparam) as %Status

This method invokes all of the UnitTest methods contained within the classes specified by the testspec parameter. During the invocation of these methods, a running log is maintained within the following global so that it can be inspected by other processes: ^UnitTest.Result

Parameters:

testspec
<testspec list> used to invoke UnitTests; passed in as one of the following formats:
String: testspec=<testspec list>
Array: testspec(<testspec list>*)="" OR testspec(#*)=<testspec list>
Global: testspec="^global" (e.g. ^global(<testspec list>*)="" OR ^global(#*)=<testspec list>)
Syntax

<testspec data> ::= [-]testsuite [ :[testcase] [ :testmethod ] [ ;[testcase] [ :testmethod ] ]* ]
<testspec list> ::= "<testspec data> [ ,<testspec data> ]*"
<testsuite root> ::= // The first instance of the testsuite value within the <testspec list>
testsuite
A directory (and possibly all of its sub-directories) that's a child of the directory referenced in the ^UnitTestRoot global. This directory contains all of the UnitTest classes from which all UnitTests will be invoked.
NOTE-1
The ^UnitTestRoot global must specify a valid directory whose existence is checked during the invocation of the RunTest(...) method.
NOTE-2
By default, the RunTest(...) method will recursively process all sub-directories unless the /norecursive qualifier is passed to the qspec parameter.
NOTE-3
If a negative-sign (-) precedes the testsuite, then this directory (and all of its sub-directories) will be excluded from UnitTest invocations.
A <testsuite root> (without a negative-sign) must first be included before a -testsuite can be excluded, as in the following example:
<testspec list> = "SQL,-SQL\Embedded"
testcase (Optional)
A class, specified in the following format, which extends one of the testing classes (e.g. %UnitTest.TestCase) and contains testing methods: package.class (e.g. Sample.Person)
testmethod (Optional)
A testing method name in the following format: Test* (e.g. Test1 or TestFirst)
NOTE
If no value is specified for the testspec parameter, then the directory referenced in the ^UnitTestRoot global will be used for the testsuite value.
Any subdirectory whose name begins with an underscore ( _ ) will be skipped.
qspec
This parameter has a name/term that is used interchangeably with the term qualifier, and a value that is a concatenated list of supported system flags and qualifiers documented on the following page: System Flags and QualifiersOpens in a new tab

This parameter allows the specification of qualifiers in the following format: /[no]<qualifier>[=<value>][/[no]<qualifier>[=<value>]]*

Example: /noload/norecursive

The first four qualifiers below (debug, load, run, and recursive) are negatable Booleans, which can be enabled by explicitly specifying the qualifier name (e.g. /debug) or disabled by either adding the prefix no, or by adding the value zero =0, as in the following respective examples: /nodebug OR /debug=0

/debug: Run in debug mode, which causes an execution BREAK if a UnitTest fails. Default is /nodebug.

/load: Load the corresponding UnitTest classes for the specified testspec parameter. Default is /load. If both the /load and /run qualifiers are enabled (true), then all loaded classes, routines, and CSP files will be deleted after all UnitTests have finished running. To prevent the post-deletion task, invoke the DebugLoadTestSuite() method to first load all appropriate UnitTest classes and then invoke the DebugRunTestCase method to actually run the corresponding UnitTests.

/run: Run all UnitTests specified by the testsuite parameter. Use the /norun qualifier if you only want to load, but not run, all corresponding UnitTest classes specified by the testsuite parameter. Default is /run.

/recursive: Recurse the specified directory when loading UnitTest classes. Default is /recursive.

/display=all: Display extended information when loading and running UnitTest classes and tests. /display=none displays limited information. Default is /display=all.

/autoload: Automatically load sub-directories with the given name when loading test classes. Default is /autoload=_autoload. When this qualifier is specified, classes are loaded from the given sub-directory of the current directory and its ancestors. This makes it possible to use a class in multiple test suites without copying it to each of their descendant directories.

/nodelete: Do not delete loaded classes when the UnitTest has finished running.

userparam
An arbitrary argument passed in by the caller, which allows for the storage of additional information, like platform, product version, etc.
If this parameter is passed a string, then it becomes the value for the UserParam property.
If this parameter is passed an array, then the first level subscripts and their values are used to populate the UserFields array property.
This information can be later cross-referenced in the result.

Examples:

   // --- RunTest(...) Examples ---
   
   // --- Setup ---
   set ^UnitTestRoot="C:\UnitTests\"
   
   // --- UnitTest Directories ---
   // C:\UnitTests\SQL\Embedded
   // C:\UnitTests\SQL\Dynamic
   // C:\UnitTests\SQL\ODBC
   // C:\UnitTests\SQL\JDBC
   
   // --- Passing 'testspec' as a String ---
   set tSC=##class(%UnitTest.Manager).RunTest("SQL\Embedded,SQL\Dynamic")
   
   // --- Passing 'testspec' as an Array ---
   set utSpecs("SQL\Embedded")=""   // Alternatively:  set utSpecs(1)="SQL\Embedded"
   set utSpecs("SQL\Dynamic")=""    //                 set utSpecs(2)="SQL\Dynamic"
   set tSC=##class(%UnitTest.Manager).RunTest(.utSpecs)
   
   // --- Passing 'testspec' as a Global ---
   set ^utSpecs("SQL\Embedded")=""  // Alternatively:  set ^utSpecs(1)="SQL\Embedded"
   set ^utSpecs("SQL\Dynamic")=""   //                 set ^utSpecs(2)="SQL\Dynamic"
   set tSC=##class(%UnitTest.Manager).RunTest("^utSpecs")
   
   // --- Passing 'testspec' as an Array (Complex Example) ---
   set utSpecs("SQL\Embedded:SQL.Embedded:Test1;:Test2")=""
   set utSpecs("SQL\Dynamic::Test1;:Test2")=""
   set tSC=##class(%UnitTest.Manager).RunTest(.utSpecs,"/recursive=0")
   
   // --- Passing 'testspec' as a String (With Exclusions) ---
   set tSC=##class(%UnitTest.Manager).RunTest("SQL,-SQL\ODBC,-SQL\JDBC")
  
NOTE
If any of your code needs to run in the %SYS namespace, change to the %SYS namespace to run that specific code (e.g. ZN "%SYS"), then return to the original namespace for continued code processing.
classmethod RunTestSuites(%testspec As %String, %qspec, ByRef %userparam) as %Status

This is a private and internal method that is invoked via the RunTest() method, but requires a value for each of its three parameters, be it the empty-string ("") or otherwise.

classmethod RunTestsFromFileList(globalName As %String = "", fileName As %String = "", qspec As %String, ByRef userparam, sections As %String = "") as %Status

This method runs the UnitTests that are listed within the specified fileName parameter. The tests within this file have the following format:

[
  • : #
  • |
  • : //
  • ] | [<section>#] | [
  • : -
  • ]
  • : utPath
  • : #
  • |
  • : //
  • Optional - Specifies a comment line
  • : [<section>#]
  • Optional - Specifies the beginning of a section of tests. For example [1] or [15]
  • : -
  • Optional - Specifies that the
  • : utPath
  • will be excluded from running
  • : utPath
  • The directory path of the UnitTest to run, or a path prefix (e.g. SQL\SQLStats) to run all UnitTests within this directory and all sub-directories

    Example:

      utFile_with_exclusions.txt
        // This file contains the following two lists:
        //   1) A list of UnitTests to exclude from running
        //   2) A list of UnitTests to run
    
        // List all of the excluded UnitTest Paths (utPath) first:
        //   NOTE: The negative-sign (-utPath) is the exclusion indicator!
        -SQL\dynamicSQL\DocBookTests
        -SQL\dynamicSQL\privilege
        -Classes\Atelier
        -Classes\Debugger
    
        // List all of the UnitTest Paths (utPath) to run last:
        SQL\dynamicSQL
        Classes
      
      Invocation
        USER>set tSC=##class(%UnitTest.Manager).RunTestsFromFileList(,"C:\ut\SQLStats_with_exceptions.txt")
    
    globalName
    A optional global name, when specified, will be populated with each
  • : utPath
  • from the given fileName, which is then passed as the first parameter to the RunTest()(testspec,...) method for execution. If specified, the value passed to the globalName parameters must have the following format:
         INPUT:   "^utGlobal"           // Where ^utGlobal is a valid IRIS Global Name
         OUTPUT:  ^utGlobal(utPath)=""  // e.g.  ^utGlobal("SQL\dynamicSQL")=""
                                                 ^utGlobal("Classes")=""
      
    fileName
    A file path and name, which contains lines of tests in the following format, as specified above: [
  • : #
  • |
  • : //
  • ][
  • : -
  • ]
  • : utPath


  • qspec
    This parameter has a name/term that is used interchangeably with the term qualifier, and a value that is a concatenated list of supported system flags and qualifiers documented on the following page: System Flags and QualifiersOpens in a new tab

    This parameter allows the specification of qualifiers in the following format: /[no]<qualifier>[=<value>][/[no]<qualifier>[=<value>]]*

    Example: /noload/norecursive

    The first four qualifiers below (debug, load, run, and recursive) are negatable Booleans, which can be enabled by explicitly specifying the qualifier name (e.g. /debug) or disabled by either adding the prefix no, or by adding the value zero =0, as in the following respective examples: /nodebug OR /debug=0

    /debug: Run in debug mode, which causes an execution BREAK if a UnitTest fails. Default is /nodebug.

    /load: Load the corresponding UnitTest classes for the specified testspec parameter. Default is /load. If both the /load and /run qualifiers are enabled (true), then all loaded classes, routines, and CSP files will be deleted after all UnitTests have finished running. To prevent the post-deletion task, invoke the DebugLoadTestSuite() method to first load all appropriate UnitTest classes and then invoke the DebugRunTestCase method to actually run the corresponding UnitTests.

    /run: Run all UnitTests specified by the testsuite parameter. Use the /norun qualifier if you only want to load, but not run, all corresponding UnitTest classes specified by the testsuite parameter. Default is /run.

    /recursive: Recurse the specified directory when loading UnitTest classes. Default is /recursive.

    /display=all: Display extended information when loading and running UnitTest classes and tests. /display=none displays limited information. Default is /display=all.

    /autoload: Automatically load sub-directories with the given name when loading test classes. Default is /autoload=_autoload. When this qualifier is specified, classes are loaded from the given sub-directory of the current directory and its ancestors. This makes it possible to use a class in multiple test suites without copying it to each of their descendant directories.

    /nodelete: Do not delete loaded classes when the UnitTest has finished running.

    userparam
    An arbitrary argument passed in by the caller, which allows for the storage of additional information, like platform, product version, etc.
    If this parameter is passed a string, then it becomes the value for the UserParam property.
    If this parameter is passed an array, then the first level subscripts and their values are used to populate the UserFields array property.
    This information can be later cross-referenced in the result.
    sections
    An options, comma-delimited list of file sections this call should test. This will not run all the tests listed in the file, but only the tests within the specified [section#] within the file. For example, suppose you file has sections [1], [2], [3], [4], [5], and [6]. If sections="2,4,6" only tests within sections [2], [4], and [6] will be run.


    method SaveResult(duration, ByRef userparam)
    classmethod WipeNamespace()

    This method will wipe all data from this Namespace in addition to all PPG information. This method is useful in cleaning a Namespace before running all UnitTests.

    This should never be invoked on a production system!

    classmethod addToExcludeGlobal(excludeUTPath As %String = "") as %Status

    This method adds the given excludeUTPath to the exclusion global:

       ^||UnitTest.exclude(0,...)                        // Master Map
       ^||UnitTest.exclude("x",$$$UPPER(excludeUTPath))  // Index Map
    

    Invocation:
    This method can be invoked in the following ways:

    • ObjectScript: ##class(%UnitTest.Manager).addToExcludeGlobal(...)
    • SQL: N/A

    Parameters:

    excludeUTPath
    The directory path of the UnitTest to exclude from running, or a path prefix (e.g. SQL\SQLStats) to exclude all UnitTests within this directory and all sub-directories from running

    Return Value:
    The status of this method's invocation;
    Otherwise, return an error message if an error occurred

    method deleteLoadedClasses(ByRef classLoaded, ByRef autoloadArray, ByRef utLoadedArray) as %Status

    This method deletes all of the classes provided in the following parameter arrays:

    • classLoaded()
    • autoloadArray()
    • utLoadedArray()

    Invocation:
    This method can be invoked in the following ways:

    • ObjectScript: ..deleteLoadedClasses(...)
    • SQL: N/A

    Parameters:

    classLoaded
    A Pass By Reference array of classes that have been loaded into the namespace by the invocation of a given UnitTest
    autoloadArray
    A Pass By Reference array of classes that have been auto-loaded into the namespace by the invocation of a given UnitTest
    utLoadedArray
    A Pass By Reference array of classes that have been loaded into the namespace by the UnitTest during its invocation

    Return Value:
    The status from the invocation of this method

    classmethod getLoadedClass(ByRef classes, ByRef skipClasses) as %Status

    This method will return all of classes that are loaded in the current namespace into the classes() array...

    Invocation:
    This method can be invoked in the following ways:

    • ObjectScript: ##class(%UnitTest.Manager).getLoadedClass(...)
    • SQL: N/A

    Parameters:

    classes
    A Pass By Reference array of classes that are loaded in the current namespace. This array will be populated with classes in the following format:
       classes=# of classes
       classes(<class-name>.cls)=""
      
       NOTE: The <class-name> and suffix (.cls) are case-sensitive
            
    skipClasses
    A Pass By Reference array of classes that should not be added to the 'classes()' array if found loaded in the current namespace. This array has the following format:
       skipClasses(<class-name>.cls)=""
      
       NOTE: The <class-name> and suffix (.cls) are case-sensitive
            

    Example:

                set skipClasses("Sample.Person.cls")=""
                set skipClasses("MRP.Test.cls")=""
              

    Return Value:
    The status from the invocation of this method

    classmethod getTestMethods(class As %String, ByRef methods) as %Status

    This internal method spins through all of the methods defined for the given class parameter, which start with the prefix Test, and records/returns this information in the Pass By Reference (PBR) parameter methods as an array sorted/collated in Canonical Order:

       methods=# of Methods
       methods(1..n)=Method Name
    

    classmethod setRecursiveStatus(pNamespace, pIndex, pSuite, pCase, pMethod) as %Integer

    Inherited Members

    Inherited Methods

    FeedbackOpens in a new tab