Exit course
Chapter 3 of 10 Beginner 6 min read 2 quick checks Updated

Commands, Targets and Locators in Selenium IDE

On this page
  1. Command, target, value
  2. Locators: how the target finds an element
  3. Which locator to keep
  4. The fallback locators are not tried during playback
  5. Locators that work on the grid and on phones

Every step in a Selenium IDE test is one row with three fields: a command, a target and a value. This chapter covers how to read them, which locator to keep when the recorder offers several, and what really happens to the alternative locators the IDE stores. That last part is different from what most guides, and the Selenium IDE homepage, still say.

Command, target, value#

The command decides what the other two fields mean:

Command Target Value
open a URL or a path such as /login
type the element to type into the text
click the element to click
select the <select> element which option, such as label=Option 2
check / uncheck a checkbox or radio button
assertText the element the exact text you expect
store the text to store the variable name
executeScript JavaScript optional variable name for the result

The full list of commands is in the Selenium IDE command reference. That reference dates from version 3, but the commands it describes still exist in version 4.

Locators: how the target finds an element#

A target that points at an element is a locator: a strategy, an equals sign and a value.

Locator Finds
id=username the element with id="username"
name=username the element with name="username"
css=#flash.success the first element matching a CSS selector
linkText=Logout a link whose full text is "Logout"
partialLinkText=Log a link whose text contains "Log"
xpath=//button[@type='submit'] the first element matching an XPath expression

When you record a click, the IDE looks at the element and builds a list of locators for it. In version 4 it tries a data-test-id or data-test attribute first, then id, link text and name, then other data- attributes, a generated CSS selector (css:finder) and several XPath forms. The first one it finds becomes the target; the full list is stored next to it as targets. In the target field's drop-down you can switch to any of them.

For the Login button on our practice page the recorded list looks like this:

"target": "css=.radius",
"targets": [
  ["css=.radius", "css:finder"],
  ["xpath=//button[@type='submit']", "xpath:attributes"],
  ["xpath=//form[@id='login']/button", "xpath:idRelative"],
  ["xpath=//button", "xpath:position"],
  ["xpath=//button[contains(.,' Login')]", "xpath:innerText"]
]

The button has no id, name or data-test attribute, so the recorder fell back to a CSS selector built from its class. radius is a styling class: a redesign can rename it and the test breaks without anything being wrong with the login.

Which locator to keep#

Choose in roughly this order:

  1. A test attribute such as data-test-id="login-button" or data-test="login-button". It exists only for tests, so nobody renames it by accident. If you can ask the developers for one thing, ask for these on the elements you test. The recorder picks them up automatically.
  2. A stable id or name, like id=username. Avoid ids that look generated (id=ember1234, id=react-select-3-input): they change between builds.
  3. The visible text of a link, linkText=Logout. Readable, but it breaks when the copy or the language changes.
  4. A short CSS selector on meaningful attributes, such as css=button[type='submit'] or css=#login button.
  5. Last resort: positional XPath such as xpath=//div[2]/div/input or xpath=//li[18]/a. These describe where an element happens to sit today, and they break when anything above it moves.

Never trust a locator only because the recording replayed once. Ask what the page change would have to be to break it.

The recorder offers these targets for a "Save" button. Which one should you keep?

A test attribute exists only for tests and survives layout and styling changes. The XPath breaks when anything above the button moves, and the class list breaks with the next restyle.

The fallback locators are not tried during playback#

The Selenium IDE homepage says that if one locator fails during playback, the others are tried until one works. That was a selling point of the old extension. It is not what the version 4 runtime does.

We checked it with a test whose target is broken on purpose while a working locator sits in its targets list:

{ "command": "type", "target": "id=user-name", "value": "tomsmith",
  "targets": [["id=user-name", "id"], ["name=username", "name"], ["css=#username", "css:finder"]] }

name=username and css=#username both match the field. selenium-side-runner 4.1.0-beta.3 still failed the step:

info: ✕ Fallback demo › type | id=user-name | tomsmith: Operation timed out during type:id=user-name:tomsmith

The source explains why. In @seleniumhq/side-runtime, which both the IDE and the runner use to play tests, the loop over the fallback locators is commented out with the note that fallbacks "create points of user confusion". Only the selected target is used.

What this means in practice:

  • The targets list is a menu for you, not a safety net. When a step fails because the page changed, open the drop-down and pick a locator that still works, or write a better one.
  • Choose a robust target from the start. There is no hidden second chance.
  • Treat "self-healing" claims for recorded tests with care. Some commercial tools do retry alternative locators; open-source Selenium IDE 4 does not.

A developer renamed id="email" to id="user-email". Your step type | id=email now fails, although its stored targets include name=email, which still matches. Why?

The fallback loop is disabled in the version 4 runtime. Switch the target to name=email yourself, or better, ask for a test attribute that will not be renamed.

Locators that work on the grid and on phones#

Two notes for later chapters:

  • Prefer CSS over XPath when you can. CSS selectors are shorter and work the same way in every browser. TestingBot's codeless automation FAQ also recommends CSS selectors when you run recorded tests on mobile browsers.
  • linkText matches the whole visible text. linkText=Logout breaks when the link is renamed to "Log out" or translated. When the copy changes often, a CSS selector on the link's href, such as css=a[href='/logout'], is steadier.

With good targets in place, the next step is checking results without making the test flaky, which is what assertions and waits are for.