%UnitTest.Manager

class %UnitTest.Manager extends %Library.RegisteredObject

Launches tests using any of the following methods:

RunTest: Runs a set of tests and deletes all test classes afterwards.

RunTestSuites: Same as RunTest, but requires 3 arguments, all of which can be null.

DebugRunTestCase: Can be used after DebugLoadTestSuite. It runs tests and does not delete the test classes afterwards, like RunTest does.

Setup: Set the global variable ^UnitTestRoot to a root directory that contains your test suites. This must point to a valid directory. Example: Set ^UnitTestRoot="C:\MyUnittests" (adding a final slash is optional).

Specifically, the RunTest method does the following:

Loads and compiles any test files in the directory specified by the first argument, testspec. If the loadxml qualifier is on, all .xml or .XML files will be loaded.
If the loadudl qualifier is on, all udl files will be loaded.
For each class that is a subclass of %UnitTest.TestCase, RunTest
1. Runs the OnBeforeAllTests() method
2. For each method named Test*, such as TestXyz, RunTest
  1. Runs the method OnBeforeOneTest()
  2. Runs the method TestXyz()
  3. Runs the method OnAfterOneTest()
3. Repeats steps i through iii for all the other methods named Test*
4. Runs OnAfterAllTests() method
Repeats steps A through D for each class that is a subclass of %UnitTest.TestCase.
Deletes all the classes loaded during execution.
Repeats step 1 through 4 recursively (for all sub-directories) through the specified directory (assuming that the /recursive qualifier is on and skipping any directory whose name begins with an underscore).

The loading, running and deletion actions each can be skipped by specifying /noload, /norun and /nodelete qualifiers.
Unit test logs testcase output to the global ^UnitTest.Result. Results displayed on CSP pages come from this global.

Method Inventory

Properties

property CurrentDir;

The directory that contains the current test.

Property methods: CurrentDirDisplayToLogical(), CurrentDirGet(), CurrentDirIsValid(), CurrentDirLogicalToDisplay(), CurrentDirLogicalToOdbc(), CurrentDirNormalize(), CurrentDirSet()

property Debug;

Set to true if the /debug qualifier is on.

Property methods: DebugDisplayToLogical(), DebugGet(), DebugIsValid(), DebugLogicalToDisplay(), DebugLogicalToOdbc(), DebugNormalize(), DebugSet()

property Display;

Set to true if the /display=all qualifier is set.

Property methods: DisplayDisplayToLogical(), DisplayGet(), DisplayIsValid(), DisplayLogicalToDisplay(), DisplayLogicalToOdbc(), DisplayNormalize(), DisplaySet()

property LoadUDL;

Set to true if the /loadudl qualifier is set. UDL files are .cls, .mac, .int, .inc, or the upper case extensions.

Property methods: LoadUDLDisplayToLogical(), LoadUDLGet(), LoadUDLIsValid(), LoadUDLLogicalToDisplay(), LoadUDLLogicalToOdbc(), LoadUDLNormalize(), LoadUDLSet()

property LoadXML;

Set to true if the /loadxml qualifier is set.

Property methods: LoadXMLDisplayToLogical(), LoadXMLGet(), LoadXMLIsValid(), LoadXMLLogicalToDisplay(), LoadXMLLogicalToOdbc(), LoadXMLNormalize(), LoadXMLSet()

deprecated property LogIndex;

Deprecated, use ResultId.

Property methods: LogIndexDisplayToLogical(), LogIndexGet(), LogIndexIsValid(), LogIndexLogicalToDisplay(), LogIndexLogicalToOdbc(), LogIndexNormalize(), LogIndexSet()

property ReportVariableLeaks;

Set to true if unexpected public variables should trigger an error.

Property methods: ReportVariableLeaksDisplayToLogical(), ReportVariableLeaksGet(), ReportVariableLeaksIsValid(), ReportVariableLeaksLogicalToDisplay(), ReportVariableLeaksLogicalToOdbc(), ReportVariableLeaksNormalize(), ReportVariableLeaksSet()

property ResultId as %Integer;

Property to hold results instance slot in ^UnitTest.Manager

Property methods: ResultIdDisplayToLogical(), ResultIdGet(), ResultIdIsValid(), ResultIdLogicalToDisplay(), ResultIdNormalize(), ResultIdSet()

property UserFields as array of %String;

Allow users to store additional information, like platform, product version, etc. for each test. This information can be later cross-referenced in the result. This array is populated from the first level subscripts of the userparam argument.

Property methods: UserFieldsBuildValueArray(), UserFieldsCollectionToDisplay(), UserFieldsCollectionToOdbc(), UserFieldsDisplayToCollection(), UserFieldsDisplayToLogical(), UserFieldsGet(), UserFieldsGetObject(), UserFieldsGetObjectId(), UserFieldsGetSwizzled(), UserFieldsIsValid(), UserFieldsLogicalToDisplay(), UserFieldsLogicalToOdbc(), UserFieldsNormalize(), UserFieldsOdbcToCollection(), UserFieldsSet(), UserFieldsSetObject(), UserFieldsSetObjectId()

property UserParam as %String;

Set by the third argument, userparam, of the RunTest method, if specified.

Property methods: UserParamDisplayToLogical(), UserParamGet(), UserParamIsValid(), UserParamLogicalToDisplay(), UserParamLogicalToOdbc(), UserParamNormalize(), UserParamSet()

Methods

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

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

This method converts old format data in ^UnitTestLog to the new ^UnitTest.Result format.
pLogIndex is the test instance index in ^UnitTestLog.
pResultNamespace is the namespace for ^UnitTest.Result.
pMachine, pConfiguration, pVersion and pUserParam are the new information ^UnitTest.Result collects but ^UnitTestLog does not. You can provide this information manually here when doing the conversion.
pUserParam is used the same way as the userparam argument which is the 3rd argument to the RunTest method. The top node of pUserParam becomes UserParam and the first level subscripts and their values are used to populate the UserFields array.

classmethod ConvertStatus(pIndex, pNamespace) as %Status

This method updates the status at each level recursively based on the status of the children If pIndex is omitted, all the TestInstances will be converted.

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

Loads, but does not run tests in the testsuite. You can use DebugLoadTestSuite to load tests and then use DebugRunTestCase to run a test over and over again, without having to reload the tests. If you are a developer, use DebugLoadTestSuite with DebugRunTestCase to load once and then run your test many times as you debug your code.

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

Runs a test case, but does not load. testsuite and testcase are required. testcase is in the form package.class. testmethod is a method within the class. See DebugLoadTestSuite for use to test code during development.

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

Returns result for a given suite, case, method, and action.

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

This method is obsolete, use method GetTestStatus

method LogAssert(success, action, description, extra, location)

method LogMessage(message, location)

method LogStateBegin(testsuite, testcase, testmethod)

method LogStateEnd(duration) as %Integer

Record the end of a test and also return the status of this

method LogStateStatus(status, action)

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

Called after all unit tests are run. If an error status is returned, it is logged.

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

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)

Called at the end of SaveResult() to perform any result aggregation tasks required by subtasks.

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

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

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

Called before any unit tests are run. If an error status is returned, no unit tests are run.

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

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

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

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

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

Called 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 State As %String) as %Status

classmethod Root() as %String

Returns the root directory of the unit test hierarchy, usually ^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(testspec As %String, qspec As %String, ByRef userparam) as %Status

Runs classes that extend %UnitTest.TestCase that contain test methods. Creates a log on each run, stored in ^UnitTest.Result.

testspec: testspec takes the form of testsuite [ :testcase [ :testmethod ] [ ;testcase [ :testmethod ] ]* ].

testsuite is a directory (and optionally, subdirectories) that contains tests. By default RunTest runs all tests found here recursively. testspec must be a child directory of the directory named by the global ^UnitTestRoot. ^UnitTestRoot must specify a valid directory because RunTest checks for its existence before running tests. If testspec is not specified, then the ^UnitTestRoot directory is used. Any subdirectory whose name begins with an underscore ( _ ) is skipped.

testcase is a class that extends %UnitTest.TestCase (contains tests) in the form package.class and is an optional argument.

testmethod is a method name and is an optional argument.

testspec can also be an array of testsuite, or if you pass in a global name the global is an array of testsuites. In addition it also supports a comma separated set of values.
qualifiers: Any of the following command-line arguments can be combined as a single string, such as /noload/norecursive. All are optional.

The first four (debug, load, run, and recursive) are negatable Booleans. They can be turned on with /arg or off by adding no in the front, as /noload or adding =0 to the end, as /load=0.

/debug: Run in debug mode, which causes a break if a test fails. Default is /nodebug.

/load: Load use cases from the specified testspec. Default is /load. If /load and /run are both on, then all loaded classes, routines, and CSP files are deleted after the tests are run. To prevent them from being deleted at the end, load them with DebugLoadTestSuite and run them with DebugRunTestCase.

/run: Run the test suite. Use /norun if you only want to load, but not run, a suite into a namespace. Default is /run.

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

/display=all: Display extended information when loading exported test class definitions. /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 set, 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 directories.

/nodelete: Do not delete loaded classes when the test is complete.
userparam: An arbitrary argument passed in by the caller of the UnitTest. The top node of this variable becomes the value for the UserParam property of the Manager. The first level subscripts and their values are used to populate the UserFields array.

Example of RunTest:

 set ^UnitTestRoot = "c:\test"
 do ##class(%UnitTest.Manager).RunTest("sql\sqlprocs")
 do ##class(%UnitTest.Manager).RunTest("sql\sqlprocs","/debug/recursive=0")

Note: If any of your code needs to run in the %SYS namespace, zn to the %SYS namespace, run the code, then return to another namespace.

classmethod RunTestSuites(%testspec As %String, %qspec, ByRef %userparam) as %Status

Same as RunTest, but requires three arguments. These arguments can be null, as ("","","").

classmethod RunTestsFromFileList(globalName As %String = "", fileName As %String = "", qualifiers, userparam) as %Status

Run the tests that are listed within the specified fileName. The tests within this file have the following format:

[

: #

: //

][

: -

]

: utPath

: # \| : //	Optional - Specifies a comment line
: -	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 1^st 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: ^utGloba(
: 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
qualifiers: Any of the following command-line arguments can be combined as a single string, such as /noload/norecursive. All are optional.

The first four (debug, load, run, and recursive) are negatable Booleans. They can be turned on with /arg or off by adding no in the front, as /noload or adding =0 to the end, as /load=0.

/debug: Run in debug mode, which causes a break if a test fails. Default is /nodebug.

/load: Load use cases from the specified testspec. Default is /load. If /load and /run are both on, then all loaded classes, routines, and CSP files are deleted after the tests are run. To prevent them from being deleted at the end, load them with DebugLoadTestSuite and run them with DebugRunTestCase.

/run: Run the test suite. Use /norun if you only want to load, but not run, a suite into a namespace. Default is /run.

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

/display=all: Display extended information when loading exported test class definitions. /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 set, 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 directories.

/nodelete: Do not delete loaded classes when the test is complete.
userparam: An arbitrary argument passed in by the caller of the UnitTest. The top node of this variable becomes the value for the UserParam property of the Manager. The first level subscripts and their values are used to populate the UserFields array.

method SaveResult(duration, ByRef userparam)

classmethod WipeNamespace()

Wipe all data from this namespace and all PPG information also. Useful in cleaning a namespace before running unit tests. Never do this on a production system!

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

------------------------------------------------------------------------------ METHOD: addToExcludeGlobal DESCRIPTION: 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(...) ..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

------------------------------------------------------------------------------ METHOD: deleteLoadedClasses DESCRIPTION: 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

------------------------------------------------------------------------------ METHOD: getLoadedClass DESCRIPTION: 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(...) ..getLoadedClass(...) SQL: N/A PARAMETERS: classes - A Pass By Reference array of classes that are loaded in the current namspace. This array will be populated with classes in the following format: classes=# of classes classes(.cls)="" NOTE: The 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(.cls)="" EXAMPLE: skipClasses("Sample.Person.cls")="" skipClasses("MRP.Test.cls")="" NOTE: The and suffix (.cls) are case-sensitive RETURN Value: The status from the invocation of this method ------------------------------------------------------------------------------

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

%UnitTest.Manager

Property Inventory

Method Inventory

Properties

Methods

Inherited Members

Inherited Methods