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.

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.

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 "" 
  ...