TestSmith Variables

Overview
Explicit Variables
Explicit Variable Assignment
Implicit Variables
Testing Variable Values
Using Variable Values
Special System Values




Overview

There are essentially two different kinds of TestSmith variables:
  • Explicit Variables - these variables are declared with a SET DECLARE_STR or a SET DECLARE_INT directive
  • Implicit Variables - these are the 'in-out' parameters, set by the TestSmith commands. and the three error variables: errlast, errworst and errcount.
Additionally, there are seven special system values which are set by the TestSmith playback engine. These are values only, not variables and as such cannot be used as the left-hand operand in a _doif statement.


Explicit Variables

Explicit variables are declared with either a SET DECLARE_STR=[varName][...]; directive or a SET DECLARE_INT=[varName][...]; directive, for string and integer variables, respectively. Each variable name must be encased in square brackets. The variable name can optionally be preceded by the keyword const e.g. SET DECLARE_STR=[const varName];. In such cases the first assignment of a value to that variable cannot be overwritten: it is permanent for the life of the script. All characters outside the square brackets are ignored, thus each variable can come with a description using a form similar to the following:
DECLARE='First Name: [firstname], Date of Birth: [dob]'

Important Notes
If a DECLARE_STR or DECLARE_INT value string contains spaces - as in the above example - they must be enclosed between 'single quotes'. Variable names must begin with an alpha character and can only contain alpha-numeric characters or the underscore '_' character; there is no length restriction enforced. Variable names are case-sensitive. Variable names will be disallowed if
  • the name is the same as a column name from a .csv file
  • name is a reserved TestSmith command or parameter name
  • the name is already used for another variable
If any of these are attempted an error will be issued and the script will not run. String variables will default to an empty string and integer variables will default to 0 (zero). Variable values should be set with a setVar command. If the variable is defined as const the value can only be set once, otherwise the value can be changed at any time.

For backward compatibility with v1.2.0 scripts the simple SET DECLARE directive is still supported, but is now deprecated.

For backward compatibility with pre-v1.2.0 scripts nine variables with predefined names are always implicitly declared. These variables also have a predefined type, suggested by the name.

  • str1, str2, str3, str4, int1, int2, int3, int4, counter

    The value of explicit variables must be set using the setVar command.
    All variables can be tested and used in the script they are defined in and any sub-script that is called, directly or indirectly, from that script.


    Explicit Variable Assignment

    Variable values can be set new or can be changed through the use of various assignment operators. The assignment operator is an essential part of the syntax and must always be used.

    Integer variables use the assignment operators:
  • =+ (add)
  • =- (subtract)
  • =* (multiply)
  • =/ (divide)
  • =: (set/reset)
    Any value assigned to an integer variable that does not resolve to an actual whole number will be read as 0.

    String variables use the assignment operators:
  • =+ (concatenate)
  • =@ (insert at start)
  • =- (remove sub-string)
  • =: (set/reset)
    The formal syntax for setting variables is:
  • {variable-name}{=}{assignment-operator}{value}

    Examples of use, assuming the following SET directives:
    SET DECLARE_INT=[myNumber][yourNumber][regValue][timeNow] ;
    SET DECLARE_STR=[myText][valText][fileText] ;
    1. setVar myNumber=:100 yourNumber=:-2 myText=:Some%--Text ;
    2. setVar myNumber=+50 yourNumber=*10 myText=+%cm%--More%--Text ;
    3. setVar myNumber=/75 yourNumber=:0 myText-=Some%--Text%cm%--More%-- ;
    4. valEditText id=1 [...] vtext~=, ;
      setVar valText=:{vtext} ;
    5. fRead d:\file1 ;
      setVar fileText=:{ftext} ;
    6. fRead d:\file2 ;
      setVar fileText=@{ftext} ;
    7. regRead [...] rtype=int ;
      setVar regValue=:{rdata} ;
    8. reportTime ;
      setVar timeNow=:{elapsed} ;
    9. setVar myNumber=:1.5 ;
    After the first setVar command myNumber will have the value 100, yourNumber will have the value -2 and myText will have the value "Some Text".
    After the second setVar command myNumber will have the value 150, yourNumber will have the value -20 and myText will have the value "Some Text, More Text".
    After the third setVar command myNumber will have the value 2, yourNumber will have the value 0 and myText will have the value "Text".
    In example 4, valText will be set with the text read in from the specified Edit control. The use of vtext~=, will ensure the command will return an OK result, allowing the variable to be set.
    In example 5, fileText will be set with the text read from file1.
    In example 6, fileText will have the text read from file2 added before its existing value. Thus if file1 contained "line-one" and file2 contained "1:" then fileText will contain "1:line-one".
    In example 7, regValue will contain the integer value read in from the specified registry key. Note the rtype=int parameter. If this is not set the value is assumed to be a string, and any integer variable will be set to 0.
    In example 8, timeNow will be set with the number of milliseconds that have elapsed since the script started running, or since the timer was last reset.
    In example 9, myNumber will be set to 0, as the value "1.5" does not resolve to an actual integer value.


    Implicit Variables

    Implicit variables are command parameters that have in-out, or out-only behaviour, i.e. they have values implied by the result of the command they belong to after the command has executed. The new values can then be read into a TestSmith variable using the syntax setVar=[operator]{out-param}.
    Examples:
    setVar strVar1=:{hvistext} ;
    setVar totalTime=+{elapsed} ;
    These parameters/variables can also be tested and used in the exactly the same way as explicit variables.

    The following 19 command parameters have in-out behaviour. This means they are sent in to a command with a value (often a fuzzy value) and they come out with either the same or a different value, depending on the result of the command. These 3 parameters have out-only behaviour. They do do have to be passed in to the command they belong to; they are implicitly set in either case. In the following examples, both commands are correct. The former is preferred.
    fRead file=d:\temp.txt ;
    fRead file=d:\temp.txt ftext=: ;
    The following command will show the contents of d:\temp.txt, regardless of which version of fRead was used.
    noop remark={ftext} ;

    Extracting values from commands this way replaces the pre-v1.3.0 way of doing it, where additional variables had to be specified as parameters, and only a limited set of data could be extracted, (e.g. just hvistext from html commands). Scripts containing the older syntax will still work but should be updated to the new syntax before version 1.4 of TestSmith, when the older method will no longer be supported.


    Testing Variable Values

    Variable values can be tested as part of a _doif statement. Comparison operators are used to determine the type of test. The comparison operator character is an essential part of the syntax and must always be used.

    Integer variables use the comparison operators:
  • =< (less-than-or-equal-to)
  • => (greater-than-or-equal-to)
  • == (exactly-equal)
  • =! (not-equal)
  • =r (within-range)
    The special variables errlast, errworst and errcount (which are set implicitly by the playback script) are also treated as integer variables and can be tested in the same way.

    String variables use the comparison operators:
  • =< (the value of the variable is a sub-string of the given value)
  • => (the given value is a sub-string of the value of the variable)
  • == (the value of the variable is identical to the given value)
  • =! (the value of the variable is not identical to the given value)

    String variables may also use an additional qualifier, at the end of the value:
  • `i (ignore-case)

    The formal syntax for comparing variables is:
  • {variable-name}{=}{comparison-operator}{value}{[`i]}

    When the 'r' operator is used the {value} part for the integer variable must be of the format
    {{low-value}..{high-value}}.

    To compare to an empty string use the following syntax (assuming textVar is a vaild variable name):
    textVar==%00 or textVar=!%00.
    The syntax textVar== or textVar=! is also acceptable, but its intent is less clear.
    The syntax textVar=='' or textVar=!'' is not acceptable.

    Examples of use, assuming the following SET directives:
    SET DECLARE_INT=[myNumber][yourNumber][otherNumber] ;
    SET DECLARE_STR=[myText] ;

    Given the assignments:
  • setVar myNumber=:100 yourNumber=:5 otherNumber=:9 myText=:George%--Jones ;
    and assuming no error has yet occurred in the script, the following _doif statements will all evaluate to TRUE.
    1. _doif myNumber==100 myText=='George Jones' ;
    2. _doif myNumber=!200 myText=!'Tom Jones' ;
    3. _doif yourNumber=>5 otherNumber=<9 ;
    4. _doif myNumber=r99..101 ;
    5. _doif myText=<'THE GEORGE JONES COLLECTION`i' ;
    6. _doif myText=>George ;
    7. _doif errlast==0 errworst==0 ;

    Using Variable Values

    All the variables can be used anywhere in a script where literal values are usually used. The format for use is the same as with data-substitution, i.e. surrounding the variable name with curly brackets. (See also Data Driven Tests.)

    Given the assignments:
  • setVar textVar1=:'meaningless text' ;
  • setVar textVar2=:'meaningless text' ;

    The command
  • kbText id=1 ktext='This is {textVar1}.' ;
    would type the text "This is meaningless text." to the window specified by id=1, and the statement
  • _doif textVar1=={textVar2} ;
    would evaluate to true.


    Special System Values
    These seven values are set by the TestSmith playback engine and can be used in the same vay that variable values can be used, surrounded by curly brackets. The Values resolve as follows:
    • {_SCRIPT_} The name of the script, excluding path and suffix
    • {_SCRIPTPATH_} The full path name of the script, including suffix.
    • {_ROOTDIR_} The root directory. This is the directory where the TestSmith executable resides, unless a new directory was set with a SET ROOTDIR directive.
    • {_LINE_} The line number in the script of the start of the currently executing command.
    • {_COMMAND_} The command number of the currently executing command.
    • {_OPSYS_} The name of the Operating System. It will be one of:
      • "Windows 2000"
      • "Windows Server 2003"
      • "Windows XP"
      • "Windows NT 4"
      • "Windows Win32" (for Windows 95/98/ME)
    • {_COUNT_} The script repeat number. Always 1 unless multiple repeats of the script were specified with the SET REPEAT directive.