Testing an Insight Model

Topics covered in this chapter:

Activating Test Mode

If you're developing a large and complex Mosel solution to run within Insight, you may want to be able to test parts of this outside of Insight. But how to do this if your Mosel calls mminsight functions? If you put mminsight into test mode, you can simulate (or "mock") how mminsight functions will behave when your Mosel code is run outside of Insight.

To activate test mode, simply set the parameter insight_testmode to be 'true'. When in test mode, the insight_is_scenario parameter will always return 'true', insightgetmode will by default return INSIGHT_MODE_RUN and insightdispatch will execute the RUN execution mode handler, to simulate the behaviour of an Insight scenario.

Test mode should not be activated when running your application inside Insight - only in an external, non-Insight test environment.

Execution Mode

If you want to simulate execution modes other than INSIGHT_MODE_RUN, you can set this using the insightsetmode function, e.g.

insightsetmode('STATS')

In test mode, insightgetmode will return whatever was passed to the last call to insightsetmode, and insightdispatch will call the annotated procedure for this execution mode.

Scenario Data

When a Mosel model running in test mode calls insightpopulate, by default this will do nothing and return immediately. If you want to populate some data-structures when the model calls insightpopulate, you can set a procedure to be called during insightpopulate using insightsetcbpopulate, e.g.:

procedure dopopulate
  ! Initialize relevent data-structures here
  myarray(1) := 91.5
  myarray(2) := 17.312
end-procedure
insightsetcbpopulate(->dopopulate)

Scenario and Application Attributes

Application ID

To set the application ID that will be used during your test, use the insightsetappid procedure, e.g.:

insightsetappid('my_app_id')

This will set the value to be returned by insightgetappid

Application Name

To set the application name that will be used during your test, use the insightsetappname procedure, e.g.:

insightsetappname('My App')

This will set the value to be returned by insightgetappname

Scenario ID

When insight_testmode is true, you will be able to set the value of the insight_scenario_id parameter, e.g.:

setparam('insight_scenario_id','abcdefg')

Scenario Name

When insight_testmode is true, you will be able to set the value of the insight_scenario_name parameter, e.g.:

setparam('insight_scenario_name','my scenario name')

Scenario Path

When insight_testmode is true, you will be able to set the value of the insight_scenario_path parameter, e.g.:

setparam('insight_scenario_path','/my app name/my folder name/my scenario name')

User Name

To set the user name that will be used during your test, use the insightsetusername procedure, e.g.:

insightsetusername('Winston Churchill')

This will set the value to be returned by insightgetusername

Attachments

Attachment Directories

When an app is run in Insight, attachments allow you to store files directly in the scenario or application. In mminsight test mode, we simulate this using directories. Set the parameter insight_test_attach_dir to be the path of a directory; the files in a subdirectory called scenattach will be the attachments of the current scenario, while the content of a subdirectory appattach will be the application attachments. If either subdirectory doesn't exist, it will be created automatically the first time you try to access that attachment type. Alternatively, the developer can specify specific directories for app and scenario attachments using the procedures insightsettestappattachdir and insightsettestscenattachdir.

The initial content of either directory will be treated as the initial scenario and appplication attachments, and any attachment changes made by calling mminsight attachment procedures will be reflected immediately in the target directory. For example:

setparam('insight_test_attach_dir','/home/user/mytests/mytestattach')
...
! Access an attachment (read from file /home/user/mytests/mytestattach/scenattach/inputdata.dat)
insightgetscenattach('inputdata.dat')
if insightattachstatus<>INSIGHT_ATTACH_OK then
 writeln_("Error accessing attachment")
end-if
...
! Create an attachment (written to file /home/user/mytests/mytestattach/scenattach/hello.txt)
insightputscenattach('hello.txt')
if insightattachstatus<>INSIGHT_ATTACH_OK then
 writeln_("Error creating attachment")
end-if

Attachment meta-data (e.g. description, last-modified date, etc) can be written to an optional .properties file in the same directory. This file contains an insightattachment record called attach written using initializations to, for example:

declarations
  attach: insightattachment
end-declarations
attach.filename := "myattachment.dat"
attach.description := "this is the description of my attachment"
attach.tags := ['first','test']
attach.lastModifiedUser := 'Winston Churchill'
initializations to '/home/user/mytests/mytestattach/scenattach/myattachment.dat.properties'
  attach
end-initializations

If the .properties file for an attachment is missing, it will be created automatically the first time mminsight looks in that attachment directory. If the filename field specifies a different name from the actual filename, the name from the .properties file will be reported as the attachment filename by all mminsight attachment functions.

Attachment Tags

There are two ways to set the list of attachment tags that will be available. The first is to pass a list of insightattachmenttag records to insightsetattachtags, e.g.:

declarations
  test,first: insightattachment
end-declarations
first.name := 'first'
first.usage = 'single-file'
test.name := 'test'
test.usage := 'multi-file'
insightsetattachtags([first,test])

Alternatively, the tag definitions can be read directly from the application's companion file. To do this, set the parameter insight_test_cfile_path to be the path to the model companion file. mminsight in test mode will automatically try to read the tags from insight_test_cfile_path so long as this is set before the first mminsight procedure call that requires tags.

Attachment Validation

By default, Insight will perform some basic validation on new attachments and attachment meta-data: attachments must be no more than a given size, their filenames and descriptions have a maximum length, certain characters are not allowed in attachment filenames, and there is a limit to how many files can be attached to a single scenario. If you wish to set different rules during your test - for example, to check how your code handles Insight failing to add an attachment - then this can be done by calling insightsetattachrules, e.g.:

declarations
  rules: insightattachmentrules
end-declarations
rules.maxsize := 1*1024*1024
rules.maxattachcount := 3
rules.maxfilenamelen := 32
rules.invalidfilenamechars := [text('/'),text('\\'),text(' ')]
rules.maxdescriptionlen := 128
insightsetattachrules(rules)

Repository

To add repository item information records that can later be returned by insightgetiteminfo or insightgetiteminfos you can use insightadditeminfo, e.g.:

declarations
  iteminfo: insightiteminfo
end-declarations
iteminfo.id := 'myid'
iteminfo.type := 'SCENARIO'
iteminfo.path := '/mymodel/myfolder/myscenario'
iteminfo.name := 'myscenario'
iteminfo.parentpath := '/mymodel/myfolder'
insightadditeminfo(iteminfo)

Note that you must ensure all the fields of the insightiteminfo record are populated and that the path and parentpath fields are consistent. The id you specify for each item must be unique.

To remove all the insightiteminfo records previously added, you can use insightcleariteminfos.

Limitations

It is not possible to use the scenariodata: I/O driver in test mode.

It is not possible to access the attachments of other scenarios in test mode.

In test mode, the insight_nofinalize parameter and the insight.nofinalize annotation have no effect.