IRIS for UNIX 2019.2
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:
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:
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
Maximum time in seconds to wait for the production to completely start or stop. The default is 10 seconds, override if necessary.
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.
Class name of the production. It must contain the production class name.
Production's first event log ID
DSN name pointing to namespace SAMPLES
DSN name pointing to namespace USER
Normalized directory name for HL7 archive
Normalized directory name for HL7 input
Normalized directory name for HL7 output
Normalized directory name for HL7 work
Last event log ID retrieved for this production execution
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
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.
Override this method if you are going to check errors with custom code. It's automatically invoked when parameter
Check if namespace is Interoperability or HealthShare enabled.
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
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.
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
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
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)
Create a test directory tree that is suitable for generic testing and for HL7 testing. The default root test directory is defined by property
This method does not erase any files or directories if they are already present. To do a cleanup, see method
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:
See also method
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])
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.
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.
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.
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)
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])
Generate log messages with all errors contained in status variable s.
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.
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.
Code to run right before the production is started. This is useful to:
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.
Run itself without loading/deleting any classes. Example:
See also method
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.
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.
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.