Skip to main content

%UnitTest.TestCase

class %UnitTest.TestCase extends %Library.RegisteredObject

Extend this class to create new test case classes. In the test case class, for each test that you want to run, create a method whose name begins with Test. You'll use %UnitTest.Manager.RunTest to run all tests in a specified directory.

TestCase provides $$$Assert* macros that can be used to test conditions (located in the file %outUnitTest.INC). The $$$Assert* macros call their associated methods automatically. A test fails if one or more of the macros fails, otherwise the test passes.

Click a method to go to the description of its macro:

AssertTrueViaMacro()
AssertNotTrueViaMacro()
AssertEqualsViaMacro()
AssertNotEqualsViaMacro()
AssertStatusOKViaMacro()
AssertStatusNotOKViaMacro()
AssertFilesSameViaMacro()
AssertFilesSQLUnorderedSameViaMacro()
AssertSuccessViaMacro()
AssertFailureViaMacro()
AssertSkippedViaMacro()

Use the OnBefore* methods to perform tasks before all test cases or before each test case.
Use the OnAfter* methods to perform tasks after all test cases or after each test case.

You might use OnBefore* and OnAfter* to, for example, set environment variables before tests and unset them after tests or load files before tests and delete files after tests.

Click a method to go to the description:

OnBeforeAllTests()
OnBeforeOneTest()
OnAfterAllTests()
OnAfterOneTest()

Note: In your test class, do not use property names that begin with Test, as the auto-generated Get and Set methods corresponding to the properties would also begin with Test, and, thus, be treated as test methods.

Property Inventory

Method Inventory

Parameters

parameter AutoGiveUsersNSAccess = 0;
If 1, guarantees that all users listed in AutoUserNames have read-write access in the namespace the unit test is starting from. If 0, access is governed by the assigned roles and resources. Default is 0.
parameter AutoUserNames;
String of test users. If this parameter is set, then %UnitTest.Manager will create these users before running any test methods. Users will be cleaned up after the test completes. Privileges for each user can be specified in AutoUserResources and AutoUserRoles. If AutoUserNames is left unspecified, the %UnitTest.Manager framework won't autocreate any test users. Separate usernames with ";" marks. White spaces are stripped out and ignored.
parameter AutoUserResources;
Optional: specifies resources for each test user in AutoUserNames. If a list of resources is specified for a user, the %UnitTest.Manager will create a test role for that user that has the listed resources. Separate lists of roles for different users with ";" marks. Separate different roles for the same user with "," marks. Make sure to specify the permissions with the resource. For example: "%DB_%DEFAULT:RW". White spaces are stripped out and ignored.
parameter AutoUserRoles;
Optional: specifies roles for each test user in AutoUserNames. Separate lists of roles for different users with ";" marks. Separate different roles for the same user with "," marks. White spaces are stripped out and ignored.

Properties

property AutoPassword as %String;
If %UnitTest.Manager creates test users specified by AutoUserNames, it will generate a random-string password for them to share and store it in this property. This password is generated anew each time the unit test is run.
Property methods: AutoPasswordDisplayToLogical(), AutoPasswordGet(), AutoPasswordIsValid(), AutoPasswordLogicalToDisplay(), AutoPasswordLogicalToOdbc(), AutoPasswordNormalize(), AutoPasswordSet()
property Debug as %Boolean [ InitialExpression = 0 ];
Use the /debug flag with %UnitTest.Manager.RunTest to break into debug mode on the first failure.
Property methods: DebugDisplayToLogical(), DebugGet(), DebugIsValid(), DebugLogicalToDisplay(), DebugNormalize(), DebugSet()
property SkipTest as %Boolean [ InitialExpression = 0 ];
The SkipTest property gets set when a test is being skipped. It will be handled by the %UnitTest.Manager to handle skipping tests from OnBeforeOneTest. NOTE: OnBeforeAllTests does not currently support skipping tests.
Property methods: SkipTestDisplayToLogical(), SkipTestGet(), SkipTestIsValid(), SkipTestLogicalToDisplay(), SkipTestNormalize(), SkipTestSet()

Methods

method %OnNew(initvalue) as %Status
Run by the %New method to provide notification that a new instance of an object is being created. Passes initialization information to a new instance of the object.

If this method returns an error then the object is not created.
It is passed the arguments provided in the %New call. There may be up to ten of these arguments, p1...p10.
method AssertEqualsViaMacro(autoquoted, value1, value2, description) as %Boolean
Returns true if two values are equal. Invoke with the $$$AssertEquals macro, in the form
$$$AssertEquals(value1,value2,"description")
where:
value1,value2
Values to be compared.
description
Optional comment shown on the results page. If you don't include a description, the expression is used by default.
Example:
do $$$AssertEquals(x,y,"x equals y")
method AssertFailureViaMacro(message) as %Boolean
Unconditionally log a failure. Invoke with the $$$AssertFailure macro in the form.
$$$AssertFailure("message")
This assertion is intended to replace the convention of passing 0 to $$$AssertTrue. It's useful when the condition is implicit (e.g., in a try block after an exception should have been thrown), and when you don't want to pollute the log with many successful assertions (e.g., in a loop).
method AssertFilesSQLUnorderedSameViaMacro(autoquoted, file1, file2, description, ignoreOrderBy=0, skipPlan="", noheader=0) as %Boolean
Returns true if two files containing SQL query results contain the same unordered results. Invoke with the $$$AssertFilesSQLUnorderedSame macro in the form.
$$$AssertFilesSQLUnorderedSame(file1,file2,"description")
where:
file1,file2
Files to compare. If no directory path is specified, the current UnitTest directory is used.
description
Optional comment shown on the results page. If you don't include a description, the expression is used by default.
ignoreOrderBy
Optional boolean stating to ignore "order by" when determining whether results are ordered
skipPlan
Optional boolean stating to not include output from ShowPlan in diff. This feature will be enabled by default if ^%SYS("HINT","%PARALLEL")=1 but off in any other cases
noheader
Optional boolean stating that there is no header in the SQL reference file
Example:
do $$$AssertFilesSQLUnorderedSame(output.log,reference.log,"Comparing output.log to reference.log")
method AssertFilesSameViaMacro(autoquoted, file1, file2, description) as %Boolean
Returns true if two files are identical. Invoke with the $$$AssertFilesSame macro in the form.
$$$AssertFilesSame(file1,file2,"description")
where:
file1,file2
Files to compare. If no directory path is specified, the current UnitTest directory is used.
description
Optional comment shown on the results page. If you don't include a description, the expression is used by default.
Example:
do $$$AssertFilesSame(output.log,reference.log,"Comparing output.log to reference.log")
method AssertNotEqualsViaMacro(autoquoted, value1, value2, description) as %Boolean
Returns true if expressions are not equal. Invoke with the $$$AssertNotEquals macro in the form.
$$$AssertNotEquals(value1,value2,"description")
where:
value1,value2
Values to be compared.
description
Optional comment shown on the results page. If you don't include a description, the expression is used by default.
Example:
do $$$AssertNotEquals(x,y,"x is not equal to y")
method AssertNotTrueViaMacro(autoquoted, value, description) as %Boolean
Returns true if the expression is not true. Invoke with the $$$AssertNotTrue macro in the form.
$$$AssertNotTrue(value, "description")
where:
value
Expression to be evaluated.
description
Optional comment shown on the results page. If you don't include a description, the expression is used by default.
Example:
do $$$AssertNotTrue(x=y,"Expression x=y is not true")
method AssertSkippedViaMacro(message) as %Boolean
An assertion to state that the test has been skipped for the reason described in the assertion's message This would typically be used if the preconditions for the test have not been met. After calling this assertion, you would typically would want to quit from the test method.
NOTE: OnBeforeAllTests does not currently support skipping tests. Calls to $$$AssertSkipped in OnBeforeAllTests may result in tests appearing to pass rather than being skipped.
method AssertStatusEqualsViaMacro(autoquoted, value1, value2, description) as %Boolean
Returns true if two statuses are equal. Invoke with the $$$AssertStatusEquals macro in the form.
$$$AssertStatusEquals(value1,value2,"description")
where:
value1,value2
Expressions that return status codes.
description
Optional comment shown on the results page. If you don't include a description, the expression is used by default.
Example: This is extremely useful to verify an expected failure.
s x=##class(Sample.Person).%New()
s sc=x.%Save()
s sc2=$system.Status.Error(5659,"Name")
d $$$AssertStatusEquals(sc,sc2,"Verify Name property requirement at %Save")
method AssertStatusNotOKViaMacro(autoquoted, status, description) as %Boolean
Returns true if the status code is not a successful status code. Invoke with the $$$AssertStatusNotOK macro in the form.
$$$AssertStatusNotOK(value, "description")
where:
value
Expression that returns a status code.
description
Optional comment shown on the results page. If you don't include a description, the expression is used by default.
Example:
set sc=##class(%Integer).IsValid("$")
do $$$AssertStatusNotOK(sc,"Status is NotOK")
method AssertStatusOKViaMacro(autoquoted, status, description) as %Boolean
Returns true if the status code is $$$OK. Invoke with the $$$AssertStatusOK macro in the form.
$$$AssertStatusOK(value, "description")
where:
value
Expression that returns a status code.
description
Optional comment shown on the results page. If you don't include a description, the expression is used by default.
Example:
set sc=##class(%Integer).IsValid("5")
do $$$AssertStatusOK(sc,"Status is OK")
method AssertSuccessViaMacro(message) as %Boolean
Unconditionally log success. Invoke with the $$$AssertSuccess macro in the form.
$$$AssertSuccess("message")
This assertion is intended to replace the convention of passing 1 to $$$AssertTrue.
method AssertTrueViaMacro(autoquoted, value, description) as %Boolean
Returns true if expression is true. Invoke with the $$$AssertTrue macro in the form.
$$$AssertTrue(value, "description")
where:
value
Expression to be evaluated.
description
Optional comment shown on the results page. If you don't include a description, the expression is used by default.
Example:
do $$$AssertTrue(x=y,"Expression x=y is true")
method Checkout(file1, file2, forceref=0)
Helper method that will check out the one file in Perforce and copy the output to the reference file so we can diff the output and see if the change is expected or not to help when things like ShowPlan changes are made which can alter a lot of output
method LogMessage(message)
Enter a message in quotes, such as "Start of test". Message is entered in the log (^UnitTest.Result) when a test is run.
method OnAfterAllTests() as %Status
Run by RunTest once after all test methods in the test class are run. Can be used to tear down a test environment that was set up by OnBeforeAllTests See example in OnBeforeAllTests.
method OnAfterOneTest(testname As %String) as %Status
Run by RunTest immediately after each test method in the test class is run.
testname
Name of the test to be run. Required.
method OnBeforeAllTests() as %Status
Run by RunTest once before any test methods in the test class are run. Can be used to set up a test environment that will be later cleaned up by OnAfterAllTests.
NOTE: OnBeforeAllTests does not currently support skipping tests. Calls to $$$AssertSkipped in OnBeforeAllTests may result in tests appearing to pass rather than being skipped.

Example: Setup and Cleanup of an environment:
Method OnBeforeAllTests() As %Status
{
	//do setup stuff here
 	set ^inputMessage = "input message"
	quit $$$OK
}
Method OnAfterAllTests() As %Status
{
	//do clean up stuff here
	kill ^inputMessage
	quit $$$OK
}
method OnBeforeOneTest(testname As %String) as %Status
Run by RunTest immediately before each test method in the test class is run.
testname
Name of the test to be run. Required.

Inherited Members

Inherited Methods

Subclasses

FeedbackOpens in a new tab