Element locators

Element locators are used by certain actions in the Windows Recorder and Web Recorder to target elements on a webpage.


Page elements are targeted by defining a target window in DOM format and locators in either CSS selector or DOM format. The default target window is gomez_top[0].

Popups are referenced as additional "top" windows. For example, the first popup is gomez_top[1] and the second popup is gomez_top[2].

Similarly, frames are referenced with a "frame" index added to the target window name. For example, if the target window was the first frame on the first window, the target window is gomez_top[0].frames[0]. The second frame on that window is gomez_top[0].frames[1].

While recording, the Recorder identifies each page element that is involved in a user action and stores the appropriate locator information. For most scripts you do not have to enter this information manually.

Locators provide the agent with a means of finding a specific element on the webpage. Locators can be in either DOM or CSS-selector format. For troubleshooting purposes, it is useful to have an understanding of how locators work since they may be the most frequent cause of script failures.

DOM locators

DOM Locators are valid JavaScript expressions that reference the W3C DOM specifically. For example, if an element has an ID attribute of address1, the DOM locator for it could be document.getElementById('address1'). Similarly, if the element was a form element in the form contactForm, a possible locator is document.forms['contactForm'].elements['address1'].

CSS selector locators

CSS-Selector locators are based on the Sizzle selector library included in jQuery (http://docs.jquery.com/Selectors). CSS selectors are an extremely powerful, descriptive, and far easier way to locate elements on a page than traditional DOM elements. Using a combination of ids, CSS classes, attributes, and position in the document one can write locators that pinpoint specific elements in the document in very concise yet descriptive statements. For these locators, the content of the text boxes is what is executed in the $(' ') syntax of jQuery. For example, if the locator is #address1, it is executed in the browser agent similarly to $('#address1') when using jQuery.

Locators in the Dynatrace Portal

The Recorder generally tries to create as many locators of varying types as it can algorithmically. Occasionally these locators will not be sufficient: sometimes it is impossible to compute an appropriate locator, or the Recorder may record a locator that is valid in Recorder playback but not in the targeted browser agent that runs the script on the selected nodes.

The browser agent tries the locators sequentially, starting on the first and continuing until it finds one that returns a valid element. If no element can be found, the script fails with an error saying that it could not find the element specified. Occasionally the locator will return a valid but incorrect element, which can result in a failed transaction later in the script.