Skip to main content

%UnitTest.TestCase

Class %UnitTest.TestCase Extends %RegisteredObject [ System = 3 ]

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.

Parameters​

AutoUserNames​

Parameter AutoUserNames As STRING;

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.

AutoUserRoles​

Parameter AutoUserRoles As STRING;

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.

AutoUserResources​

Parameter AutoUserResources As STRING;

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.

AutoGiveUsersNSAccess​

Parameter AutoGiveUsersNSAccess As BOOLEAN = 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.

Properties​

Manager​

Property Manager As %UnitTest.Manager [ Private ];

Pointer to the %UnitTest.Manager object

Debug​

Property Debug As %Boolean [ InitialExpression = 0 ];

Use the /debug flag with %UnitTest.Manager.RunTest to break into debug mode on the first failure.

SkipTest​

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.

AutoPassword​

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.

Methods​

%OnNew​

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.

OnBeforeAllTests​

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 }

OnAfterAllTests​

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.

OnBeforeOneTest​

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.

OnAfterOneTest​

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.

AssertEqualsViaMacro​

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")

AssertNotEqualsViaMacro​

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")

AssertTrueViaMacro​

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")

AssertFailureViaMacro​

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).

AssertSuccessViaMacro​

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.

AssertSkippedViaMacro​

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.

AssertNotTrueViaMacro​

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")

AssertStatusOKViaMacro​

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")

AssertStatusNotOKViaMacro​

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")

AssertStatusEqualsViaMacro​

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")

AssertFilesSameViaMacro​

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")

AssertFilesSQLUnorderedSameViaMacro​

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")

Checkout​

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

IsFileOrderSame​

ClassMethod IsFileOrderSame(file1, file2, diff, ignoreOrderBy, skipPlan, noheader) As %Boolean [ Internal ]

fileLines​

ClassMethod fileLines(file) [ Internal ]

parseSQLFile​

ClassMethod parseSQLFile(file, ByRef parsed, ignoreOrderBy, noheader) [ Internal ]

IsFileSame​

ClassMethod IsFileSame(file1, file2, diff) As %Boolean [ Internal ]

getline​

ClassMethod getline(file, line, eof) [ Internal ]

LogMessage​

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.

GetSourceLocation​

Method GetSourceLocation(pStack As %String = "") As %String [ Internal, Private ]

Return the source code location of the caller's stack frame in label[+offset]^[|"ns"|]doc.ext format. Returns pStack if it can't be mapped.

ParseAutoQuoted​

ClassMethod ParseAutoQuoted(argline As %String, type As %String) As %String [ Private ]

This method returns a useful description based on arguments used in the Assert macros.