frm
Script emos_frm_tbl_lib

CompiledModule
  |
  +--emos_frm_tbl_lib

This libary provides a family of functions for support of table GUI objects. GUI objects in table format are known for being difficult to handle for many reasons. First of all, although a single object a tables can potentialy carry huge amounts of data. Depending on the testing objectives we sometimes need to handle only a handfull of cells and in other cases big portions of it if not the whole table. Programatic interfaces to tables are usually handle individual table cells and the navigation through table. More complicated actions on larger parts of table data are left to test programmers to be designed from the basic table operations.
Secondly, tables are often very dynamic objects (i.e. their content and their strucure sometimes changes within a single test session). A robust test design should provide for easy location of data (e.g. dynamcally determining the appropriate row/column) which is not a trivial task.
Finally, individual table cells can in fact contain various sorts of other GUI objects such as edit fields, drop-down lists, combo boxes, radio buttons, check buttons and other. Sometimes it seems as if vendors of GUI toolkits simply had to invent something that would distinguish their tables from all the other ones.

WinRunner's tbl interface does a fairly good job in making these various tables appear similar. However, there are plenty of situations where this is not the case. Here only individual solutions can help. Our table interface builds upon the strengths of WinRunner tbl-interface and is therefore able to handle many different tables. Still, due to mentioned difficulties, the interface is limited in some aspects and will need to be tuned for certain environments. Our code should work well with HTML tables and with tables with well-working tbl-interface (tbl_set_cell_data/tbl_get_cell_data). We hope also, that our code provides enough design ideas which will help you handle exotic cells such as edit fields, combo-boxes, etc.

Our table support has been specially designed for use in EMOS Framework tables. Pay special attention to functions FRM_TBL_set_data() and FRM_TBL_set_data_block(). The former implements an interface for handing individual table cells. The later implements an interface for handing bigger portions of tables.

Author:

drajovic

Tsl

emos_frm_tbl_lib.tsl

Function Summary

String	FRM_TBL_cell_action(in tbl, in cmd, in frm_mode, in desc, in list) Performs the action on a table cell as specified by the command cmd.
String	FRM_TBL_CHK_button(in tbl, in row, in col, in obj, in val, in simple_select, in exact)
String	FRM_TBL_CHK_cell_action(in tbl, in cmd, in desc, in list)
String	FRM_TBL_CHK_data(in tbl, in row, in col, in val, in simple_select, in operation)
String	FRM_TBL_CHK_edit(in tbl, in row, in col, in obj, in val, in simple_select, in exact)
String	FRM_TBL_CHK_pick(in tbl, in row, in col, in obj, in list, in val, in simple_select, in exact)
String	FRM_TBL_determine_col(in tbl, in row, in col, in val, out out_col, in exact) Returns the name/index of the column depending on the specified row/col.
String	FRM_TBL_determine_row(in tbl, in row, in col, in val, out out_row, in exact) Returns the name/index of the row depending on the specified row/col.
String	FRM_TBL_find_cell(in tbl, in regex, out out_row, out out_col, in row, in col, in exact, in row_offset) Searches for a cell that contains a given regex.
String	FRM_TBL_find_row(in tbl, in row_spec, out out_row, in idx, in row_offset) Searches for a row that contains given data in specified coumns.
protected String	FRM_TBL_generic_check(in actual, in expected, in operation)
String	FRM_TBL_get_cols_count_adjustment() Function tbl_get_cols_count() sometimes returns count that is less than the physical number of columns.
String	FRM_TBL_GET_data(in tbl, in row, in col, out val, in simple_select)
String	FRM_TBL_get_rows_count_adjustment() Function tbl_get_rows_count() sometimes returns count that is less than the physical number of rows.
String	FRM_TBL_list_select_item(in obj, in list, in item) Pops a drop-down list on a Stingray-ComboBox-cell by performing a left-mouse click at some calculated position within the obj.
String	FRM_TBL_obj_drop_list(in obj) Pops a drop-down list on Stingray-ComboBox-cell by performing a left-mouse click at some calculated position within the obj.
String	FRM_TBL_popup_cell_menu(in tbl, in row, in col) Selects the cell and opens it's popup menue via the <kAppa> key.
String	FRM_TBL_popup_menu(in tbl, in x, in y) Opens a popup menue at the specified location within the table object or, if not specified, at the top-left corner of the table object.
protected String	FRM_TBL_process_data_block(in tid, in block, in obj) Process 2-dimensional table block
String	FRM_TBL_select(in tbl, in row, in col, in simple_select)
String	FRM_TBL_SET_button(in tbl, in row, in col, in obj, in val, in simple_select)
String	FRM_TBL_set_cols_count_adjustment(in amount) Function tbl_get_cols_count() sometimes returns count that is less than the physical number of columns.
String	FRM_TBL_set_data_block(in tid1, in test, in obj) Performs an action(s) on a block of table cells.
String	FRM_TBL_set_data(in table, in test, in obj, in desc, in list) Performs operations on single table cells for the whole test block (i.e.
String	FRM_TBL_SET_data(in tbl, in row, in col, in val, in simple_select)
String	FRM_TBL_SET_edit(in tbl, in row, in col, in obj, in val, in simple_select)
String	FRM_TBL_SET_pick(in tbl, in row, in col, in obj, in list, in val, in simple_select)
String	FRM_TBL_set_rows_count_adjustment(in amount) Function tbl_get_rows_count() sometimes returns count that is less than the physical number of rows.
String	FRM_TBL_type(in tbl, in row, in col, in val, in simple_select)
String	FRM_TBL_web_get_child_item(in tbl, in row, in col, in desc)

Function Detail

FRM_TBL_set_data

public String FRM_TBL_set_data(in table,
                               in test,
                               in obj,
                               in desc,
                               in list)

Performs operations on single table cells for the whole test block (i.e. loops through all cells of a particular test block until an empty cell or the last cell is reached.

Parameters:

table - (in) table index

test - (in) test name

obj - (in) logical name or phisical description of the table object

desc - (in) [optional] physical description of an edit object that is located in the particular table cell (attempt only if such object really appears in the cell; we had to fight one tweeked VB table once with this; hopefulla you'll never need it; see FRM_TBL_cell_aktion() for more)

list - (in) [optional] physical description of a list object that is located in the particular table cell (attempt only if such object really appears in the cell, see code of FRM_TBL_cell_aktion function)

Returns:

E_OK if successful, else error

FRM_TBL_set_data_block

public String FRM_TBL_set_data_block(in tid1,
                                     in test,
                                     in obj)

Performs an action(s) on a block of table cells.

Parameters:

tid1 - (in) id of the table where the instructins come from

test - (in) name of the test to run (as named in column "Name")

obj - (in) table object where actions are to be performed

FRM_TBL_process_data_block

protected String FRM_TBL_process_data_block(in tid,
                                            in block,
                                            in obj)

Process 2-dimensional table block

FRM_TBL_set_rows_count_adjustment

public String FRM_TBL_set_rows_count_adjustment(in amount)

Function tbl_get_rows_count() sometimes returns count that is less than the physical number of rows. If present, the headings row is typically not counted. So the returned count is one less than the physical count. For our search functions (e.g. FRM_TBL_find_cell()) we need to access the headings row to search them. Increase the count_adjustment if you notice that our functions do not seem to find the value in the last row.

Parameters:

amount - (in) amount to adjust

FRM_TBL_get_rows_count_adjustment

public String FRM_TBL_get_rows_count_adjustment()

Function tbl_get_rows_count() sometimes returns count that is less than the physical number of rows. If present, the headings row is typically not counted. So the returned count is one less than the physical count. For our search functions (e.g. FRM_TBL_find_cell()) we need to access the headings row to search them. Increase the count_adjustment if you notice that our functions do not seem to find the value in the last row.

Returns:

the row adjustment amount

FRM_TBL_set_cols_count_adjustment

public String FRM_TBL_set_cols_count_adjustment(in amount)

Function tbl_get_cols_count() sometimes returns count that is less than the physical number of columns. If present, the headings column is typically not counted. So the returned count is one less than the physical count. For our search functions (e.g. FRM_TBL_find_cell()) we need to access the headings column to search for them. Increase the count_adjustment if you notice that our functions do not seem to find the value in the last column.

Parameters:

amount - (in) amount to adjust

FRM_TBL_get_cols_count_adjustment

public String FRM_TBL_get_cols_count_adjustment()

Function tbl_get_cols_count() sometimes returns count that is less than the physical number of columns. If present, the headings column is typically not counted. So the returned count is one less than the physical count. For our search functions (e.g. FRM_TBL_find_cell()) we need to access the headings column to search for them. Increase the count_adjustment if you notice that our functions do not seem to find the value in the last column.

Returns:

the row adjustment amount

FRM_TBL_cell_action

public String FRM_TBL_cell_action(in tbl,
                                  in cmd,
                                  in frm_mode,
                                  in desc,
                                  in list)

Performs the action on a table cell as specified by the command cmd. There are four types of actions you can perform on a table cell:

• S = select the cell (i.e. tbl_set_selected_cell/tbl_activate_cell)
• E = enter the value in a cell box of type edit (i.e. edit_set)
• P = pick the value from a list (i.e. list_select_item)
• T = type into the cell (i.e. type)
• D = enter data using tbl functions such as tbl_set_cell_data() or tbl_get_cell_data()

All actions can be specified by a generic syntax:

~action~[row]~[col][~val[~obj[~exact]]]

where

• ~ = any character that occurs only at specified positions (separator)
• action = one of the following: S|E|P|T|D, action can be prefixed with . or : (e.g. .S) where . means selection (tbl_set_selected_cell) and : means activation (tbl_activate_cell, i.e. double-click) [default: selection]
• row = row specification either as
  • index (e.g. #1)
  • search expression in form col1=val1[;coln=valn]... where col1 ist the name of the column containing val1, etc. the separator ; (semicolon) is interpreted as logical AND
  • <LAST> in which case the last valid row spec is reused (no search is performed for preformance reasons)
  • name (e.g. Par1) it is assumed that col #0 contains row names [obsolete; replaced by #0=val]
  • in case of Selection row can be left empty (assuming col and val are filled in) where val is searched for in col #0 [obsolete, replaced by construct #0=val]
• col = column specification either as
  • index (e.g. #1)
  • name (e.g. Col1)
  • search expression in form row1=val1[;rown=valn]... where row1 ist the name of the row containing val1, etc. the separator ; (semicolon) is interpreted as logical AND
  • <LAST> in which case the last valid column spec is reused (no search is performed for preformance reasons)
  • in case of Selection col can be left empty (assuming row and val are filled in) where val is searched for in row #0 [obsolete, replaced by construct #0=val]
• val = value which can be interpreted two-fold
  in case of Selection val can specify the content of the cell which is to be selected
  in other cases val represents the value for the E|P|T|D operations
• obj = a phisical description of the object to be actioned upon
• exact = indicats whether exact or tollerant matching [default] is to be performed

A few examples:

• ~S~#1~#2
  selects cell indexed by row=#1, col=#2
  
  
• ~.S~AnzahlH~Wert
  selects cell in a row named "AnzahlH" and a column named "Wert"
  
  
• ~:S~~Wert~xxx
  activates cell in a column "Wert" that contains "xxx"
  
  
• ~S~#1~~xxx
  activates cell in a row #1 that contains "xxx"
  
  
• ~E~#1~Wert~xxx
  sets (edit_set) cell in row #1 and column named "Wert" to "xxx"
  
  
• ~E~#1~#2~xxx~{class:edit,index:12}
  sets (edit_set) object with the given description that appears in cell #1:#2 to "xxx"
  
  
• ~S~aaa~bbb~~~1
  selects cell named exactly "aaa":"bbb"
  
  
• ~.T~#1~#2~abc
  types "abc" in cell #1:#2 (after selecting a cell with a single click)
  
  

Parameters:

tbl - (in) table name

cmd - (in) command to be performed

frm_mode - (in) [optional] FRM mode (FRM_SET_MODE|FRM_CHK_MODE|FRM_ATR_MODE|FRM_GEN_MODE)

desc - (in) [optional] default physical description of the object to be acted upon this description is used unless overridden by the cmd, if you don't provide this argument, "{class:edit}" will be used

list - (in) [optional] a description or a logical name of the combo box containing the obj.

FRM_TBL_CHK_cell_action

public String FRM_TBL_CHK_cell_action(in tbl,
                                      in cmd,
                                      in desc,
                                      in list)

FRM_TBL_select

public String FRM_TBL_select(in tbl,
                             in row,
                             in col,
                             in simple_select)

FRM_TBL_GET_data

public String FRM_TBL_GET_data(in tbl,
                               in row,
                               in col,
                               out val,
                               in simple_select)

FRM_TBL_SET_data

public String FRM_TBL_SET_data(in tbl,
                               in row,
                               in col,
                               in val,
                               in simple_select)

FRM_TBL_CHK_data

public String FRM_TBL_CHK_data(in tbl,
                               in row,
                               in col,
                               in val,
                               in simple_select,
                               in operation)

FRM_TBL_generic_check

protected String FRM_TBL_generic_check(in actual,
                                       in expected,
                                       in operation)

FRM_TBL_SET_edit

public String FRM_TBL_SET_edit(in tbl,
                               in row,
                               in col,
                               in obj,
                               in val,
                               in simple_select)

FRM_TBL_CHK_edit

public String FRM_TBL_CHK_edit(in tbl,
                               in row,
                               in col,
                               in obj,
                               in val,
                               in simple_select,
                               in exact)

FRM_TBL_SET_button

public String FRM_TBL_SET_button(in tbl,
                                 in row,
                                 in col,
                                 in obj,
                                 in val,
                                 in simple_select)

FRM_TBL_CHK_button

public String FRM_TBL_CHK_button(in tbl,
                                 in row,
                                 in col,
                                 in obj,
                                 in val,
                                 in simple_select,
                                 in exact)

FRM_TBL_SET_pick

public String FRM_TBL_SET_pick(in tbl,
                               in row,
                               in col,
                               in obj,
                               in list,
                               in val,
                               in simple_select)

FRM_TBL_CHK_pick

public String FRM_TBL_CHK_pick(in tbl,
                               in row,
                               in col,
                               in obj,
                               in list,
                               in val,
                               in simple_select,
                               in exact)

FRM_TBL_type

public String FRM_TBL_type(in tbl,
                           in row,
                           in col,
                           in val,
                           in simple_select)

FRM_TBL_determine_row

public String FRM_TBL_determine_row(in tbl,
                                    in row,
                                    in col,
                                    in val,
                                    out out_row,
                                    in exact)

Returns the name/index of the row depending on the specified row/col. If <row> is given (i.e. != ""), the unchanged value is returned. If <row> is not given (i.e. == ""), the row containing the given <val> is searched for in the column specified by <col>. If both <row> and <col> are not given, an error is returned.

Parameters:

tbl - (in) table object

row - (in) row to select (if row does not equal "", no search is performed; if row equals "", last valid row determined by this function is returned (no search performed))

col - (in) column where <val> is searched for

val - (in) value to search for in the given column

out_row - (out) the name of the determined row

exact - (in) [optinal] true indicates that an exact match is to be performed

Returns:

E_OK: value was found (i.e. out_row contains the name of the row) else: error

FRM_TBL_determine_col

public String FRM_TBL_determine_col(in tbl,
                                    in row,
                                    in col,
                                    in val,
                                    out out_col,
                                    in exact)

Returns the name/index of the column depending on the specified row/col. If <col> is given (i.e. != ""), the unchanged value is returned. If <col> is not given (i.e. == ""), the column containing the given <val> is searched for in the row specified by <row>. If both <row> and <col> are not given, an error is returned.

Parameters:

tbl - (in) table object

row - (in) row to select (if row does not match "#[0-9][0-9]*", then column #0 is searched for the value <row>

col - (in) column to select (if col does not equal "", no search is performed; if row equals "", last valid row determined by this function is returned (no search performed))

val - (in) value to search for in the determined row

out_col - (out) the name of the determined column

exact - (in) [optinal] true indicates that an exact match is to be performed

Returns:

E_OK: value was found (i.e. out_col contains the name of the column) else: error

FRM_TBL_find_row

public String FRM_TBL_find_row(in tbl,
                               in row_spec,
                               out out_row,
                               in idx,
                               in row_offset)

Searches for a row that contains given data in specified coumns. Note that an exact mtch is always performed. If such row is found (first from top!) the row index is returned otherwise an error is indicated. Cells can be specified using the following syntax:

col=val[;col=val]...

where col is either

• name such as "Column1" (without quotes!)
• index such as #3

Parameters:

row_spec - (in) formated cell content specification (see above)

out_row - (out) row index (only if retrn == E_OK)

idx - (in) [optional] internal index needed for recursion

Returns:

E_OK: row found E_NOT_FOUND: row not found else: other error

FRM_TBL_find_cell

public String FRM_TBL_find_cell(in tbl,
                                in regex,
                                out out_row,
                                out out_col,
                                in row,
                                in col,
                                in exact,
                                in row_offset)

Searches for a cell that contains a given regex. You can limit the search to a particular row or a col, by providing their names or indices (#idx).

Parameters:

tbl - (in) table object

regex - (in) text to search for (regular expression)

out_row - (out) row where text was found

out_col - (out) column where text was found

row - (in) [optional] limit the search to this row only

col - (in) [optional] limit the search to this column only

exact - (in) [optional] TRUE=exact match, FALSE=tolerant match [default=FALSE]

row_offset - (in) [optional] row index where the search begins [default=0]

Returns:

E_OK: text found E_NOT_FOUND: text not found else: other error

FRM_TBL_popup_cell_menu

public String FRM_TBL_popup_cell_menu(in tbl,
                                      in row,
                                      in col)

Selects the cell and opens it's popup menue via the <kAppa> key.

Parameters:

tbl - (in) table object

row - (in) row to select

col - (in) column to select

FRM_TBL_popup_menu

public String FRM_TBL_popup_menu(in tbl,
                                 in x,
                                 in y)

Opens a popup menue at the specified location within the table object or, if not specified, at the top-left corner of the table object.

Parameters:

tbl - (in) table object

x - (in) [optional] x-coordinate to click to [default: 0]

y - (in) [optional] y-coordinate to click to [default: 0]

FRM_TBL_list_select_item

public String FRM_TBL_list_select_item(in obj,
                                       in list,
                                       in item)

Pops a drop-down list on a Stingray-ComboBox-cell by performing a left-mouse click at some calculated position within the obj.

Parameters:

obj - (in) object to click

list - (in) list object that drops down after the click

item - (in) item to select

Returns:

E_OK: success else: failure

FRM_TBL_obj_drop_list

public String FRM_TBL_obj_drop_list(in obj)

Pops a drop-down list on Stingray-ComboBox-cell by performing a left-mouse click at some calculated position within the obj.

Parameters:

obj - (in) object to click

Returns:

E_OK: success else: failure

FRM_TBL_web_get_child_item

public String FRM_TBL_web_get_child_item(in tbl,
                                         in row,
                                         in col,
                                         in desc)