Troubleshooting locator errors

The best way to resolve locator issues in scripts is to prevent them. Before recording the script, walk through the actions in the web browser or native application to make sure there are no issues that might prevent successful script recording and playback.

If your walkthrough identifies issues with locators, use the information in the sections below to diagnose and resolve those issues.

Locator troubleshooting procedures

Resolving local locator issues

  1. Manually perform the script steps in your local browser, depending on which agent you want to test against, and navigate up until the point of error.
  2. Use the browser's inspection utility to inspect the source code of the object at which the script throws the error.
  3. Update the locator in the script according to the information you see in the inspection utility.
  4. Play back the script against the desired browser agent.

Resolving locator issues in the Dynatrace Portal

  1. Make sure Screen Capture on Error (SCoE) is enabled for the test.
  2. Check the SCoE results to make sure the correct page has loaded.
  3. Download the script from the Platform into the Recorder, and try to reproduce the issue by playing back the script locally.
  4. If you can reproduce the issue, perform the Resolving Local Locator Issues procedure (above).

Locator basics

The Recorder uses DOM and CSS locators to detect objects. The locators are used to match an element instance based on its identifier. Knowing the locator rules can be very helpful when troubleshooting an action.

Most locator errors occur when the Recorder tries to find a dynamic object that has changed.

When a step fails because of a CSS locator error, it has exhausted all of the locators available for the object. The Recorder goes through the queue of locators and if none work, the Recorder issues an alert that the first locator has failed. For example:

Javascript ErrorDetails:
Step 2, action 1: Failed to locate object: DOMselector
document.forms[1]["gomez"] in window gomez_top[0]

The failed step is displayed in the Recorder as shown in the following figure.

When this error occurs, the first thing you should do is to make sure the object exists. Using the rules described below, you should be able find a different way to locate the desired object.

Locator types

DOM locators

Only a few DOM locators are useful within the Recorder. The following table describes the DOM locators you are likely to use.

Locator Description
document.getElementById("element id") Locates the element directly by its ID. Example: document.getElementById("main")
document.forms["<form>"]["element"] Locates the element using the form name or ID and the element's name or ID. Example: document.forms ["aspnetForm"]["main"]
document.forms[0]["element"] Locates the element using the form number and the element's name or ID. Example: document.forms[1]["main"]

CSS locators

Although DOM locators can be useful, CSS offers many more options for locators.

Locator Description
#elementId Locates an element directly by its ID. Example: #main
element[varName ^= "test"] Locates an element where the variable varName begins with the value test. Example: a[title ^= "Gomez"]
element[varName $= "test"] Locates an element where the variable varName ends with test. Example: a[href $= ".html"]
element[varName *= "test"] Locates an element where the variable varName contains test. Example: input[name *= "search"]
element[varName = "test"] Locates an element where the variable varName is equal to test. Example: input[value="Type Here"]
element[varName1="test1"][varName2="test2"] Locates an element where the variable varName1 is equal to test1 and varName2 is equal to test2. Example: input[name="searchsubmit"][type="image"]
element:contains("test") Locates an element where the text contains test. Example: a:contains("Dynatrace!")
locator:eq(0) Uses the eq function to obtain a certain instance of any locator. The instances begin at zero. If, for example, you want to find the second instance, you need to set eq to 1. Example: a[href *= "dynatrace"]:eq(1)
locator:not(locator) When a locator finds two elements with similar qualities and you want a specific one, not excludes the element you do not want. Example: a:contains("Big Crunch Sandwich Combo"):not(:contains("Spicy"))

Target window

If none of the locators work, the target window may be incorrect.

The variable gomez_top is an array of the windows currently open within the script. The index for these windows starts at zero. For every N window, you must access the window by setting the index to N-1. For example, if you want to access the third window the script generates, set the target window to gomez_top[2].

The default target window is gomez_top[0], which directs the script actions to the original browser window. If any popup windows are generated within this script and you want to interact with them, you need to change the index for the target window.


A frame is an application within a website that divides the user’s display into two or more windows that can be scrolled independently. Navigating frames can be tricky to script. The frames object is an array just like gomez_top, so the same N-1 indexing rules apply. Referencing a frame can be done within the target window as well.

To find what frame contains the element is in, you can use a browser tool to inspect it, such as Firebox for the Firefox browser. When an element is selected in Firebug, it shows the path it which it is located. The following shows a selected element that is within a frame. The elements path specifies two frames. In this example, the target window is  gomez_top[0].frames[0].frames[0], because there is a frame within a frame. However, identifying the frame can be complicated, and you may need custom code to figure out the frame count.

Browser tools for inspecting elements

Each browser has its own tool for inspecting elements. The following procedures show how to inspect the Google search box in the Firefox, Internet Explorer, and Chrome browsers.

Firefox Firebug

Before performing this procedure, make sure the Firebug Add-On is installed in Firefox.

  1. Open Firefox and go to
  2. Press Shift+Ctrl+C to open the element inspector.
  3. Click the Google search field.
    In the Inspector, the code for the search box is highlighted. The element information is displayed on the right.

You now have access to all the information that is related to that element. The code includes the element's ID, name, link information, and many other details.

IE Developer Toolbar

In Internet Explorer, use the Developer Toolbar to view element information. It works the same way that the Firebug add-in works in Firefox.

Before performing the procedure, make sure you have the IE Developer Toolbar installed in Internet Explorer.

  1. Open Internet Explorer and go to
  2. Press F12 to open the Developer Tools.
  3. Click the cursor icon to bring up the element inspector.
  4. Click the Google search field.
    In the Developer window, the code for the search box is highlighted.
  5. Select Attributes on the right to display information for all the element attributes.

You now have access to all the information related to the element. The attribute information in particular can be very useful for troubleshooting locators.

Chrome user-agent switcher

The Recorder uses the Chrome browser to record scripts for mobile devices. When you record a mobile script, the websites render as they do because the user-agent string that the Recorder passes to the web server tells the web server to send content appropriate for the device being emulated.

You can add an extension to the Chrome browser that adds a user-agent icon next to the address bar. Through this icon, you can choose which user-agent to send to web servers for the browser session, so web pages will be rendered as if the pages were displayed on the selected device.

The Chrome Web Store may feature several user-agent switcher extensions. The recommended extension is called User-Agent Switcher for Chrome.

Before performing this procedure, make sure User-Agent Switcher for Chrome is is added to the Chrome browser.

  1. Open the Chrome browser and go to
  2. In the top right corner of the browser, click the User-Agent Switcher icon and select the device or browser you want to emulate.
    The icon changes to indicate the selected device.
  3. Right-click in the Google search box and select Inspect Element from the context menu.
    The Elements pane of the Chrome JavaScript Console opens at the bottom of the window. The code for the search box is highlighted in the left side, and element information is displayed on the right.