6. Scripting — Test Tool User Guide

### Navigation

- index
- next |
- previous |
- Tester User Guide »

# 6. Scripting

The Vortex OpenSplice Tester provides automatic testing capabilities by means of scripting. This section describes the features of Tester’s built-in scripting instructions, and how to install additional script engines.

## 6.1. The Script Language

The script language as used by the Tester is specifically designed to create readable and easily maintainable scripts.

Instructions are simple, with named parameters which enable the Tester to limit the testing to the fields applicable to the test. For example, the `send` instruction is an instruction which sends a topic. The basic syntax is the keyword `send` followed by the `topicname` and a list of named parameters between parentheses (‘round brackets’), terminated with a semicolon.

Illustrating send keyword syntax

The `check` instruction is similar to the `send` instruction; it has options to find a specific instance using key fields or a query.

Illustrating check keyword syntax

In this example a `timeout` is set, which will allow a wait of up to 0.2 seconds for the topic sample for the correct instance to arrive.

### 6.1.1. A script file

A `scenario` has the following format:

Illustrating scenario keyword syntax

The name is for information only, and is not used further.

### 6.1.2. Variables

The script language allows the use of variables. Variables can be used to store values that can then be used at a later time. A variable is indicated by either a `<<` or a `>>` prefix. Variables may be declared implicitly, or explicitly using the `var` instruction.

Example variable

In this example the variable `myvar` is declared and initialized with the value `5`. Within the `send` instruction the variable is used to provide the value for the field index. The `<<` prefix indicates the direction of the assignment from the variable to the field.

Variable with >> prefix

Here the variable `index_of_4` is declared implicitly and the value of the field index is copied to the variable (the prefix `>>` points to the variable).

All environment variables and java virtual machine (JVM) properties are also available as variables, and they can be used as shown below:

Using environment variables

#### 6.1.2.1. Special variables

There are some special variables which can be useful in scripts.

- `curtime_sec` and `curtime_nsec` provide the second and nanosecond parts of the current time.
- `uniqid` provides a unique number for every call, within the same session of the Tester.
- `script_file` and `script_path` provide the scenario file name and the scenario file’s path respectively. If the currently executing scenario context changes because of a `call` instruction to another scenario or macro file, using these variables in the called scenario or macro will reflect the respective path and file name of the called script.

Note that these special values are used without the `<<` prefix.

### 6.1.3. Embedded Scripts

Inside a scenario any script compatible with the java ScriptEngineFactory can be used to provide calculated values for fields in a `send`, `check` or `var` instruction, or as a stand-alone statement.

Embedded javascript

Stand-alone scripts must be enclosed by left single quotes, and then followed by a semi-colon.

Variables used in the javascript are translated before the evaluation of the script. In this specific case the `<<dt` is the delta time in the `repeat` function. All javascript in one scenario is executed in the same scope, and functions and variables declared at the beginning of a script are available later in the script.

A specific script language can be selected by providing the name of the script language in the first line of the embedded script: `#!<language>`, for example `#!js`. Note that the language description must not be followed by any other text. See section 5.6, Installing Script Engines, on page 85, for instructions on installing a scripting language for use with the OpenSplice Tester. If no language descriptor is provided on the first line of a script, the default language is used as set in Preferences.

More embedded javascript

### 6.1.4. Comments

Comments can have the following formats:

Format of comments

Within the scenario editor, comments are displayed in green.

### 6.1.5. Macros

For repeated scenarios a repetitive part can be split off into a separate script file called a macro. Macros can have parameters.

Calling a macro with parameters

Similarly to `send` and `check` instructions, values for fields can be optional. However, in a macro a default value must be provided for a parameter to be optional.

Setting a default value for a macro parameter

In this case `t` is optional, `id` and `x` are mandatory.

It is possible to call a scenario using the `call` instruction. Scenarios do not have parameters.

## 6.2. The Instructions

### 6.2.1. Send

Instruction to publish a sample of a topic.

> `send <readername> ( [fieldname => value,]*);`

The `send` instruction may include an ‘update parameter’. The `update` parameter name is a combination of the topic name, followed by an underscore (_) and the literal text ‘update’. Valid values for the update parameter are `true` and `false`. The `update` parameter allows scenario scripts to send a series of samples that evolve, each from the previous one, without having to explicitly specify all field values in each `send` instruction.

If the `update` parameter is present, then the sample data sent is retained by the topic reader, associated with the topic key field value(s). A subsequent `send` instruction, including the `update` parameter set to `true` with the same topic key field value(s), will have its sample initialized from the retained values, if they exist. The sent sample with then replace the retained values.

A `send` instruction including the `update` parameter set to `false` with the same topic key field value(s) will be initialized from the topic defaults, but the sent sample will be retained.

A `send` instruction without the `update` parameter will be initialized from the topic defaults, and any retained value for the key field value(s) will be removed.

Disposing the topic reader will remove all retained values.

### 6.2.2. Dispose

Instruction to dispose an instance of a topic.

> `dispose <readername> ( [fieldname => value,]*);`

### 6.2.3. Writedispose

Instruction to write dispose an instance of a topic.

> `writedispose <readername> ( [fieldname => value,]*);`

### 6.2.4. Check

Instruction to check a sample of a topic.

> `check[_last | _any] | recheck_last <readername> ( [timeout => <timeout in seconds>,] [<fieldname> => [!]<value>[:deviation],]*);`

A timeout value can be provided allowing the check to wait for `<timeout in seconds>` for the sample to arrive. If a sample meeting the criteria of the check is available either directly or within `timeout` seconds the fields as provided in the parameter list will be verified for correctness.

When the value of a field is an output variable:

> `>><varname>`

Then the value will not be checked but entered in the variable with the name `<varname>`.

There are two special fields, `topicReceived` and `topicDisposed`, which when used will provide a `true` or `false` value into a variable.

When no sample is found which meets the criteria of the check then `topicReceived` will be set to `false` (and the check instruction will not fail); if a sample is received the value will be set to `true`. When a field `topicDisposed` is found, then the variable will be set to `true` if the sample was disposed and `false` if the sample was not disposed. In this case no fail is reported upon a check instruction when the checked sample was disposed.

The value can be given a possible deviation in the form `<value>:<allowed deviation>`. In this case when the value for the field in the received sample is within the range from `value` minus `allowed_deviation` to `value` plus `allowed_deviation`, the value is considered correct.

The sample which matches the check can be determined in several ways:

1. The topic does not have a keyfield(s) or the topic has keyfield(s) but no value is provided for all keyfield(s). In this case the oldest not checked or marked sample is checked.
2. The topic has keyfield(s) and the check provides a value for all keyfield(s). In this case the last sample with the key is checked, so long as it was not previously checked. If no matching sample (within the possible timeout) is found then the check fails.
3. One or more fields of the check are marked as a query by prefixing the value with a `‘!’`. The oldest not checked or marked sample which matches the query is checked. If no matching sample is found (within the possible timeout) the check fails.
4. Instead of `check`, the command `check_last` is used. In this case (as for situations 1 and 3) the last not-previously-checked sample matching the criteria is checked.
5. Instead of `check`, the command `check_any` is used. In this case also previously-checked or marked samples are considered.
6. The command `recheck_last` will always check the last sample matching the criteria, regardless of whether it has previously been checked or not.

### 6.2.5. Miss

Instruction to check that no sample of a topic was received since the last checked or marked sample for the given key/query. The same rules apply as for the `check` instruction with respect to finding (or not) the matching topic sample.

> `miss <topicname> ([timeout => <timeout_in_seconds>,] [<fieldname> => [!]<value>[:<deviation>],]*);`

### 6.2.6. Disposed

Instruction to check that an instance of a topic is disposed for the given key/query. The same rules apply as for the `check` instruction with respect to finding the disposed instance. Note that field values are only provided to find a specific instance (either by key or by query) and not verified for values as part of this instruction.

> `disposed <topicname> ([timeout => <timeout_in_seconds>,] [<fieldname> => [!]<value>,]*);`

### 6.2.7. Mark

Mark all samples (with the given key/query) as read. Any regular miss/check function will not ‘see’ topic samples received before the mark instruction. If no key or query is provided all samples will be marked as read (and therefore not considered for `check` or `check_last` instructions). If a key value or query is provided, all samples matching the key/query will be marked as read.

> `mark <topicname> ( [fieldname => value,]*);`

### 6.2.8. Repeat

Instruction to repeatedly send a topic for a specified count or until disposed.

> `repeat <topicname> <period> <count> ( [fieldname => value,]*);`

If `<count>` is `‘0’` then the repeat will continue until the scenario terminates or until a dispose for the same topic and key. The variable `dt` is available for calculating a field value based on time since the repeat was started. The period indicates the period with which the topic will be sent. Note that a repeat command by itself does not extend the execution of a scenario and that when a scenario finishes (i.e. all following instructions are executed) the repeat instruction is terminated automatically. In such a case the wait or message instruction can be used to ensure that the repeat instruction is completed.

### 6.2.9. Set

The `set` instruction allows the call of a macro in a table-like fashion. The command allows a number of static parameters and variable parameters. The command has the following format:

> `set <macroname> ([<fieldname>=><value>]*)((<fieldname>*),[(<value>*),]*);`

For example, the following set instruction:

    set send_and_check_test (
         t => 2)
     ((     x,id),
      (   3.1, 1),
      (  2.34, 2),
      ( 3.678, 3),
      (  6.34, 4),
      ( 99.99, 5))

In this example the `send_and_check_test` macro is called five times, all five calls will be made with `t = 2` and the values for `x` and `id` as indicated by each row of values. This can be very useful for testing of translations.

### 6.2.10. Execute

The `execute` instruction allows the execution of an application or command line script on the native OS.

> `execute [wait] [log] “<instruction>”;`

If `wait` is set then the instruction will wait for the execute to complete. If `log` is set then the output of the execute will be logged to the Debug window (and resulting dump file). When `log` is used `wait` should also be used, to avoid overwriting log messages.

### 6.2.11. Log

The `log` instruction logs a message to the Debug window. Log messages can provide information immediately (e.g. a step being made in a script, or a value of some variable) or post-execution as part of the logfile which includes the full content of the Debug window.

> `log (“message” [optional var]);`

### 6.2.12. Message

The `message` instruction opens a dialog with the message and allows the operator to provide feedback and a OK/NOK indication. The feedback plus OK/NOK indication are logged to the Debug window.

> `message (“message text” [optional var]);`

This instruction is useful for semi-automatic testing of user interfaces where the GUI part is done manually using message instructions.

### 6.2.13. Fail

The `fail` instruction fails the execution of the scenario (final result). The execution terminates.

> `fail (“message” [optional var]);`

The `fail` instruction can be useful in combination with an if instruction, for instance when a complex check is executed using javascript.

### 6.2.14. Call

The `call` instruction calls a macro or scenario. The name of the macro/scenario is the filename without extension. Macros must be on the `macropath` as provided in the configuration file. The Macrolist window displays all available macros. Also note that the macro name must be unique throughout all of the available macros because the path is not part of the selection of a macro (just the filename without extension).

> `call <macroname> ([<parametername> => <value>,]*);`

### 6.2.15. Reader

The `reader` instruction allows the creation or deletion of a reader. When the keyword `dispose` is used the reader (if it exists for that topic) will be deleted. When a reader is created the `topicname` is mandatory.

> `reader [dispose] (<topicname> [, <qos> [,<partition> [,<readername>]]]);`

The qos can be provided in short notation (2 or 4 characters):

> `< v | l | t | p >< b | r >[h][<S|E><D|S>`

where

`< v | l | t | p >`
  Volatile, local transient, transient or persistent
`< b | r >`
  Best effort or reliable
`[h]`
  History, for a “keep” of 10 which allows for the reception of 10 samples with the same key in one poll interval
`<S|E>`
  Shared or exclusive ownership
`<D|S>`
  Ordering based on Destination or Source time stamp

## 6.3. Instructions for Graphs

### 6.3.1. Graph

The `graph` instruction allows manipulation or save of the graph. It has the following parameters:

    X
    Y
    Key
    Color
    Title
    xUnits
    yUnits
    save => <name>
    show => true|false
    reset => true|false

Note that all graphs have the same X component; when omitted the X will be the sample time. If the Y parameter is set, then a new trace is created for the current graph. The X, key, color, title and units are used for this trace if provided.

If `reset` is `true`, then the graph is cleared (i.e. all existing traces are deleted) before creating any new trace. If `show` is `true` then the graph is made visible after adding the trace; when `false`, then the graph is hidden after adding the trace. When `save` is `true` the graph will be saved to an image file after the trace has been added.

### 6.3.2. Column

The `column` instruction allows the creation of an extra column from a script for use by the graph instruction.

> `column [clear] (<fieldname> [, <columnname>]);`

When the optional `clear` is set then the column for the field with name `fieldname` will be removed. When `columnname` is omitted, the `columnname` will be the same as the fieldname.

## 6.4. Instructions for Flow Control

### 6.4.1. Wait

The `wait` instruction forces a wait in the execution of the script. The time is provided in seconds.

> `wait (<time in seconds>);`

Value can be a variable.

### 6.4.2. If

The `if` instruction allows conditional execution of instructions.

> `If (val1 <operator> val2) then`

> > `<true instruction list>`

> `[else`

> > `<false instruction list>]`

> `endif;`

Where `<Operator>` is one of `‘==’`, `‘!=’`, `‘>’`, `‘<‘`, `‘>=’`, `‘<=’`, `‘||’`, `‘&&’`.

Expressions can be layered with brackets:

> `((<<x>0) && (<<y>0))`

### 6.4.3. For

The `for` instruction allows the execution of a list of instructions multiple times.

> `for ,<var> in 1 .. 10 loop`

> > `<instruction list which can use <<var>`

> `endloop;`

or

> `for <var> in (a,b,c) loop`

> > `<instruction list which can use <<var>`

> `endloop;`

### 6.4.4. Exit

The `exit` instruction exits the scenario.

> `exit;`

## 6.5. Instructions for the Message Interface

### 6.5.1. Write

The `write` instruction writes a message to the interface.

> `write <interface>.<message> ([<fieldname> => <value>,]*);`

### 6.5.2. Read

The `read` instruction checks a received message from the interface.

> `read <interface>.<message> ([<fieldname> => <value>,]*);`

### 6.5.3. Connect

The `connect` instruction calls the `connect` of the interface. The functionality depends on the implementation in the interface.

> `connect <interface>;`

### 6.5.4. Disconnect

The `disconnect` instruction calls the `disconnect` of the interface. The functionality depends on the implementation in the interface.

> `disconnect <interface>;`

### 6.5.5. Control

The `control` instruction allows the execution of special instructions as provided by the interface.

> `control <interface>.<instruction>[ ([<fieldname> => <value>,]*)];`

## 6.6. Installing Script Engines

In order to use additional script languages the appropriate script engines must be added to the Java `classpath`. The Java JRE already comes with a JavaScript engine by default (i.e. no specific installation is required). More Java script engines are available and can be used to support different scripting languages for the embedded scripts inside the scenario scripts, or for the additional fields.

When Tester starts, the available script engines will be logged (default log file is `/tmp/OSPLTEST.log`).

### 6.6.1. Jython

Download and install Jython on the target machine. Include `jython.jar`, which is normally located in the Jython installation directory, in the `classpath` of the OpenSplice Tester. Use this language by adding the following line as the first line of each script using the Jython script language:

> `#!jython`

### 6.6.2. Jruby

Download and install Jruby on the target machine. Include `jruby.jar`, which is normally located in the `lib` directory in the Jruby installation, in the `classpath` of the OpenSplice Tester. Use this language by adding the following line as the first line of each script using the Jruby script language:

> `#!jruby`

### 6.6.3. Groovy

Download and install Groovy on the target machine. Include `groovy-all-<version>.jar`, which is normally located in the `embeddable` directory in the Groovy installation, in the `classpath` of the OpenSplice Tester. Use this language by adding the following line as the first line of each script using the Groovy script language:

> `#!groovy`

### Navigation

- index
- next |
- previous |
- Tester User Guide »