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.
Note: This class is not intended to be used in InterSystems IRIS instances.
How to use this class:
- Create a subclass of this base class, one per production. Typically there will be one directory per production, and one unit test class per directory/production, called for example Test.xml. In case one wants to run the same production with various settings there may be additional unit test classes such as Test2.xml, Test3.xml, etc.
- Override parameter PRODUCTION to contain the production class name.
- Override parameters MAXWAIT, MINRUN and IGNOREPRODUCTIONERRORS if the defaults are not adequate to the production case.
- Override method CheckResults to include your code with custom verification of the intended production results.
- Override method CheckErrors if you set IGNOREPRODUCTIONERRORS = 1 and want to check the errors yourself.
- Override methods OnBeforeProductionStart and OnAfterProductionStart with code to run before or after the production is started, for example to put files in place (before start), or to call a method that fires the test by instantiating a business service and sending a message (after start).
- Override methods OnBeforeProductionStop and OnAfterProductionStop with
code to run right before or after the production is stopped, if needed.
Note: Initialization and cleanup code may go as usual into OnBeforeOneTest, OnAfterOneTest, etc.
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:
- GetSetting: Get the current value of a setting for a production item.
- ChangeSetting: Change the value of settings for production items.
- CreateCredentials: Define credentials.
- SendRequest: Call Interoperability testing service to send a request.
- CopyFile: Copy a file from a directory to another directory.
- CompareFiles: Compare the contents of two files.
- Error: Compose a general error message as %Status with the text message provided.
- LogErrors: Generate log messages with all errors contained in a status variable.
- GetEventLog: Retrieve records from the Interoperability event log.
- SelectToString: Return a string containing select information from the Event Log.
File management utility/helper methods available to be used in the test code (all with normalized names):
- CreateMainDirTree: Initialize test directories, with subdirectories for HL7 use.
- CopyFile: Copy a file from a directory to another directory.
- CompareFiles: Compare the contents of two files.
- CleanUpDirectory: Remove all files from a directory or tree.
The following properties are available:
Utility/helper methods to be used during test development or debugging:
- Run: Run without loading/deleting any classes.
- Debug: Run in debug mode, without loading/deleting any classes.
- Export: Export all classes in a package to a directory.
- ListSettings: List to the terminal all current settings for a given production and config item.
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.
Production's first event log ID property DSNToSamples as %String;
DSN name pointing to namespace SAMPLES property DSNToUser as %String;
DSN name pointing to namespace USER property HL7ArchiveDir as %String;
Normalized directory name for HL7 archive property HL7InputDir as %String;
Normalized directory name for HL7 input property HL7OutputDir as %String;
Normalized directory name for HL7 output property HL7WorkDir as %String;
Normalized directory name for HL7 work property InstanceName as %String;
Instance name property LastLogId as %Integer;
Last event log ID retrieved for this production execution property MachineName as %String;
Machine name 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.
Change the value of a setting for a production item, optionally updating the production class too. Examples: method CheckErrors() as %Status
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.
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. method CompareFiles(FileName1 As %String = "", FileName2 As %String = "", Dir1 As %String = "", Dir2 As %String = "") as %Status
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.
Compare the contents of two files and return $$$OK if they are equal, or a status code otherwise. method CopyFile(FileName As %String = "", SourceDir As %String = "", TargetDir As %String = "") as %Status
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.
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: method CreateMainDirTree() as %Status
Set s = ..CreateCredentials(Id, UserName, Password)
Set s = ##class(%UnitTest.TestProduction).CreateCredentials(Id, UserName, Password)
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. classmethod Debug() as %Status
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.
Run itself in debug mode, without loading/deleting any classes. If an assertion fails or if an error is encountered, execution will pause. Example: classmethod Error(msg As %String = "", s As %Status = "") as %Status
See also method Run.
Compose a general error message as %Status with the text message provided. If message is the null string, this method returns $$$OK instead. classmethod Export(dir As %String = "", suite As %String = "")
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])
Export all classes in the same package to a directory as a set of individual files. method GetEventLog(type As %String = "all", name As %String = "", baseId As %Integer, ByRef v As %String, Output New As %Integer) as %Status
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.
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.
Retrieve records from the Interoperability event log, returning them in an array. classmethod GetFullName(Dir As %String = "", FileName As %String = "") as %String
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."
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: classmethod ListSettings(production As %String = "", configName As %String = "")
Set s = ..GetSetting([Production], ConfigName, Setting, .Value)
Set s = ##class(%UnitTest.TestProduction).GetSetting(Production, ConfigName, Setting, .Value)
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: method LogErrors(s As %Status = 1, where As %String = "")
Do ##class(MyTestClass).ListSettings(, [configname])
Do ##class(%UnitTest.TestProduction).ListSettings(production, [configname])
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: 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: classmethod SelectToString(ByRef Log As %String, Prop As %String = "", Value As %String = "", Del As %String = "^") as %String
See also method Debug.
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. method SubMainDir(AddDirs="") as %String
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.
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.