Skip to main content


class %UnitTest.TestProduction extends %UnitTest.TestCase

Unit test base class specialized for testing productions.
Unit tests created based on this class are associated with one production. When the unit test is run, it automatically starts the production, allows it to run for a parameterized time, puts new event log entries in an array and passes control to a method for custom verifications, then stops the production and checks for errors.
The programmer can adjust some parameters, add code to verify results, and use callback methods to handle events before/after start/stop production.

How to use this class:

There are methods to facilitate usage, such as change settings, retrieve additional records from the Interoperability event log, compare files, etc. More details are given below and in the description for each method.

General utility/helper methods available to be used in the test code:

File management utility/helper methods available to be used in the test code (all with normalized names):

The following properties are available:

Utility/helper methods to be used during test development or debugging:

Property Inventory

Method Inventory


If any errors appear in the Event Log during execution of the production, the test will fail. In many cases, errors are expected to happen. In this case, override this parameter. You may also want to check them manually by overriding the method CheckErrors().
parameter MAXWAIT = 10;
Maximum time in seconds to wait for the production to completely start or stop. The default is 10 seconds, override if necessary.
parameter MINRUN = 10;
Minimum time to let production run before collecting event log entries of type "infouser" and check for results. The default is 10 seconds, override if necessary. This varies with the production; some productions only need to run for a little time, and some require more time.
parameter PRODUCTION;
Class name of the production. It must contain the production class name.


property BaseLogId as %Integer;
Production's first event log ID
Property methods: BaseLogIdDisplayToLogical(), BaseLogIdGet(), BaseLogIdIsValid(), BaseLogIdLogicalToDisplay(), BaseLogIdNormalize(), BaseLogIdSet()
property DSNToSamples as %String;
DSN name pointing to namespace SAMPLES
Property methods: DSNToSamplesDisplayToLogical(), DSNToSamplesGet(), DSNToSamplesIsValid(), DSNToSamplesLogicalToDisplay(), DSNToSamplesLogicalToOdbc(), DSNToSamplesNormalize(), DSNToSamplesSet()
property DSNToUser as %String;
DSN name pointing to namespace USER
Property methods: DSNToUserDisplayToLogical(), DSNToUserGet(), DSNToUserIsValid(), DSNToUserLogicalToDisplay(), DSNToUserLogicalToOdbc(), DSNToUserNormalize(), DSNToUserSet()
property HL7ArchiveDir as %String;
Normalized directory name for HL7 archive
Property methods: HL7ArchiveDirDisplayToLogical(), HL7ArchiveDirGet(), HL7ArchiveDirIsValid(), HL7ArchiveDirLogicalToDisplay(), HL7ArchiveDirLogicalToOdbc(), HL7ArchiveDirNormalize(), HL7ArchiveDirSet()
property HL7InputDir as %String;
Normalized directory name for HL7 input
Property methods: HL7InputDirDisplayToLogical(), HL7InputDirGet(), HL7InputDirIsValid(), HL7InputDirLogicalToDisplay(), HL7InputDirLogicalToOdbc(), HL7InputDirNormalize(), HL7InputDirSet()
property HL7OutputDir as %String;
Normalized directory name for HL7 output
Property methods: HL7OutputDirDisplayToLogical(), HL7OutputDirGet(), HL7OutputDirIsValid(), HL7OutputDirLogicalToDisplay(), HL7OutputDirLogicalToOdbc(), HL7OutputDirNormalize(), HL7OutputDirSet()
property HL7WorkDir as %String;
Normalized directory name for HL7 work
Property methods: HL7WorkDirDisplayToLogical(), HL7WorkDirGet(), HL7WorkDirIsValid(), HL7WorkDirLogicalToDisplay(), HL7WorkDirLogicalToOdbc(), HL7WorkDirNormalize(), HL7WorkDirSet()
property InstanceName as %String;
Instance name
Property methods: InstanceNameDisplayToLogical(), InstanceNameGet(), InstanceNameIsValid(), InstanceNameLogicalToDisplay(), InstanceNameLogicalToOdbc(), InstanceNameNormalize(), InstanceNameSet()
property LastLogId as %Integer;
Last event log ID retrieved for this production execution
Property methods: LastLogIdDisplayToLogical(), LastLogIdGet(), LastLogIdIsValid(), LastLogIdLogicalToDisplay(), LastLogIdNormalize(), LastLogIdSet()
property MachineName as %String;
Machine name
Property methods: MachineNameDisplayToLogical(), MachineNameGet(), MachineNameIsValid(), MachineNameLogicalToDisplay(), MachineNameLogicalToOdbc(), MachineNameNormalize(), MachineNameSet()
property MainDir as %String;
Normalized root test directory name, which by default is directory TestAutoNNN on the same level as the InterSystems IRIS or HealthShare instance, and where NNN is the build number. To initialize the directory tree see method CreateMainDirTree().
Property methods: MainDirDisplayToLogical(), MainDirGet(), MainDirIsValid(), MainDirLogicalToDisplay(), MainDirLogicalToOdbc(), MainDirNormalize(), MainDirSet()


classmethod ChangeSetting(production As %String = "", configName As %String = "", setting As %String = "", value As %String = "", saveToProduction As %Boolean = 0) as %Status
Change the value of a setting for a production item, optionally updating the production class too. Examples:
Set s = ..ChangeSetting([Production], ConfigName, Setting, Value)
Set s = ##class(%UnitTest.TestProduction).ChangeSetting(Production, ConfigName, Setting, Value, 1)
The values are validated. Check the return for errors.
method CheckErrors() as %Status
Override this method if you are going to check errors with custom code. It's automatically invoked when parameter IGNOREPRODUCTIONERRORS = 1.
classmethod CheckNamespace() as %Status
Check if namespace is Interoperability or HealthShare enabled.
method CheckResults(ByRef Log As %String, New As %String) as %Status
Fill in with code to check the results for the production execution.
This method is initialized with a local array containing user created entries of type "Info" from the Event Log, not including the start production/components entries, with the following contents:
Log = last existing seq for array Log()
Log(seq, fieldname) = fieldvalue
To get other entries from the Event Log, or for more information about the array contents, see method GetEventLog().
Return $$$OK in most cases, or an error status if you want to indicate that there was a failure. Remember that failures are automatic when unit test macros are used.
method CompareFiles(FileName1 As %String = "", FileName2 As %String = "", Dir1 As %String = "", Dir2 As %String = "") as %Status
Compare the contents of two files and return $$$OK if they are equal, or a status code otherwise.
The default for FileName2 is the same name as FileName1 concatenated with _reference before the last file extension.
FileName1 = MyFile.txt, default FileName2 = MyFile_Reference.txt
FileName1 = HL7Message_ADTA01, default FileName2 = HL7Message_ADTA01_Reference
The default for Dir1 is the directory name specified by HL7OutputDir.
The default for Dir2 is the unit test directory.
method CopyFile(FileName As %String = "", SourceDir As %String = "", TargetDir As %String = "") as %Status
Copy a file from a directory to another directory. This allows for example to place files in input directories. The default origin directory SourceDir is the unit test directory. The default destination directory TargetDir is the directory name specified by HL7InputDir.
classmethod CreateCredentials(CredId As %String = "", User As %String = "", Pw As %String = "") as %Status
Define credentials. If one already exists with the same Id, it's overwritten. Examples:
Set s = ..CreateCredentials(Id, UserName, Password)
Set s = ##class(%UnitTest.TestProduction).CreateCredentials(Id, UserName, Password)
method CreateMainDirTree() as %Status
Create a test directory tree that is suitable for generic testing and for HL7 testing. The default root test directory is defined by property MainDir.
This method does not erase any files or directories if they are already present. To do a cleanup, see method CleanUpDirectory().
This method may be invoked in OnBeforeAllTests() or OnBeforeProductionStart() to initialize the test directory tree.
classmethod Debug() as %Status
Run itself in debug mode, without loading/deleting any classes. If an assertion fails or if an error is encountered, execution will pause. Example:
Do ##class(MyTestClass).Debug()
See also method Run().
classmethod Error(msg As %String = "", s As %Status = "") as %Status
Compose a general error message as %Status with the text message provided. If message is the null string, this method returns $$$OK instead.
To append text to an existing error text, pass the status as a second argument.
Set status=..Error(message, [oldstatus])
Set status=##class(%UnitTest.TestProduction).Error(message, [oldstatus])
classmethod Export(dir As %String = "", suite As %String = "")
Export all classes in the same package to a directory as a set of individual files.
If the directory is not specified, then ^UnitTestRoot will be used as a base and the last piece of the package name will be used as the subdirectory name.
If the suite name is not specified, then the last piece of the package name of the current class will be used.
Note that parameter suite is ignored when a directory is specified.
Do ##class(MyTestClass).Export()
Do ##class(MyTestClass).Export("D:\Test\MyProductionTests\TempDir")
Do ##class(MyTestClass).Export(,"MySuite")
To do: In production-enabled namespaces, all rules and VDoc schemas whose names start with the package should also be exported.
To do: Think about other kinds of files such as CSP pages.
method GetEventLog(type As %String = "all", name As %String = "", baseId As %Integer, ByRef v As %String, Output New As %Integer) as %Status
Retrieve records from the Interoperability event log, returning them in an array.
type = "info" or "error" or "trace" or "warning" or "alert" or "assert" or "infouser" or "startstop" or "other" name = config name to filter entries (only fetch entries associated with this config name)
To get new user entries of type "Info":
Set s = ..GetEventLog("infouser", "", "", .Log, .New)
To get new entries of type "Trace":
Set s = ..GetEventLog("trace", "MyBP", "", .Log, .New)
where New indicates how many new entries were found.
Sample format for the returned array:
Log(1,"Text")="Production 'QDENS.HL7.HL7Routing.Production' is up-to-date."
Log(1,"TimeLogged")="2006-12-05 17:41:06.421"
classmethod GetFullName(Dir As %String = "", FileName As %String = "") as %String
Given a directory and a file name, return a normalized full file name.
classmethod GetSetting(production As %String = "", configName As %String = "", setting As %String = "", Output value As %String) as %Status
Get the current value of a setting for a production item. Value must be passed by reference. Examples:
Set s = ..GetSetting([Production], ConfigName, Setting, .Value)
Set s = ##class(%UnitTest.TestProduction).GetSetting(Production, ConfigName, Setting, .Value)
classmethod ListSettings(production As %String = "", configName As %String = "")
List all existing settings and their values for a given production and config item name. If a config name is provided, all settings for this config name are listed. Otherwise all config names are listed. Examples:
Do ##class(MyTestClass).ListSettings(, [configname])
Do ##class(%UnitTest.TestProduction).ListSettings(production, [configname])
method LogErrors(s As %Status = 1, where As %String = "")
Generate log messages with all errors contained in status variable s.
method OnAfterProductionStart() as %Status
Code to run right after the production is started. Used, for example, to call a method that initiates the test. If an error status is returned, the test will be aborted and failed and the production will be stopped. So if a non fatal error occurs, you may invoke ..LogErrors(status,"OnAfterProductionStart()") and return $$$OK.
method OnAfterProductionStop() as %Status
Code to run right after the production is stopped. If an error status is returned, the test is failed. If a non fatal error occurs, you may invoke ..LogErrors(status,"OnAfterProductionStop()") and return $$$OK.
method OnBeforeProductionStart() as %Status
Code to run right before the production is started. This is useful to:
If an error status is returned, the test will be aborted and failed. So if a non fatal error occurs, you may invoke ..LogErrors(status,"OnBeforeProductionStart()") and return $$$OK.
method OnBeforeProductionStop() as %Status
Code to run right before the production is stopped. If an error status is returned, the test will be failed and aborted, the production will be stopped. If a non fatal error occurs, you may invoke ..LogErrors(status,"OnBeforeProductionStop()") and return $$$OK.
classmethod Run() as %Status
Run itself without loading/deleting any classes. Example:
Do ##class(MyTestClass).Run()
See also method Debug().
classmethod SelectToString(ByRef Log As %String, Prop As %String = "", Value As %String = "", Del As %String = "^") as %String
Extract select text information from the event log returned results, and return a delimited string containing the count followed by selected values, filtering by property/index Prop equals to Value.
classmethod SendRequest(Name As %String = "", Req As %RegisteredObject, ByRef Resp As %RegisteredObject, GetReply As %Boolean = 0, Time As %Integer = 30) as %Status
Call Interoperability testing service to send a request to a business process or business operation. This is a way to invoke them directly without creating a dummy business service. The production needs to be enabled for testing.
If no request object type is passed, then type Ens.Request is assumed.
Set s = ..SendRequest("MyBPName", MyRequestObject, .Response, [GetReply], [Time])
GetReply=1 indicates a response is expected (default is 0).
Time indicates how long to wait for a response in case GetReply=1. Default is 30 secs.
method SubMainDir(AddDirs="") as %String
Helper method to return the normalized directory name for the full directory path composed of the default test directory plus the additional directories, eg. sub1/sub2. The argument containing the additional directories must use slashes ( / ) as the directory delimiter, on all platforms.

Inherited Members

Inherited Properties

Inherited Methods

FeedbackOpens in a new tab