Variables & Expressions

Overview

When defining a test, many of the operation parameters or arguments can be defined either as a constant value, or as an expression. An expression will typically contain variables. There are three main categories of variables.

• User Variables stored in $v (available throughout a test run).
• Inbound Operation Variables stored in $i (allows test logic to access inbound data).
• Global Variables stored in $g (common across all test instances in a test run).

Tests can initialise user variables to fixed or randomly-assigned values at the start of each test instance.

Variables can be used as part of an Expression to specify most parameters of most test operations. Note that some operation parameters always expect an expression. Other parameters will accept an expression if the parameter is contained in curly braces { –expression – }.

Note: For parameters which may be an expression, if you wish to specify a constant value which actually begins with a curly brace and not have it evaluated as an expression, then you must escape the first character. Specify { for the first character, it will be interpreted as {, and no expression evaluation will be performed.

Refer to the subsequent documentation for each operation to identify which operation parameters may be given as an expression, which are always expressions, and which accept only constant values.

Using Variables

Basic user variables are stored within a Perl object named $v. User operations can define these variables and use them within test operations.

Here is an example sequence of test operations consisting of an eval operation which sets a variable named cause to value 23, followed by an inap.ssp_from_scp.ReleaseCall (INAP Expect ReleaseCall) operation which uses that variable.

Note that the expression attribute of an eval operation is always treated as an expression to be evaluated. However, the initialCallSegment_cause argument needs to be wrapped in curly braces in order to request expression evaluation.

"operations": [
    {
        "type": "eval",
        "expression": "$v->{cause} = 23"
    },
    {
        "type": "inap.ssp_from_scp.ReleaseCall",
        "arguments" : {
            "initialCallSegment_cause": "{$v->{cause}}"
        }
    }
]

The expressions may be any valid Perl expression. The standard Perl operators and functions are available. An invalid expression will cause the script execution to end with an error.

Note that long-running expressions should be avoided, as they will interfere with the execution of other scripts.

Inbound Variables

As well as the variables defined by users in $v, the test script itself will also store inbound received values to make them available to other operations. These inbound variables are stored in $i.

For example, the following sequence of test operations will expect an inbound ReleaseCall operation, and then will apply an assert operation to check that the inbound values are correct.

"operations": [
    {
        "type": "inap.ssp_from_scp.ReleaseCall"
    },
    {
        "type": "assert",
        "expression": "$i->{ReleaseCall}{initialCallSegment_cause} > 22",
        "abort": "{'Bad ' . $i->{ReleaseCall}{initialCallSegment_cause} . ', <= 22.'}",
        "pass": "{'OK ' . $i->{ReleaseCall}{initialCallSegment_cause} . ', > 22.'}",
    }
]

Note that the assert operation automatically assumes that its expression parameter is an expression. But its abort and pass parameters require curly brackets to be treated as expressions (by default they are assumed to be constants).

Global Variables

Finally, your Test can store values in global variables in $g. There are two reasons to use a global variable rather than a standard $v variable.

Firstly, all global variables will be returned back to the client at the conclusion of the test run. These are passed back in the globals attribute in the result of the QueryTest JSON RPC method of the test management interface.

Secondly, the $g variable is common to all test instances in a test run. This becomes relevant when performing load tests which have more than one test instance performed within a single test run.

The following sequence of test operations will record a bucket count of each individual received initialCallSegment_cause value in a test run.

"operations": [
    {
        "type": "inap.ssp_from_scp.ReleaseCall"
    },
    {
        "type": "eval",
        "expression": "$g->{$i->{ReleaseCall}{initialCallSegment_cause}}++"
    }
]

At the end of a test run which performed ten test instances, the following may be returned in the result back to QueryTest, indicating that the cause 31 was returned in 8 instances, and the cause 22 was returned in two instances.

    ...
    "globals": {
        "22": "2",
        "31": "8"
    },
    ...

Initialising Variables

Variables may be be given initialisation values at the start of each test instance definition in the ExecuteTest JSON-RPC method. This is done via the vars parameter as listed in the ExecuteTest method definition.

The vars parameter is an object defining one or more variable initialisations, as per the following example:

"vars": {
    "tn": "0800111111",
    "cause7": 45,
    "var_7b": null,
    "cause": 23,
    "cli": "414511860",
    "details": {
        "timer": 43
    }
}

When each test instance is initialised, it is given a private copy of the vars structure which it may then reference as $v within any expressions that it evaluates. An expression is a Perl language expression.

Some operation parameters are always evaluated as expressions. Other parameters support optional expression evaluation, in which case you indicate that expression evalulation is required by wrapping the operation parameter in curly braces, e.g. { $v->{cli} }.

Refer to the documentation for each individual operation to determine which operation parameters allow expression evaluation, which always use expression evaluation, and which do not allow expression evaluation at all.