Here are my notes on writing scripts run by the automated software testing tool Robot from IBM Rational. This summarizes stacks of manuals and web pages.
Topics this page:
Just as with C and other programming languages, Robot scripts make use of several constructs:
SQABasic Files contain procedural (programming) code to recognize objects and use variables and constants in if-then-else, do-while, and other logical constructs. In larger projects, script code is modularized for reusability. Reusable code is organized into functions called from a script library header file. The name of such header files are included in scripts that use those functions.
Project Header Files structurally ensure that both function libraries and scripts that use them declare those functions and global constants the same way. Header files declare constants, variables, custom sub procedures, and custom functions which are common across an organization's scripts. This allows for code reuse in many scripts, therby also standardizing programming practices.
GUI Shell Scripts call script procedures (stored using a .rec file extension). Unlike functions, procedures are executed without parameters.
“Test automation must be approached as a
full-blown software development effort in its own right. Without this, it is most likely destined to failure in the long term.”
Because all this information are required inputs into Change and Configuration management (CCM) systems, including them at the beginning of each source file seems redundant and indeed can breed conflicting information.
One piece of comment that typically do not overlap with CCM information is a summary of the major functions performed within the file. These become major headings within the file.
It may be confusing to some that this statement begins with an apostophe ('), which is Basic language syntax for a comment line ignored by the compiler. Also notice that the file name is encased around double quotation marks and is not case sensitive. The file extension is .sbh.
This file lives in Robot's sqabas32 folder within Program Files, which makes it available to all scripts. This file declares:
Download their Software Automation Framework Support (SAFS) library containing keyword (data) driven execution engine for automated application-independent tests running under Rational Robot.
This product's .msi installs about 5 MB (261 files) into default folder Program Files \Rational \Rational Test \sqabas32\ (where Rational put "sqautil.sbh"). Files in that location is available to all files in the repository.
After, do File > Batch Compile.
But SQARobot assumes that testers are willing and able to write programming code to specify how objects can recognize a particular object or attribute, such as.
HTMLImage Click, "Name=txtLogin", "Coords=35,6"
If the application's programmer changes the name "txtLogin", the playback script will no longer work. Adapting to this means testers have to hunt through every script where the name is used.
An alternative is to have the tester define tester's variable name in an include file with this technical information as its value, then use that variable in all scripts. Such a file is called a Map file because it maps names assigned by testers to the technical references Robot needs to recognize objects. With map files, changes will only have to be made in one place (the include file), which is automatically percolated to all scripts.
RobotJ creates a map file automatically during script recording. RobotJ also assigns a weighting value to each object to specify how heavily RobotJ will rely on that object for recognition.
A call to a function can pass values as part of the call.
Shell scripts play back other scripts in sequence. This sample call executes a DOS batch file in the C:\ root drive:
Using them allow results from several scripts to be stored in the same Log file (which simplies results analysis and data management)
To avoid problems, shell scripts should not manipulate the environment.
You will not see a file if you simply copy it into your project folder. You must use File > New > Script and paste the code within Robot so that Robot can add it to its database of scripts in your project.
All DDE assets are defined with one line:
The include enables use of DDE functions such as this to enable "LogMessage" functionality:
InitLogFacility msgId, MainLog, logFile
The include also defines global variables (such as MainLog) and constants such as these stored in variable msgID used to determine when logging occurs:
(TEXTLOG_ENABLED OR SQALOG_ENABLED OR CONSOLE_ENABLED)
Additional constants and variables can be defined, such as the location of the test logfile and DDE's test summary report:
Const SaveASFile = "C:\TEMP\MyNotes.txt"
logFile = = SQAGetDir(SQA_DIR_PROJECT) &"MyTestLog1.txt"
The SQABasic command SQAGetDir(SQA_DIR_PROJECT) returns the file path of your test library. But beware that the DDE library assumes the presence of some folders that newer versions of Robot no longer create. So, you must create these folders before using the library.
To invoke a data-driven test using the SFAS/DDE library, the user script invokes one of the drivers functions from the DDE Library along with the file that controls it:
SDStepDriver "StepFile.txt", ";", MainLogThis script contains DD Driver Commands that control Driver functions:
Before all this, dimension variables and constants and delete any preexisting files output from prior tests:
on error resume next
on error goto 0
If there is no file to kill (such as when the script is run the first time), on error resume next tells Robot it's OK.
Afterword, invoke DDE's clean-up routines:
CloseTextLog MainLog, 1
c, SetApplicationMap, "NotepadMap.txt"
Parameters are position dependent. The first parameter position (which is not case sensitive) defines the type of request:
"S" or "s" records are skipped (treated as comments) by the driver.
"C" or "c" (command) records specify actions affecting the test environment, such as "ExitCycle" to abort processing.
"CW" expects a Warning result
"CF" expects a Failure result
"T" or "t" (Test) control records specify test actions using "component functions" of the SAFS/DDE library.
"TW" expects a Warning result
"TF" expects a Failure result
"B" or "b" records define where blocks of commands begin and end.
"BP" or "bp" records define breakpoints recognized during executions when Debug Mode is enabled and BREAKPOINTS has been turned "ON".
T, WindowID, WindowID, AWindowAction, Param1, ... t, AddUserAccount, , ^user=Name t, LoginWindow , UserIDField , VerifyProperty , "Text" , "userid" t, LoginWindow , UserIDField , SetTextValue , ^USER = "MyUserID" t, LoginWindow , OKButton , Click t, MainWindow , MainWindow , VerifyProperty , "Caption", ^USER
The ^ caret identifies variables from literal strings and is not actually part of the variables' names.
C, SetExitTableBlock, AExitHandlerTo reset so no special handler is invoked if/when ExitTable is executed:
C, SetExitTableBlock, ""
The DDE library also provides several Flow Control commands to exit to default script blocks:
The SFAS/DDE SuiteDriver works with user-defined lists of StepDriver tables that test an entire area of AUT functionality. Examples of test suites:
The CycleDriver (at the highest-level) invokes sets of suites. For example, there may be different control files to verify Integration Readiness, Systems Integrity, Functional Regression Stability, etc. Additionally, different cycles could correspond to each version or language of the AUT.
Sample commands to call these drivers:
CDCycleDriver "Cycle1.txt", ";", MainLogWithin the Cycle1.txt file are these statements:
STSuiteDriver "Suite1.txt", ";", Suite1Log
STSuiteDriver "Suite2.txt", ";", Suite2Log
declare sub CheckSave 'allocate name defined below. '$Include "sqautil.sbh" 'used for datapool scripts. '$Include "global.sbh" 'used by all scripts. Sub Main Dim Result As Integer 'Explicitly declare variable: dim strOpSys As String, strFileName As String dim strScriptUsed As String, strReturn As Integer const SCRIPTUSED As String = "Using Script 5/8/99" 'Assuming that the application is opened by the calling module: 'Press Alt-File, Save As to open dialog box: InputKeys %"FA" ' MenuSelect "File->Save As..." not used 'Analyze pop-up window to detect and handle unexpected dialog: 'Instead of Window SetContext, "Caption=Save As", "" 'which is not generic: Window SetContext, "Current Window" 'Get object name... 'Is it save as? ... 'Any other errors? Assert ... 'If an error is found, stop! ... 'Push a button that says "Save" PushButton Click, "Text=Save" SQADataPoolOpen Do while not EOF(1) 'Fetch the next record from the datapool: SQADataPoolFetch 'Retrieve a value from the datapool: SQADataPoolValue Input #1 strOpSys, strFileName if strOpSys = strOpSysUT then 'good, numReturn = CheckSave() 'Set field needed for either good or bad: (strScriptUsed = SCRIPTUSED) if numReturn> 0 then 'good, 'Write good record to Verification Log: SQAVpLog (strScriptUsed) else 'Write goon record to Verification Log: SQAVpLog (strScriptUsed) end if end if Loop End Do SQADataPoolClose 'Exit application: Window SetContext, "Current Window" MenuSelect "File->Exit" End Sub Sub CheckSave InputKeys strFileName 'Detect to see if an unexpected screen. Assert ... 'Otherwise: EditBox Click, "name=Save*" InputKeys strFileName 'Detect to see if file was really saved: GetAttr, ChDrive, ChDir, FileAttr, FileAttr, 'Set return signal: if good: Pos1 = 1 else Pos1 = 0 end if End Sub
Defining functions in a common source library allow them to be used by others. The DDE Library does this on such a massive scale that most web applications do not need custom functions.
To define a custom function:
End Function When a script wants to use a function, it first has to know what parameters to exchange with that function. Here is the format for declaring a custom procedure (MySub) in an SQABasic library file (MyLib.sbl):
Declare Sub MySub BasicLib "MyLib" (arg1 As String, arg2 As Integer)To call a function:
SQAGetPropertyThe last statement uses named arguments. A function's argument become parameters controlling the function or sub-procedure called. Double parentheses around an argument indicate that it cannot be changed by the procedure called.
Pos1 = instr(clipBoardString, "find me")
Call instr(clipBoardString, "find me")
instr acton:="clipBoardString", value:="find me"
Ideally, each function should return a result code indicating success or failure. The value of that result should use constants SUCCESS or FAILURE so that it can be customized. Some prefer zero to indicate failure. Microsoft prefers numeric "-1" to indicate failure.
Functions return a string or numeric value to the module which called it. But Sub Procedures do not return values to its caller.
The pointer to Library Files is stored in the Windows Registry key CommonDir under HKEY_LOCAL_MACHINE/SOFTWARE/Rational Software/Common (from Luke Goodwin)
One advantage of using the SAFS/DDE library is that it performs additional functionality not provided in native SQABasic commands. For example, SAFS/DDE String Utilities mimic the SQABasic string Trim$ functions. But it also trims TAB characters.
Both variables and CONSTANTS can be passed from a calling function to a script using that function.
CONSTANTS are defined in header files using a phrase like this:
Constants are in all upper case by convention.
Within a function library, a custom data type is defined by a phrase such as this:
Constants are in all upper case by convention.
Within a function library, a custom data type is defined by a phrase such as this:
If more than one window has that title, a window is chosen at random. And the comparison is NOT case-sensitive!
Robot waits for the time value defined in the global value ______
60000 milliseconds = 1 minute
The nSequence parameter above uses these Constants from DpConst.sbh:
SQA_DP_RANDOM = &H00000001 SQA_DP_SEQUENTIAL = &H00000010 SQA_DP_SHUFFLE = &H00000100
To retrieve the value of the specified datapool column.
To move the datapool's cursor to the next row:
To reset the cursor:
To close a datapool:
sqaDpSuccess = 0 sqaDpUnitialized = -1 sqaDpFailure = -2 sqaDpEOF = -3 sqaDpInvalidArgument = -998 sqaDpExtendedError = -999
From the Robot Tools menu, select Inspector....
Scroll through the Object Hierarchy to find the Caption= for your application under test. Click the [+] to expose objects for that window. Expand the "Generic,Class=Shel DocObject View;ClassIndex=1" Object, then the "HTMLDocument,HTMLTitle=..." displayed by your app.
Click each of these objects to view the value of each object's properties, such as width, height, innerText and outerHTML. Multiple instances of the same type are differentiated with an Index=value.
The name of Verification Points must be 20 characters or less and contain no special characters such as periods and dashes. Individual VPs are stored in the project's vp folder. Robot automatically creates VP files with the script name and file extension .obp. If you right-click on a VP item and select copy, you can paste it into another script's VP list.
Remember (in Robot world) you must right-click on "Verification Points" in order to paste. Robot automatically deletes and re-creates the .obp files.
Robot allows VP's to be created on the fly with these SQABasic commands:
DDE General Verification Functions:
To simulate an error use the SQABasic command Error.
Your first name:
Your family name:
Your location (city, country):
Your Email address:
Top of Page