TSL General and Coding Standards

1. Script and Script Artifact(s) Standards
Before the user starts creating scripts and using the software, they will need to be familiar with the standards applied to scripts and their associated artifacts. This will include use, naming, and storage of these artifacts. Artifacts can include GUI maps, data files, result sets, stored queries, etc. The details for each of these can be found in the following sections of this chapter.
1.1 Script Conventions
The section contains the standards related specifically to the automated test scripts.
1.1.1 Script Naming Conventions
Scripts will be named using context naming with “CamelBack” style. The name will be made up of an acronym that represents the application under test, plus a security level, plus a functional description of what the script does. Below is a list of some standard names as they have been used to this point. Ordering of the components making up the name is relevant. Please adhere as closely as possible to the below examples.
Script Naming Conventions
Security Level
Functional Level
Resulting Name
Admin
AddSoftwareTitle
ISIAdminAddSoftwareTitle
Admin
MainPageValidation
ISIAdminMainPageValidation
User
AdvancedSerch
ISIUserAdvancedSearch
User
MainPageFieldValidation
ISIUserMainPageFieldValidation
User
MainPageExceptions
ISIUserMainPageExeception
User
MainPageFieldValidation
ISIUserMainPageFieldValidation

ControlScript
ISIControlScript

1.1.2 Script Storage
Scripts will be stored in a folder, named for each project under a parent folder named “Projects”. The folder for individual projects will be a subdirectory of the WinRunner\Projects\ folder and named for the project it represents. Scripts will be stored inside this directory using the naming standards listed in the preceding section.
An example storage location of a script for the ISInventory Project would be:
C:\Program Files\Mercury Interactive\WinRunner\Projects\ISInventory\AdminAddSoftwareTitle
An example of both the storage location and the naming convention of a control script for the ISInventory Project would be:
C:\Program Files\Mercury Interactive\WinRunner\Projects\ISInventory\ISInventoryControlScript
1.2 Script Artifact Conventions
The section contains the conventions used for the artifacts and files associated with automated test scripts.
1.2.1 Script Data Files
Scripts will often require the use of files for reading and storing of data. There will be two types of data files used in automated scripting, flat files or Excel tables. Both types of files will be stored in the home directory of the script using the following naming conventions.
Flat File Naming Convention: data.txt
Excel Table Naming Convention: default.xls
NOTE – The above names are default names. If multiple data files are required for a script, descriptive naming with CamelBack style should be used to distinguish what each file contains.
An example storage location of a data file for the AdminAddSoftwareTitle script of the ISInventory Project would be:
C:\Program Files\Mercury Interactive\WinRunner\Projects\ISInventory\AdminAddSoftwareTitle\data.txt
1.2.2 Script GUI Maps
WinRunner requires GUI Maps to identify the objects it works with. There will be one GUI Map created per project and it will be named after the project with the added extension of “.gui” (default extension used by WinRunner). It too will be stored in the home directory of the project.
An example of both the storage location and the naming convention of a GUI Map for the ISInventory Project would be:
C:\Program Files\Mercury Interactive\WinRunner\Projects\ISInventory\ISInventory.gui
1.3 Script Architecture Conventions
Scripts will use a standard architecture. This architecture is constructed of three separate pieces consisting of a control level, a business scenario level, and driver level. Details on each of these architectural levels can be found in the following sections.
1.3.1 Control Level Scripts
The control script is the top-level script. It is used to setup the environment and call the scripts that execute the business scenarios or use cases. It will include declaration of global variables, the opening of GUI Maps for the project, initialization of the test environment (development, staging, or production), calls to configuration scripts, starting the Application Under Test (AUT) and navigation to the starting point or point of initiation, as well as making calls to the second level architecture scripts which exercise the business scenarios. This script will typically be a single script and be named using an acronym for the project joined with the words “ControlScript” using a camel back style. An example of control script naming would be:
SRSControlScript
1.3.2 Business Scenario or Use Case Level Scripts
The second level of the script architecture, are scripts that execute business scenarios or use cases. These scripts are merely the ordering and calling of driver scripts to complete a functional business scenario or a use case. The scripts at this level do not actually do any testing inside them but instead determine the order of calling driver scripts to complete the business scenario. The naming of these scripts shall always start with “UC” joined to a descriptive name of what business it does or named after the use case it exercises. An example of business scenario script naming would be:
UCAddNewCustomer
1.3.3 Driver Level Scripts
The third level of the script architecture, are scripts that execute the functionality of each window. These typically put data into the system but are limited to a specific window or entering of specific business data. These scripts must be built as generically as possible to support the differences of what actions can take place for any given window. Driver level scripts shall start with an acronym for the project joined by a descriptive name of the functionality it exercises or the window it represents. An example of business scenario script naming would be:
SRSRequestNewSoftware
2. TSL Coding Standards
The standards related directly to coding and the coding language can be found in the sections of this chapter.
2.1 Script Layout and Readability Conventions
The following standards are related to the overall layout of the TSL test scripts. It is intended to improve consistency and readability of the scripts.
2.1.1 Script Header Conventions
Script headers are a mandatory element of all TSL scripts. The header is intended to provide a definition and understanding of its purpose, who authored the script, date it was created, revision history, etc. Listed below are the elements that are mandatory for the script header at Devon Energy. Script headers will use the “#” sign to frame them. An example of a script header will follow this list.
ü The name of the script
ü A description of what the script does.
ü The author of the script.
ü The date the script was originally created.
ü Pre-conditions for the script.
ü Post-conditions of the script.
ü Name, description, and location of the data files local to the script.
ü A detailed revision history including who, what, and when.
v Parameters passed to the script.
v Parameters returned from the script.
NOTE – Items denoted with a check mark are mandatory
################################################################################## Script Name: SRControlScript## Description: This is the control script for the Software Request System.# It performs all the fucntions of a control script as defined# in the WinRunner Standards Test Guidelines document. It # initialize the environment, global variables, configuration,# and calling the use cases to be exercised.## Author: Rusty Riggs# Date: 4/22/2002## Pre-conditions: Base environment, access to the Software Request System. ## Post-conditions: Regression of the Software Request System base functionality.## Data Files: None at this level.# ################################################################################# Parameters and Variables List################################################################################## Global Variables: varNewRequestNumber
# In Parameters: None
# Out Parameters: None################################################################################## Revision History################################################################################## Date: MM/DD/YYYY
# Revised By: Details of the revision go here.#################################################################################
2.1.2 Script Body Conventions
The script body is all script lines below the header. The body of the script is further divided into functional sections (also see “Script Section Comments” under the “Comments Usage Conventions” in this document). The standards below are to increase both consistency and readability of the scripts. There are several standards that pertain to the script body and can be found below.
ü Script body will be divided into functional sections with a blank line before each section.
ü Multiple set_window statements within a functional section must be proceeded with a blank line. NOTE – set_window statements usually indicate a separate functional section is needed.
ü Each functional section should contain a tsl_step function to improve test results reporting.
ü Indent all looping and branching.
ü Braces shall be at the beginning of the line and lined up according to the indentation they belong to.
ü Always use braces for “if” and “else” statements, even if they are single statement clauses.
ü There will be only one statement per line.
ü Parameters for TSL functions should always use the name instead of the number for the parameter.
ü Use tsl_step functions to report pass/fail conditions for each section in a script.
2.2 Variable Conventions
2.2.1 Variable Naming Conventions
Variable naming will adhere as closely as possible to the standards established by the web development team. These standards can be found at: http://dev.home.devon/it/webdev/NamingConventions.cfm
Since these standards were developed for web development, all may not apply and there may be some additions. Because of that, the standards used for variable naming in TSL will be listed below.
Variable Naming Conventions
Variable Type
Prefix
Example
Array
Arr
ArrEmployeeNames
Boolean
Bln
BlnValidated
Byte
Byt
BytColor
Constants
Con
ConExchangeRate
Currency
Cur
CurAmount
Data or time
Dtm
DtmBirthday
Error
Err
ErrInvalidName
Integer
Int
IntCount
Long
Lng
LngWidth
Object
Obj
ObjRecordSet
Query
Qry
QryEmployees
Single
Sng
SngHeight
String
Str
StrName
Variant
Var
VarNumber
Window
Win
WinName

2.2.2 Variable Declaration Conventions
All global variables will be declared at the top of a script immediately following the script header. Variables used as parameters passed to or from (in or out) functions or called tests must also be declared at the top of the script immediately following the list of global variables. Variables that are local to the script can be declared at the time of use. All variables shall have descriptive comments added following the standards establish for commenting variables.
2.3 Function Conventions
Rules applying to functions in WinRunner are mandated by its design and are available in the online help. These rules are to be accepted as the standards for functions. Any standards listed below either are additional standards or override the WinRunner standards.
2.3.1 Function Naming Conventions
The naming of user defined functions will follow the general naming style applied in this document. The name shall be proceeded with “func” plus a descriptive name using the camel back convention. An example of a TSL statement would be:
funcSRSConfiguration();
2.3.2 Function Parameters and Called Test Parameters Conventions
All parameters passed to or returned from a function must be declared and commented at the top of the script below the script header and immediately proceeding after the variable declarations. They must also contain the type of “in” or “out” when used in the function to improve on readability. This standard applies to parameters passed to or returned from called scripts as well. Comments of function parameters should adhere to the standards listed under the Comment Usage Conventions of this document.
funcSRSConfiguration(in varBaseEnv, out varTRS);
or
call_close “SRSNewSoftwareRequest”(in varApplication, out varTRS);
2.4 Operator Usage Conventions
Operators should be sandwiched between spaces to improve readability of scripts. An example of operator sandwiching would be:
if(varRowCount !> varInitialRowCount)
2.5 Statement(s) Usage Conventions
In TSL, any expression followed by a semicolon is a statement. Only one statement should exist on a single line. Statements can continue beyond one line but is discourage unless it is really needed. An example of a TSL statement would be:
set_window(“My Software Requests – IS Inventory”, 30);
2.6 Comment Usage Conventions
Adding comments to scripts is mandatory. The conventions listed below must be strictly adhered to. Comments are one of the most important elements within a script. Good and consistent commenting facilitates easy transfer of knowledge and understanding of what a script is doing. Comments found in a script combined with the information contained in the script header should build a complete understanding of what the script is for and what each part of the script is intended to do. Make sure that comments explain the code and not just repeat it.
NOTE - In the samples provided below the color coding that is provided in the WinRunner interface is provided for clarity.
2.6.1 Script Section Comments
It is mandatory to add comments to subdivide sections of a test script. The comment should communicate what part of the use case specification it exercises or what that section of the script is doing.. An example of a section comment would be:
# Use Case Specification 1.2.1 – Add a Customer Record
statement_1;
statement_2;
2.6.2 Variable Declaration Comments
It is mandatory to add comments to all variable declarations. The comment should communicate what data gets assigned to that variable in the script. An example of a global declaration would be:
Public varNewRecordNumber; # Holds the value of the newly created record.
2.6.3 Array Declaration Comments
It is mandatory to add comments to all array declarations. The comment should communicate what data gets assigned to that array in the script. An example of a global array declaration would be:
Public arrCustomerInformation [I]; # Holds the name, address, and phone number of the customers.
2.6.4 Conditional Branching Comments
It is mandatory to add comments to all conditions or conditional branching. The comment should communicate what condition is checking for. An example of a if condition would be:
if(varRowsCount > varInitialRowsCount) # Checks to see if a new row was added to the table.
Or
do # Parses through the table.
{
statement_1;
statement_2;
}
while(varCurrentRow != varRowsCount); # Not the last row in the table.
2.6.5 Called Test and User Defined Function Comments
It is mandatory to add comments to all calls to tests or call statements. The comment should communicate what called test will do. An example of a call comment to invoke a test would be:
Call”UserRequestExistingApplication” (varApplicationName); # Makes a new software request.
2.7 Universal Variables and Reserved Words List
The following is a list of reserved words. These are in addition to the words reserved by WinRunner. There are definitions provided for standard use of the words presented on this list.
ü SetupScript – configuration script name for each project (preceeded by project acronym).
ü ControlScript – initialization script name for each project (preceeded by project acronym).
ü trs - (Test Return State) – used to pass “Success” or “Fail” to a calling script.
ü varTestEnv – variable to hold the web environment to test in (partial path).
ü varTestBaseDir – variable to hold the base test directory for the project (Projects or tmp).
ü varLeadDeveloper – variable to hold the email address of the lead developer of the project.
ü varProjectLead – variable to hold the email address of the project leader of the project.