SQABasic "CycleDriver" Script
MODULE DESCRIPTION:
Application-independent driver for data driven automation with SQA.
Used in conjunction with SuiteDriver and StepDriver.
The three driver routines form the primary data-driven engine for test
automation.
StepDriver is the primary GUI driver, exercising the AUT and verifying
AUT status and data via lists or tables of user-defined instructions.
The format of these instructions is easy to understand, is AUT
independent, is automation tool independent, and can be used as scripts
for manual testing. They are generally very short, performing only
a few simple steps to drive, test, or verify a small piece of a particular
application state or function. For example, one table may verify the text
of a set of controls or window. Another may check that particular
menuitems are present and in the proper state. Another may activate a
particular control while another ensures the AUT responded accordingly.
SuiteDriver is the mid-level driver whose data tables are generally
generally user-defined lists of StepDriver tables. Here the simple StepDriver tables
are linked together to form more complex sets of tests. Each Suite might
test an entire area of functionality for a given AUT.
For example, there may be a Suite to test the entire Reports section of an
app, another to fully test Data entry.
CycleDriver is the highest level driver whose data-tables are generally
lists of Suites to provide the SuiteDriver. Thus, this defines the total
test for the AUT through the data-driven engine.
Since CycleDriver is the highest level of data-driven automation, it is
generally invoked by a Robot Script which has been setup to perform a
particular Test Cycle. For example, there may be an Integration Test Cycle,
a Systems Test Cycle, a Build Verification Cycle, a Regression Test Cycle,
as well as versions of these for different versions of the AUT.
DATA TABLE FORMAT:
Each command line or record in the provided filename represents the
start of a new record/command/entry.
It is possible for a single command to use multiple lines if its syntax
or implementation provides that capability. This routine, at this time,
expects the information it needs to reside on the current command line.
Blank Lines are ignored.
For each valid record:
Field #1: Represents one of our RECORD TYPES.
Remaining Fields (2-N) are interpreted based on the RECORD TYPE.
Consult the various routines of this driver to determine the format
and number of fields needed for each RECORD TYPE.
If Field #1 is empty, the entire record is skipped.
If Field #1 contains an entry other than a known record type, we
will assume it is the name of a runnable Robot script and will attempt
to execute it. This is called IMPLIED SCRIPT EXECUTION.
Comment Lines begin with a comment delimiter(s) RECORD TYPE.
(Generally, ['] and [;] will be treated as comment lines as well as
and record whose first field is empty.)
All fields not containing variables (see below) within a record can
be enclosed in double quote marks to help visually delimit fields.
Valid record fields can be used to set and receive variable values
that can be used for the current table and any subsequent tables.
Where a field is used to set a value it is also immediately replaced
by that value for immediate use. Variables are referenced by immediately
preceding their names with a caret (^). The symbol must be the first
non-whitespace character in the field. Variable references cannot reside
inside of quotation marks or they will be treated as literal strings.
It is important to note that a field that is replaced by a variable's
value will be enclosed in quotes.
See DDVariableStore for more information on the use of variables in
these data tables. Specifically, DDVSubstituteVariables and
DDVExtractVariables.
SAMPLE DATA TABLE:
' Data Table Sample
' Some Record Types:
' B = Define a Named Block within the file
' C = Driver Command
' S = SKIP this Record
' T = Perform a ComponentFunction action or test
c_ Version "1.0"
c_ SetApplicationMap_ "AppMap.map"
c_ WaitForGUI _ LoginWindow_ LoginWindow_ 30
' Do some Data Driven Login tests here....
t_ LoginTests _ "," _ ^userid = "MyUserID" _ ^password = "MyPassword"
t_ VerifyLogin _ ","
A user or developer would normally only call the CDCycleDriver
routine. This is the entry point used by the Robot Script to commence our
automated test. All other routines are called by the CDCycleDriver
routine as required.
(Some multi-line test commands may eventually call CDGetLineInput.)
NOTE:
**** **** **** **** ****
SQARobot must be configured to "Continue Execution" upon Script Command
Failures in order for this to work properly. Where appropriate we set
flags and status to recognize, report, and work with these failures.
**** **** **** **** ****
This library is defined by:
CycleDriver.SBH Export Header File
CycleDriver_X.SBH Constants, Globals, Types etc.
CycleDriver.SBL Sourcecode and Detailed Documentation
CycleDriver.SBX Compiled executable library
Orig Author: Carl Nagle
Orig Date: SEP 02, 1999
History:
SEP 07, 1999 Original Release
JUL 21, 2000 (CANAGL) Streamlined for variables and scripts
JAN 21, 2001 (CANAGL) Redesigned reentrancy and the STACK.
APR 23, 2001 (CANAGL) Removed CDCallScriptMode Global and related constants.
Consolidated functionality into DDDriverCommands lib.
OCT 01, 2001 (CANAGL) Enabling DEBUG MODES and enhanced expressions.
OCT 18, 2002 (CANAGL) Added Expected Failure support.
APR 01, 2005 (RDUCHARME) Added logic to support table caching
MAY 14, 2005 (CANAGL) Fixed EOF detection for non-cached branching.
JUN 06, 2005 (CANAGL) Fixed blank field 1 handling to treat as comment.
DEC 13, 2005 (CANAGL) Added support for safsActiveCycle DDVariable.
FEB 07, 2006 (CANAGL) Added support .statusinfo and BRANCH_TO_BLOCKID return code
MAR 20, 2007 (CANAGL) Added support to ignore UTF-8 leader characters.
Copyright (C) SAS Institute Inc. All rights reserved.
GNU General Public License: http://www.opensource.org/licenses/gpl-license.php
Action Commands
Global Variables
Routine Details
User Dependencies:
(stuff the developer's library/script $INCLUDES at compile time.)
(Note: The order of items may matter and may be different for your code.)
Internal Dependencies:
(stuff this library needs at compile time.)
DDE Action Commands
*** NO SUPPORTED ACTION COMMANDS SECTION FOUND ***
Globals
(none)
Routine Details
Function CDProcessTestRecord (suiteFac As LogFacility,
stepFac As LogFacility) As Integer
DESCRIPTION:
At this point the Driver has determined we are dealing with a Test Record.
A Test Record is one containing a data table filename for SuiteDriver to execute.
Field #1: The TEST record type (T).
Subsequent fields would be as follows (with a separator between each field):
Field: #2 #3
================= =============
SuiteDataFILENAME Separator
FILENAME: A filename or path suitable for the SuiteDriver.STSuiteDriver routine.
(No error checking is done here. It is done in SuiteDriver.)
SEPARATOR: (Optional) Character(s) to use as the field separator for
specified file. Normally, you would only specify this if the
separator is different than the one currently in use.
The default is to use the one currently in use (STFieldSeparator).
NOTE:
A user or developer would not normally call this routine. This
routine is intended to be called from the CDCycleDriver routine as
deemed necessary by the input records of the data table provided to
the CDCycleDriver routine. The routine declaration and parameters are
subject to change as necessary.
PARAMETERS:
suiteFac LogFacility to log SuiteDriver messages to.
stepFac LogFacility to log StepDriver messages to.
RETURNS:
CDGeneralScriptFailure if we were unable to call SuiteDriver
(generally, a missing table filename)
CDNoScriptFailure if we DID call SuiteDriver
(Suite/Step Driver failures CAN have occurred, however)
ERRORS:
none
Orig Author: Carl Nagle
Orig Date: SEP 07, 1999
History:
SEP 07, 1999 Original Release
JUL 21, 2000 (CANAGL) Streamlined for variables and scripts.
JUN 20, 2001 (CANAGL) Added FlowControl and Error Recovery Handling.
JUN 21, 2001 (CANAGL) Changed Error return to DDU_SCRIPT_NOT_EXECUTED.
OCT 01, 2001 (CANAGL) Enabling DEBUG MODE.
Sub CDCycleDriver (filename As String, separator As String,
fac As LogFacility, suiteFac As LogFacility,
stepFac As LogFacility, Optional mode)
DESCRIPTION:
This is the routine that a Robot Script or other user utility should
call within this library to commence a data-driven test.
All the other routines are called from this routine based upon the
input records of the provided data table.
DATA TABLE FORMAT:
Each command line or record in the provided filename represents the
start of a new record/command/entry.
It is possible for a single command to use multiple lines if its syntax
or implementation provides that capability. This routine, at this time,
expects the information it needs (only the record type) to reside on the
current command line.
Blank Lines are ignored.
For each valid record:
Field #1: Represents one of the driver RECORD TYPES.
Remaining Fields (2-N) are interpreted based on the RECORD TYPE.
Consult the various routines of this driver and DDDriverCommands to
determine the format and number of fields needed for each RECORD TYPE.
If Field #1 is empty, then the entire record is skipped.
If Field #1 is an unrecognized record type, the Driver will attempt to
execute it as a Script. In that case, subsequent fields in the input
record can contain any parameters or DDVariables the script might want or need.
See Using DDVariables for more information on this nifty capability!
Comment Lines begin with a comment delimiter RECORD TYPE--a single quote (').
Lines whose first non-blank character is a semicolon (;) are also ignored.
The routine does not have a return value since it is a subroutine.
However, upon exit, the GLOBAL CycleDriverInfo will contain all the status
information available on the results of the call.
PARAMETERS:
filename String filename to the data table to use as input.
The routine tries to locate the file as if it were a full path.
If it doesn't find it then it attempts to locate the file
relative to the repository, the project, the project\datapool.
separator field separator String to isolate fields within each
data table record.
If not provided(""), uses last defined separator (CDFieldSeparator).
If none ever provided then uses a comma (,).
fac LogFacility to use for CycleDriver logging.
suiteFac LogFacility to use for SuiteDriver logging.
stepFac LogFacility to use for StepDriver logging.
mode Optional parameter specifying in what mode CycleDriver should
be running. By default, CycleDriver runs in CDStandAlone mode
and outputs additional test information for each data table it
processes.
In a Cycle Driven mode this additional information may not be desirable.
See Cycle Driver Modes in the CONSTANTS section
for valid CycleDriver modes.
ERRORS:
none
Orig Author: Carl Nagle
Orig Date: SEP 07, 1999
History:
SEP 07, 1999 Original Release
JUL 21, 2000 (CANAGL) Streamlined for variables and scripts.
JAN 21, 2001 (CANAGL) Redesigned reentrancy and the STACK.
APR 23, 2001 (CANAGL) Removed CDCallScriptMode Global and related constants.
Consolidated functionality into DDDriverCommands lib.
OCT 01, 2001 (CANAGL) Enabling DEBUG MODES and enhanced expressions.
OCT 18, 2002 (CANAGL) Added Expected Failure support.
APR 01, 2005 (RDUCHARME) Added logic to support table caching
MAY 14, 2005 (CANAGL) Fixed EOF detection for non-cached branching.
JUN 06, 2005 (CANAGL) Fixed blank field 1 handling to treat as comment.
DEC 13, 2005 (CANAGL) Added support for safsActiveCycle DDVariable.
FEB 07, 2006 (CANAGL) Added support .statusinfo and BRANCH_TO_BLOCKID return code
MAR 20, 2007 (CANAGL) Added support to ignore UTF-8 leader characters.
Function CDGetLineInput(fileref As Integer) As String
DESCRIPTION:
Routine retrieves and returns the next line from the fileref provided
and increments the CycleDriverInfo.linecount counter.
The routine returns the line--which is a result of a Line Input #fileref
CDatement--unmodified.
All routines which input records from the CycleDriver data table should
call this routine for their line input in order to maintain an accurate
linecount.
PARAMETERS:
fileref Integer from file's OPEN CDatement.
RESULTS:
String returned from Line Input CDatement unmodified.
ERRORS:
none
Orig Author: Carl Nagle
Orig Date: SEP 07, 1999
History:
SEP 07, 1999 Original Release
APR 01, 2005 (RDUCHARME) Added logic to support table caching
MAY 14, 2005 (CANAGL) Fixed EOF detection for non-cached branching.
Copyright (C) SAS Institute
GNU General Public License: http://www.opensource.org/licenses/gpl-license.php
==============================================================================