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.

Summary
This page describes eValid's IndexFindElementEx command and explains its role and use.

General Background
In analyzing web pages one possible capability is to use an XPath expression. This facility provides a language for selecting nodes from an XML document that can be used to compute values based on the content of an XML document. Two important features of this are (i) the ability to search in the hierarchy of DOM elements, and (ii) the ability to match on regular expressions for names and/or values.

When applied to the DOM of a web page, an XPath is a powerful way to identify and enumerate page elements by specifying a few attributes/properties and possibly a few of their values.

eValid Application
However powerful the XPath notion is, it is not a particularly convenient way to organize tests of a web page, in which you generally want to be focused on one particular DOM element, or on a sequence of related DOM elements in the page.

In the eValid context the XPath idea is embodied in the IndexFindElementEx command that performs the same functions as an XPath except that rather than returning ALL of the elements in a page that match the specified criteria the eValid command identifies the NEXT match (based on starting the search at the current sourceIndex) on a DOM element described in the command.

This allows the playback script to position the sourceIndex value to a particular DOM element, upon which one or more subsequent commands that take action on the element can then be applied.

To get multiple matches or to refine your search you simply run the command multiple times, each time re-positioning the sourceIndex value you've found.

Command Description
Here is the IndexFindElementEx command description. This command is part of the DOM Element Manipulation/Motion command set.

KEY	COMMAND SYNTAX: Name(...)	ORIGIN	EXPLANATION	COMMENTS
PAGEMAP	IndexFindElementEx wid { UP | DOWN } { "string" [ "string" ] ...} "frame_path"	Edit	Description: Related to the IndexFindElement command, but provides for any number of matches of varying types. This command provides a comprehensive "fuzzy match" capability to identify specific HTML elements within pages for which the content is highly unpredictable, and for which there can be many instances of required matches. The value of a string in the command has a specific format: "name:x" to search for a match on a DOM element with a property named x "value:x" to search for a match on a DOM element with a property with value x The name and property values can be regular expressions. Behavior: Starting from the current sourceIndex, this command finds the first element that matches ALL of the specified name: and value: requirements simultaneously. The order of specifying the candidate match criteria is important. The scan is from the left of the command to the right. Those items least likely to match should be placed first to minimize the total processing time in complicated multi-element searches. Also, a value: match is made relative to the DOM element identified by the most-recently processed name: match, if any, that preceeded it. In other words, the command will search for any attribute property with a matching value if a value:x parameter is not preceded by a name:x parameter. The x parameter is assumed to be a regular expression and as a consequence certain characters in the string have special meanings, as described in the Regular Expression explanation. The x parameter can be blank but in that case a Warning is logged to advise the scripter who may have forgotten to write down a value. Results: If a match occurs in the current sourceIndex the sourceIndex is not changed. If NO match is found at or above/below (depending on whether the search direction parameter is UP or DOWN) the sourceIndex is not changed. The sourceIndex is changed ONLY if a match statisfying all of the specified criteria is found.	No adaptive playback activity is performed. Fields are assume left adjusted, and trailing blanks are ignored. A simple string without any Ex operators (or with Ex operators escaped properly) is automatically taken as a simple string match. For a match of the Left Hand Side (LHS) you write "string.*". For ANY acceptable content in either the property_name_Ex or property_value_Ex field you write ".*". Use the PageMap to identify the exact name of the frame_path to use, if necessary.

Typical Regular Expressions
Here is a quick primer and some typical examples of Regular Expressions that you may encounter in practical application of this command:

• All characters are literals except: ".", "*", "?", "+", "(", ")", "{", "}", "[", "]", "^" and "$".
• These special characters are literals when preceded by a "\". A literal is a character that matches itself. They all have special meanings; see the documentation.
• "ABC" matches when the string contains ABC.
• The "." is a single-character wild card. For example "A.C" matches with ABC or AXC or AWC, etc.
• The "^" indicates the beginning and "$" indicates the end of the string. For example, "^ABC" matches when the string begins with ABC. And, "XYZ$" matches when the string ends with XYZ.
• "ABC.*DEF" matches when the string contains an instance of ABC followed by an instance of DEF.
• ".*AB[CDEF].*" matches any string that contains one instance of the substring ABC or ABD or ABE or ABF.

Command Examples
Here are some examples of how this command works:

1. To find a link to a particular URL (for example, the first one that clicks on a link to www.cnn.com) and click on it would involve this sequence:

   IndexSet 0
   IndexFindElementEx 0 DOWN "name:innerHTML" "value:.*www.cnn.com.*" ""
   IndexFollowLink 0 ""

2. This sequence is used on mapslive.com to position sourceIndex on the "Zoom In" button, and zoom in a total of 2 times. Here we need to use IndexElementMouseDown & IndexElementMouseUp because that particular page is sensitive to mouse over actions and is not sensitive to clicks.

   IndexSet 0
   IndexFindElementEx 0 DOWN "name:id" "value:MSVE_navAction_tinyZoomBar_plus" "name:readStateValue" VALUE "4" ""
   IndexElementMouseDown 0 ""
   IndexElementMouseUp 0 ""
   IndexElementMouseDown 0 ""
   IndexElementMouseUp 0 ""

3. This command finds a DOM element on the current page that, starting from the top of the page and searching down the page, has an id that also contains an attributed name display with current value none.

   IndexSet 0
   IndexFindElementEx 0 DOWN "name:id" "value:Enter Your Name" "name:display" "value:none" ""
   IndexElementClick 0 ""

4. Like the previous example, this command finds a DOM element on the current page that, starting from the top of the page and searching down the page, has an id with specified value, and also contains at least one property (of any name) that contains the string complete as a substring.

   IndexSet 0
   IndexFindElementEx 0 DOWN "name:id" "value:Enter Your Name" "name:.*" "value:.*complete.*" ""
   IndexElementClick 0 ""

5. Searches for the second element that has an id defined (of any value) and an exact match for innerText = "Enter Name" in the same DOM element and then does a mouse down then mouse up on that element.

   IndexSet 0
   IndexFindElementEx 0 DOWN "name:id" "name:innerText" "value:Enter Name" ""
   IndexFindElementEx 0 DOWN "name:id" "name:innerText" "value:Enter Name" ""
   IndexElementMouseDown 0 ""
   IndexElementMouseUp 0 ""

6. This command matches an HTML element that contains the property named offset which has a value 31, 32, 33, 34, 35, 36 ,37, 38, or 39 and then performs an IndexSubmitClick action.

   IndexFindElementEx UP "name:offset" "value:3[123456789].*" ""
   IndexSubmitClick 0 ""