Your e-Business Quality Partner eValid™ -- The Web Quality Suite
Browser-Based Client-Side Functional Testing and Validation Page Timing/Tuning Transaction Monitoring. WebSite Spidering & Analysis and Realistic Server Loading.

eValid -- DOM Element Manipulation/Motion -- Command Description
eValid Home

Introduction
The basic idea of these commands is to make it possible to have playback sequences that move around within the current page and perform certain actions based on what is found there.

These commands give the tester the ability to create test scripts that "navigate" within the current page, possibly in a series of separate steps, to page objects and elements by their visible or DOM name, or even by DOM property name and value, without reference to specific DOM indexes.

Because no specific DOM index needs to be identified these tests will be insensitive to inconsequential page changes.

Background About Web Pages
The context for these commands is based on the organization of the web page in terms of its DOM. Every web page has a DOM that is organized as a collection of elements, each of which has a set of named properties. Individual properties associated with an element on the page may take on a specific value.

Many page elements have a variety of pre-defined properties, which are there and have meaning due to certain standards, but some pages have "custom properties" that can take on values as well. Each DOM element has [by default] a property named "sourceIndex" [note that property names are case sensitive], whose values uniquely number the elements, 0, 1, 2, ... in order in the DOM tree and in rough order of layout of the page on the screen.

You can study the DOM contents in the current page through use of the eValid PageMap utility. These commands help you find the right place to "do something", and to take action. In addition, there are IndexElementEvent commands that also can be used to compose a response.

The assumption here is that the "searching" being done is based on the delivered pages having this variable structure, but within which there is enough constancy of structure to make the high-level process of exploiting the order of elements feasible.

A Note About Perspective On A Page
UPThis means "up" on the page as seen by the viewer, i.e. toward the top of the page. This means decreasing index numbers.

The top of the page is "0".

DOWNThis means "down" on the page as seen by the viewer, i.e. toward the bottom of the page. This means increasing index numbers.

IndexFindElement   IndexFindElementEx   IndexSet   IndexSetEnd   IndexMove
IndexFollowLink   IndexElementClick   IndexSubmitClick   IndexInputValue
IndexValidateObjProperty    IndexSaveObjProperty
IndexElementMouseOver    IndexElementMouseOut    IndexElementMouseDown    IndexElementMouseUp
IndexElementEvent

DOM Element Manipulation/Motion Commands
 

Working Assumptions About These Commands:
  • There is only one sourceIndex known to eValid at any time.
  • The sourceIndex is always an integer.
  • The initial value of the sourceIndex is always set to zero.
  • The value of the sourceIndex persists between pages.
  • Commands that use this [internally stored] sourceIndex value always refer to the current page.
  • eValid does not modify the sourceIndex except by action of the commands below.
  • Because motion on the page is from the perspective of the view, a search DOWN toward the bottom of the page means increasing index numbers, whereas a search UP toward the top of the page means decreasing index numbers.
  • If that's not confusing enough, maybe this will help (or not): if you go all the way UP on a page, you're at sourceIndex 0.
KEY COMMAND SYNTAX:
Name(...)
ORIGIN EXPLANATION COMMENTS
PAGEMAP IndexFindElement wid { UP | DOWN } "property_name" ["property_value"] "frame_path" Edit
DOM
Starting from the current sourceIndex, this command moves up or down in the DOM element index number sequence until eValid reaches the next element with a property of the specified "property_name" [or until it reaches the next element with a property of the specified "property_name" which has the specified "property_value"], or until eValid reaches the end [or beginning] of the page.

The index movement is either UP (decreasing index numbers) initial index is positive or zero. of DOWN (increasing index numbers).

When a match if found this command leaves the sourceIndex set to the index of the matching HTML element, if found. If no match is found, the sourceIndex will remain the same.

Note that if the "value" parameter is specified and is given as simply "" then this is the same as requiring that the value string for that name be empty (blank).

This is the main command. Use it to find where to take an action.

No adaptive playback activity is performed for this command.

PAGEMAP IndexFindElementEx wid { UP | DOWN } "string" [ "string" ] ... "frame_path" Edit
DOM
Starting from the current sourceIndex, this command moves up or down in the DOM element index number sequence searching for a Regular Expression match.

For a complete explanation please see the IndexFindElementEx Command Explanation.

This is a primary command in the Index Motion/Manipulation set. Use it to find where to take an action.

No adaptive playback activity is performed for this command.

PAGEMAP IndexSet idx Edit
DOM
Moves the internally remembered current index to idx.

  • idx = 0 for the first element of the page.
  • idx if you know the specific index you want.

An illegal value is corrected to 0 and a message is issued to the Event Log.

Subsequent commands can be based on this starting index.
PAGEMAP IndexSetEnd wid "frame_path" Edit
DOM
Moves the internally remembered current index to the last available one on the indicated frame_path. Subsequent commands can be based on this starting index.
PAGEMAP IndexMove number Edit
DOM
Moves forward (positive number) or backward (negative number) the specified number of source index positions, possibly resulting in arriving at the top or bottom of page (but NOT wrapping around).

If an IndexMove command attempts to reach beyond the end of the page, or above the beginning of the page, the current index will be set to 0 and a Warning will be issued to the Event Log.

You will probably have to have a good idea of where your target is, or you may want to run an additional IndexFindElement command to reposition the current source index.

No adaptive playback activity is performed for this command.

PAGEMAP IndexFollowLink wid "frame_path" [NO_NAV] Edit
DOM
Similar to the FollowLink script command, the IndexElementClick employs the sourceIndex command issues a click at the current sourceIndex as set by a preceding IndexSet, IndexMove, or IndexFindElement command

Like the FollowLink command, a NAV is expected, hence there is no optional NAV parameter.

This command usually follows a search process, and sends a click to what is assumed to be an element that accepts a click meaningfully.

No adaptive playback activity is performed for this command.

PAGEMAP IndexElementClick wid "frame_path" [NAV] Edit
DOM
Similar to the Element Click command, this command issues a click at the current sourceIndex as set by a preceding IndexSet, IndexMove, or IndexFindElement command

The optional NAV parameter implies to expect navigation, and follows eValid's regular rules about how to handle NAVs.

This command usually follows a search process, and sends a click to what is assumed to be an element that accepts a click meaningfully.

No adaptive playback activity is performed for this command.

PAGEMAP IndexSubmitClick wid frame_path" Edit
DOM
Similar to SubmitClick command, with same parameters and meaning.

Clicks the button pointed to by the SourceIndex.

A navigation is expected to occur.

No adaptive playback activity is performed for this command.
PAGEMAP IndexInputValue wid "type" "extra-1" "extra-2" "frame_path" [NAV] Edit
DOM
See Detailed Explanation of IndexInputValue Command. This is the "Index" version of the InputValue command.

An optional NAV parameter specifies whether or not to expect navigation.

Adaptive playback activity is not performed for this command.
PAGEMAP IndexValidateObjProperty wid "property-name" "expected-value" "frame_path" Edit
DOM
Validates that on the current sourceIndex the property named takes on the specified value.

If the validation fails then an ERROR is logged in the EventLog.

No adaptive playback activity is performed for this command.
PAGEMAP IndexSaveObjProperty wid "property-name" "filename" "frame_path" [APPEND] Edit
DOM
On the current sourceIndex in the page, saves the the named property named to the specified filename. If the property does not exist, no action is taken.

If APPEND is present, then the data is added to the end of the file.

No adaptive playback activity is performed for this command.
PAGEMAP IndexElementMouseOver wid x y "frame_path" [NAV] Edit
DOM
At the current sourceIndex, executes a left-button MouseOver command.

The "x y" values specified are offsets within the object supplied by the DOM.

The optional NAV parameter needs to be specified if the action is expected to generate a navigation action.

No adaptive playback activity is performed
PAGEMAP IndexElementMouseDown wid [x y] "frame_path" [NAV] Edit
DOM
At the current sourceIndex, executes a left-button MouseDown command.

The optional [x y] values specified are offsets within the object that are supplied by the DOM.

The optional NAV parameter needs to be specified if the action is expected to generate a navigation action.

No adaptive playback activity is performed
PAGEMAP IndexElementMouseUp wid [x y] "frame_path" [NAV] Edit
DOM
At the current sourceIndex, executes a left-button MouseUp command.

The optional [x y] values specified are offsets within the object that are supplied by the DOM.

The optional NAV parameter needs to be specified if the action is expected to generate a navigation action.

No adaptive playback activity is performed for this command.
PAGEMAP IndexElementMouseOut wid x y "frame_path" [NAV] Edit
DOM
At the current sourceIndex, executes a left-button MouseOut command.

The "x y" values specified are offsets within the object supplied by the DOM.

The optional NAV parameter needs to be specified if the action is expected to generate a navigation action.

No adaptive playback activity is performed
PAGEMAP IndexElementEvent wid "event_name" "property_name" "property_value"
[ "property_name" "property_value" ] ... "frame_path" [NAV]
Edit
DOM
Description: Fires an event of event_name with specified event properties. A wide variety of events can be processed in this way. Multiple property_name/property_value pairs can be specified.

Explanation: See the complete IndexElementEvent Command Description for complete details and examples.

No adaptive playback activity is performed.

Example Usages
Here are some typical eValid Index Motion command sequences that illustrates the process for positional navigational activity.

  ...
  # Start at the top of the page...
  IndexSet 0 
  
  # Here is the line in the table we want...
  IndexFindElement 0 DOWN "innerText" "UPS Next Day Air" ""
  
  # Now, move just a bit down...to avoid a conflict...
  IndexMove +5
  
  # Here is where we want to click...
  IndexFindElement 0 DOWN "tagName" "INPUT" ""
  
  # Now, go ahead and click and wait for the expected navigation...
  IndexElementClick 0 "" NAV
  
  # Or, push the mouse down and up (this is NOT the same as a click)...
  IndexElementMouseDown 0 "" 
  IndexElementMouseUp 0 "" 
  ...