class %UnitTest.Manager
extends %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 .xml or .XML file in the directory specified by the first argument, testspec.
- For each class that is a subclass of %UnitTest.TestCase, RunTest
- Runs the OnBeforeAllTests() method
- For each method named Test*, such as TestXyz, RunTest
- Runs the method OnBeforeOneTest()
- Runs the method TestXyz()
- Runs the method OnAfterOneTest()
- Repeats steps i through iii for all the other methods named Test*
- 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.
Note: This reference material draws from the article
Unit Testing in Cache by Ramon Jimenez.
• property CurrentDir
;
The directory that contains the current test.
• property Debug
;
Set to true if the /debug qualifier is on.
• property Display
;
Set to true if the /display=all qualifier is set.
• property LogIndex
;
• 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 UserParam
as %String;
Set by the third argument, userparam, of the RunTest method, if specified.
• 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 these information manually here when doing the conversion
pUserParam is used the same way as the userparam argument which is the 3rd argument to RunTest method.
The top node of pUserParam becomes UserParam and the first level subscripts and their values are used to populate UserFields array collection.
• 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 = "")
as %Status
Runs a test case, but does not load. testsuite and testcase are required. testcase is in the form package.class. test is a method within the class. See DebugLoadTestSuite for use to test code during development.
• 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)
• method LogMessage(message)
• method LogStateBegin(testsuite, testcase, testmethod)
• method LogStateEnd(duration)
• method LogStateStatus(status, action)
• method PrintErrorLine(text)
• method PrintLine(text, level)
• method PrintURL()
• classmethod PurgeLog()
as %Status
• classmethod PurgeResult()
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, test As %String = "")
• method RunOneTestSuite(dir As %String, suite As %String, testspec As %String, qstruct)
• classmethod RunTest(testspec As %String, qspec As %String, 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 ] ].
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.
- 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 are deleted after the tests are run. To prevent classes 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.
- userparam
- An arbitrary argument passed in by the caller of the UnitTest. The top node of this variable becomes the value for UserParam property of the Manager.
The first level subscripts and their values are used to populate 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, userparam)
as %Status
Same as RunTest, but requires three arguments. These arguments can be null, as ("","","").
• method SaveResult(duration)
• classmethod setRecursiveStatus(pNamespace, pIndex, pSuite, pCase, pMethod)
as %Integer
