Understanding variables and their functions in ScenarioBuilder

Learn how to use predefined variables and their functions in ScenarioBuilder.

Variables in ScenarioBuilder can store various data types: strings, numbers, dates, and times. They can also get their values from external data sources, such as Excel or CSV files. Variables can change their values using the appropriate functions. With variables, data input can be varied to emulate real world application usage. This article provides detailed information on working with the variables and their functions with various examples.

Sections

User-defined Variables 

The variable actions can be found under the "Variables" group in the “Actions” list located on the left side of ScenarioBuilder.

Let's learn about variable scope before moving forward.

Variable scope property allows you to provide levels of access to the variables. There are 3 options of variable scope that you can select:

  • Global - The value of the variable will be accessible during all iterations of the scenario execution (useful in ScenarioBuilder, AppLoader, and AppVerify).
  • Script - This is the default scope where the variable will be accessible during one iteration. The value of the variable is accessible from sub-scenarios as well.
  • Internal - This option is to make the variable internal to the scenario and not used in Test cases in AppVerify (useful in AppVerify).

Here is an example of how to use the Global scope.

In this scenario, we want to play a scenario multiple iterations and we want to know the time that the first iteration started.

We have added an "If" statement to check if the current iteration is 1, then we have set a global variable named StartTime.

For the rest of the scenario, we will be able to print the value of StartTime and this same value will also be accessible in the rest of the iterations.

Screenshot_59-2

Results after playing 3 iterations:

Screenshot_61

Set String Variable

Add a string variable to your scenario.

Properties

  • Variable Name – Provide a meaningful name to the variable.
  • Variable Value – Simply type in your value/text entry or use the drop-down menu to select a pre-defined variable. The value of a variable is set when the set variable action is executed.
  • Variable Scope – Specify the level at which you want to access your variable. 
  • Encrypted – Selecting this checkbox will encrypt the variable value for security purposes. This is useful if your variables contain passwords or other sensitive information.
Example - Setting a Value for an emapty variable
Let's say we have a required field in an application. If the value coming from a data source (CSV file - "reason for visit" variable) is empty, then we want to set a default value. Here are the steps to take:
  1. Add an If statement to the script.
  2. Enter %reason for visit% == EMPTY for the Expression property.
  3. Add Set String Variable as a child step.
  4. For the Variable Name property, enter %reason for visit%.
  5. For the Variable Value, enter the data you want the script to use if the “reason for visit” is blank.
                                                      Now when the script executes it will read the value in the CSV for reason for visit. If the value is empty, then it will use the value set by the If statement. To learn more about how to use CSV files, see here.

Set Date Variable

Add a date variable to your scenario.

Properties

  • Variable Name – Provide a meaningful name to the variable.
  • Variable Scope – Specify a level at which you want to access your variable.
  • Date Format – Select a date format. You can select a format from the drop-down, or you can enter your own format. Use the Syntax table below to assist in this effort.

 Syntax

 Description

 d

Single-digit for day (1-9) instead of (01-09)

 dd

 Numeric representation of the day of the month, with leading zeros

 ddd

 Three-letter abbreviation for the day of the week

 dddd

 Full name of the day of the week

 M

Single-digit for month (1-9) instead of (01-09)

 MM

 Numeric representation of the month, with leading zeros

 MMM

 Three-letter abbreviation for the name of the month

 MMMM

 Full name of the month

 yy

 Year represented by only the last two digits

 yyyy

 Year represented by all four digits

 weekday

Day of the week as an integer (Mon = 1, Tue = 2, … Sun = 7)

 yearday

Day of the year as an integer (1-366)

 yearweek

Week of the year as an integer (1-53)

  • Variable Value – Provide a value for the variable based on the date format or your own format using the syntaxes associated with it. If you leave this field blank the date will be set to the current date. The value of a variable is set when the set variable action is executed.

Set Time Variable

Add a time variable to your scenario.

Properties

  • Variable Name – Provide a meaningful name to the variable.
  • Variable Scope – Specify a level at which you want to access your variable. 
  • Time Format – Select a Time format. You can select a format from the drop-down, or you can enter your own format. Use the Syntax table below to assist in this effort.

 Syntax

 Description

 h

Single-digit for hour (1-9) instead of (01-09) in (12-hour clock)

 hh

 Hours with leading zeros (12-hour clock)

 H

Single-digit for hour (1-9) instead of (01-09) in (24-hour clock)

 HH

 Hours with leading zeros (24-hour clock)

 m

Single-digit for minute (1-9) instead of (01-09)

 mm

 Minutes with leading zeros

 s

Single-digit for second (1-9) instead of (01-09)

 ss

 Seconds with leading zeros

 tt

 Multicharacter time-marker string (for example, "AM" and "PM")

  • Variable Value – Provide a value for the variable based on the Time format or your own format using the syntaxes associated with it. If you leave this field blank the time will be set to the current time. The value of a variable is set when the set variable action is executed.

Set Number Variable

Add a number variable to your scenario.

Properties

  • Variable Name – Provide a meaningful name to the variable.
  • Variable Scope – Specify a level at which you want to access your variable. 
  • Variable Value – Enter your variable value or use the drop-down menu to select a random number range [Low-High]. Replace the first number with the lowest number to use and the second number with the highest number to use (i.e. [1-10] Random Number). The value of a variable is set when the set variable action is executed.
  • Number of Decimals – Specify the number of decimal places that you want to use.
  • Decimals Separator – Enter a character to separate the integer part from the fractional part of a number written in decimal form (comma, period, space, etc.). By default, ScenarioBuilder uses period (.) character.
  • Thousands Separator – Enter a character to separate the integer part from the fractional part of a number written in decimal form. (comma, period, space, etc.)
  • Currency Symbol – Enter a symbol if you want to display numbers as monetary values. The currency symbol appears right next to the first digit. ($)
  • Negative Symbol – Enter a symbol you want to use for negative numbers. The number can be displayed with parentheses, braces, brackets around it.

Example 1 - Set a negative number

Screenshot_50-3

Properties:

Screenshot_53-3

Results:

Screenshot_48-2

 

Example 1 - Set a random number

Let's say we want to loop a set of steps a random number of times, so we need to create a variable that contains a randomly generated value. Here are the steps to take:

  1. Add Set Number Variable onto your script.
  2. In the Variable Name property, enter a name for the random value.
  3. In the Variable Value drop-down, select [30-47] Random Number.
  4. Change the 30 to represent the least number of times you want to iterate through your loop.
  5. Change the 47 to represent the greatest number of times you want to iterate through your loop.
  6. For your Loop step, in the Iterations property, enter the name you created in step 2 surrounded by % (i.e. %randomnumber%).

Each time the script is executed the loop will use a randomly generated number using the range you set in steps 4 and 5.


Set Image Variable

Add an image variable to your scenario.

Properties

  • Variable Name – Provide a meaningful name to the variable. For example, OKButton.
  • Variable Value – Right click on this field to show the dropdown menu and select an existing image or take a new one. Use [ESC] key to cancel.

Example:

Screenshot_65-2


Variable Functions

ScenarioBuilder offers various functions for variables to help you process information.

String Functions

ScenarioBuilder has strong text handling capabilities. Read below to understand the string functions that are available for manipulating text strings.

Properties

  • Variable Name – Provide a meaningful name to the variable.
  • Function – Select one of the above listed functions from the drop-down list.
    • FirstCapital – Returns text with the first letter of each word capitalized.
    • Split – Splits text into a list of values by separating the text at specified delimiter. You can get the values out of the list by entering the following syntax: variable name[index]. The list values' indices start at 1 and increment by 1, so the first value's index is 1, the second value's index is 2, etc. 
    • ToLowerCase – Returns text converted to all lowercase (non-capital) letters.
    • ToUpperCase – Returns text converted to all uppercase (capital) letters.
    • Trim – Removes whitespace or tab characters from the beginning and end of the source text value.
    • Truncate – Shortens text down to the number of characters defined in Truncate Size.
    • ValueIn – Updates the value of the variable by getting the value of another variable that has the same name as the current value.
  • Split Delimiter – When using the Split function, enter the character that is used to separate the values (comma, period, space, pipe, etc.)
  • Reg Expression – Use a regular expression to read the execution results. For example, for ping www.automai.com, expression #output# will place what the command returns in the variable output, and expression sent = #sent# will place what is between =space and comma in the SENT variable.
  • Continue On Failure – If Checked the execution of the scenario will continue.

Example 1 - Split function

Screenshot_37-Jun-26-2020-07-15-04-31-PM

Screenshot_39-Jun-26-2020-07-16-17-11-PM

Result:

Screenshot_40-2

 

Example 2 - Truncate function

Screenshot_41-Jun-26-2020-07-21-12-65-PM

Result:

Screenshot_45-3

 

Example 3 - ValueIn function

Let's say we have a variable that has value of "A,B,C,D". We need to go through the value, process each entry and see if it's empty or not. Here are the steps to take using Loop action and ValueIn function:

    Screenshot_70-3

    Now when the script is executed, each value of the variable will be displayed in a dialog box.

    Here is the sample scenario if you want to give it a try.


    Date Functions

    Read below to understand how to use and manipulate values representing dates.

    Properties

    • Variable Name - Enter the name of the variable you wish to manipulate (the "Set Date Variable" action must precede this step, establishing the variable to be used).
    • Function – Select one of the above listed functions from the drop-down list.
      • AddDays – Adds a number of days to a date.
      • AddMonths – Adds a number of months to a date.
      • AddYears – Adds a number of years to a date.
      • Format – Returns a formatted value as defined by the Date format property.
      • LastDayOfTheMonth – Returns the last day of a month, considering leap years too.
      • SubtractDays – Subtracts a number of days from a date.
      • SubtractMonths – Subtracts a number of months from a date.
      • SubtractYears – Subtracts a number of years from a date.
    • Add/Subtract Value – Enter a value you want to add to or subtract from the variable value.
    • Date Format – Select a Date format.
    • Continue On Failure – If Checked the execution of the scenario will continue.

    Example 1 - Determine the last day of the month

    Let's say we need to test that an application behaves correctly when the report date falls on the last day of the current month. Because the last day of the month varies, we need to calculate what the last day is each time the script is executed. Here are the steps to take:

    1. Add Set Date Variable into the script.
    2. Enter “LastDayofMonth” for the Variable Name property.
    3. Leave the Variable Value property blank. This will set it to today’s date.
    4. Add Date Functions into the script.
    5. In the Variable Name property, enter %LastDayofMonth%.
    6. In the Function drop-down, select LastDayOfTheMonth.

    Now when you use the “LastDayofMonth” variable, it will enter the last day of the month corresponding to the current month.

     

    Example 2 - Change the Date format to the day of the week

    Let's say we need to make a day of the week selection in an application based on the current date (Sunday, Monday, Tuesday, etc.). We can pull out the day of the week from today's date to accomplish this. Here are the steps to take:

    1. Add Set Date Variable action to the script.
    2. Set the Variable Name property to a name of your choosing (e.g. today).
    3. Leave the Variable Value property blank so it will default to today's date.
    4. Add Date Functions action to the script after the Set Date Variable you added in step 1.
    5. In the Variables Name property, enter the name of the date variable you set in step 2.
    6. For the Function property, select Format from the drop-down.
    7. In the Date Format property, select "dddd" from the drop-down.

    Now when the script is executed, the %today% variable will be the day of the week based on today's date.


    Time Functions

    Read below to understand how to use and manipulate values representing times.

    Properties

    • Variable Name – Enter the name of the variable you wish to manipulate (the "Set Time Variable" action must precede this step, establishing the variable to be used).
    • Function – Select one of the above listed functions from the drop-down list.
      • AddHours – Adds a number of hours to a time.
      • AddMinutes – Adds a number of minutes to a time.
      • AddSeconds – Adds a number of seconds to a time.
      • Format – Returns a formatted value as defined by Time format.
      • SubtractHours – Subtracts a number of hours from a time.
      • SubtractMinutes – Subtracts a number of minutes from a time.
      • SubtractSeconds – Subtracts a number of seconds from a time.
    • Add/Subtract Value – Enter a value you want to add to or subtract from the variable value.
    • Time Format – Select a Time format from the drop-down or enter your own.
    • Continue On Failure – If Checked the execution of the scenario will continue.

    Example - Setting the Time to 1 hour from current time

    We are working with an application that creates products with short lifespans. When we create the product, we need to set the expiration date to 60 minutes from the current time. Obviously, this will change based on the time when the script is executed. Here are the steps to do that:

    1. Add Set Time Variable into the script.
    2. Enter “ExpirationTime” for the Variable Name property.
    3. Leave the Variable Value property blank. This will set it to the current time.
    4. Add Time Functions onto your script.
    5. In the Variable Name property, enter %ExpirationTime%.
    6. In the Function property drop-down, select AddHours.
    7. In the Add/Subtract Value property enter “1”. This will add 1 hour to the current time.

    Now when the ExpirationTime variable is used in the script, it will be a time that is 1 hour ahead of the current time.


    Increment a Variable

    Use this action when you want to increase a variable value by a specified amount.

    Properties

    • Variable Name – Enter the name of the variable you wish to increment (the “Set A Variable” action must precede this step, establishing the variable to be incremented).
    • Increment Value – Enter the value that you wish to increment the entered variable by.

    Example - Automatically number elements in a file 

    Let's say we have a text file that is created during script execution. As new items are added to the file, we want it to number them automatically. Here are the steps to take:

    1. Add Set Number Variable to the script.
    2. Enter a name in the Variable Name property.
    3. In the Variable Value property, enter 1. This will start our numbering at 1.
    4. Add the variable to the text that is written to the file (i.e. %num% - this is what happened…)
    5. After each step that writes to the text file, add an Increment A Variable action.
    6. In the Variable Name property enter the name you used for step 2. Remember to enclose it in % (i.e. %num%).
    7. In the Variable Increment property, enter 1. This will increase the value of the variable by 1.

    Screenshot_63-4

    Now the items written to the text file can be numbered 1, 2, 3, etc.


    Load an Image Into a Variable

    If you have a changing image that needs to be used for an action, have ScenarioBuilder capture the image during execution, and them pass that on as a variable value to the step that needs to use it.

    Properties

    • Variable Name – This is the variable where the text is stored.
    • Use Anchor – If enabled, mouse location is relative to the parent Image or Window Action (property is only relevant if the “Mouse Move” Action is a child of either an Image or Window Action).
    • Image area – Click the ellipses to use your mouse to select the area from which to capture text. Capture only the desired image. NOTE – the “Start” and “End” Text Area “X” and “Y” property fields will automatically populate after you make your selection. To remove the “Image Area” settings, click the X.
      • Start Image area X – Image area coordinates upper left corner X
      • End Image area X – Image area coordinates lower right corner X
      • Start Image area Y – Image area coordinates upper left corner Y
      • End Image area Y – Image area coordinates lower right corner Y
    • Scenario Section – This is for Global scenarios only. Specify the section name that can be called from other scenarios.

    Example - Dynamic Application Buttons

    Let's say we want to test the action buttons change based on the record selected (includes the patient name) inan application. To handle this, after loading the record Iwe will capture the button and save it as a variable. That allows us to use the image in a Find Image or Click on Image action. Here are the steps to take:

    1. In the script after you access the record you are going to work with, add Load an Image Into a Variable action into the script.
    2. Enter a name for the variable into the Variable Name property.
    3. Click the ellipse button for the Image area property and drag the mouse over the button to select the area it should capture.
    4. Add a Click on Image action below the Load an Image Into a Variable step.
    5. For the find Image #1 property, right click on No image data and select Choose a Variable from the menu. The Select Variable window opens.
    6. Open the Variable name drop-down and select the variable name used for step 2.

    Now when the script runs it will click on the button matching the image captured in the Load an Image Into a Variable step.

    For more about the Load an Image Into a Variable action, please check out “Load Image As Variable” in our Video Tutorials series.