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

Properties

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
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 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 $$$AssertSucccess macro in the form.
$$$AssertSucccess("message")
This assertion is intended to replace the convention of passing 1 to $$$AssertTrue.
method AssertTrueViaMacro(autoquoted, value, description) as %Boolean
classmethod IsFileSame(file1, file2, diff) as %Boolean
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.
classmethod getline(file, line, eof)
classmethod parseSQLFile(file, ByRef parsed, ignoreOrderBy, noheader)

Inherited Members

Inherited Methods

Subclasses

FeedbackOpens in a new tab