MScript Functions are provided by system and plugins. They are embedded in MScript to perform actions including interacting with AUT.

There are 5 types of MScript functions:

1. System Functions - functions provided by the system
2. User Defined Functions - functions defined by the user within a model.
3. Plugin Functions - functions provided by the plugin, only available when the plugin is activated for the model
4. Plugin Driver Functions - functions provided by the native driver used by the plugin, for example WebDriver functions provided through SeleniumPlugin
5. User MScript Functions - functions provided by a java class written by users to extend MScript capability that can be imported into models

1. web plugin functions - functions provided by SeleniumPlugin
2. SeqOut plugin functions - functions provided by SeqOut plugin
3. Remote Command/Trigger Plugin functions - functions implemented by RemoteCommandPlugin and RemoteTriggerPlugin plugins.
4. service plugin function - functions provided by ServicePlugin plugin.
5. data generation function - functions provided by DataGenPlugin plugin.
6. data design function - functions provided by DataDesignPlugin plugin.
7. Concurrent function - functions supported for concurrent modeling by EnterpriseEdition and LoadPlugin.
8. Model Orchestration & Load Modeling function - functions to support the orchestration of model executions and load testing by LoadPlugin
9. Windows UI App plugin functions - functions provided by WinUIAPlugin
10. XUIA plugin functions - functions provided by XUIA Plugin
11. Sikuli plugin functions - functions provided by Sikuli Plugin
12. BA plugin functions - functions provided by BA Plugin

With Selenium, WinUIA, JavaUIA and XUIA plugins, you may send keyboard function keys through MScript. For example, [KEYS.ENTER] and [KEYS.TAB]. For more details, see Sending Keyboard Keys.

Except User Defined Functions, functions are called like

<log msg="Calling MyFunc, return value: $myFunc ('p1','p2')"/>

The above mscript tag calls the function named myFunc, it passes two parameters to the function as required by this specific function and the return value from the function call is then concatenated with Calling MyFunc, return value: and printed to the MScript log file.

All parameters must be enclosed by a set of single quotes.

If the parameter value contains single quotes, those single quotes in the expression value do need to be escaped (prefixed) with “\”. For example:

    <action code="$click('xpath=id(\'order\')')"/>

Notice that the single quotes around “order” are escaped as they are part of the parameter value.

Function can have parameters. Parameter values are passe by position, for example $myFunc('abc','123') where abc and 123 are parameter values for the function call.

Most functions require some parameters while some don't. If a function does not require parameter, the function call would look like $myFunc().

Functions may have return value as the one above or may not have return value.

The return value can then be concatenated with other text string to form new text string as shown in the example above.

Calling to a function that does not have return value will return an empty string.

You may nest the function call within the same mscript expression. For example:

<log msg="Random number is: $rand('0,', '$increment('upBound')')"/>

In the above example, function call $increment('upBound') is first executed. Let's assume the user variable upBound has the value of 5, this function call will return 6 which is then used as the second parameter value to call $rand('0','6'). As the result, the above example will generate a random number between 0 and 6. The return value from the $rand('0','6') is then concatenated with the static text Random number is: and written to mscript log file.

There is no limit of how many levels for the nested function calls.

User Defined Functions are functions define in Functions trigger within a model.

Within Functions trigger, you use <func> tag to define the function. For example:

<func name="myFunc">
... mscript tags ...
</func>

Within the function myFunc, you can retrieve the parameters passed to the function by calling mscript function $getFuncParam('paramName'). For example:

<func name="myFunc">
    <log msg="Param p1: $getFuncParam('p1')"/>
</func>
 

User Defined Functions can return a value. To set the return value, call mscript function $setFuncReturn('retVal'). For example:

<func name="myFunc">
    <action code="$setFuncReturn('retVal')"/>
</func>

User defined functions can be shared with other models with the following MScript:

 $requires('userFuncModel');
 

The above MScript will include all user defined functions from the model called userFuncModel and make all user defined functions available to the current model.

User Defined Functions are functions define in Functions trigger within the model and thus it's model specific.

User Defined Functions can be shared with other models using $requires('modelName').

To call User Defined Functions use the following syntax:

 $callFunc('myFunc','p1=v1','p2=v2')

where p1 and p2 are the parameter names and v1 and v2 are the parameter values for the corresponding parameters.

User Defined Functions can return a value. The return value is then concatenated with other static string just like other function calls as described earlier.

User Definfed Functions can recursively call itself. However, caution must be taken not to cause infinite loop which will result server hang and crash.

Plugin Functions are functions provided by the plugins which are specifically designed to interact with different type of AUT. Besides TestOptimal provided plugins, you may also create your own custom plugins to provide mscript functions.

For example SeleniumPlugin provides a set of functions to allow you to drive web applications as show in the following:

 <action code="$click('id=button1')"/>

The $Selenium.click(…) is a plugin function implemented by SeleniumPlugin when called will click the button on the web page.

Please note that Selenium. prefix to the function name is optional when the function name is unique.

Some plugin uses 3rd party drivers to accomplish specific task, typically to interact with the AUT. For example SeleniumPlugin uses WebDriver to drive the web applications.

Each plugin has the option to expose the functions provided by the driver that it uses. Not all plugins uses 3rd party drivers, neither do all plugins expose functions from the driver. Please refer to the specific plugin documentation page listed above for more information about the native functions exposed by the plugin.

To call a native function, you must add a prefix underscore (_) to the native function name as shown in the following example:

 <action code="$_nativeFunc1('p1')"/>

User MScript Functions are functions that you implement by writing a simple java class.

The java class just need to provide the constructor in the following signature:

  public MScriptImpl2(MbtScriptExecutor scrfiptExec_p)
  

For each model, you can declare MScriptImpl java class in MBT_start trigger using MScript function addMScriptImpl('class path') or addMScriptImpl('class path','java source file'):

  <action code="$addMScriptImpl('com.abc.myClass')"/>
  or 
  <action code="$addMScriptImpl('com.abc.myClass', 'javaFileName.java')"/>
  

The first syntax requires that you have compiled your java class into jar file and deployed it to /lib/ folder. The second syntax dynamically compiles your java source code automatically when model executes.

All of the public functions declared in your java class MScriptImpl2 can be called with the following syntax:

  <action code="$_myMScriptFunc('p1')"/>

Notice the prefix of underscore (_) is required before the function name.

User MScript Functions can return a String value. The return value is then concatenated with other static text string to form another string.

If you plan to use xpath to locate the element on HTML page and have trouble finding the correct xpath string, you may want to check out WebMBT Builder and UIRepo firefox add-on.

In some rare case some special characters may cause problem to the mScript interpreter, in which case they can be encoded them using mscript tokens, such as [lt] for “<” and [gt] for “>”.