Commands, Targets and Locators in Selenium IDE
On this page
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:
-
A test attribute such as
data-test-id="login-button"ordata-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. -
A stable
idorname, likeid=username. Avoid ids that look generated (id=ember1234,id=react-select-3-input): they change between builds. -
The visible text of a link,
linkText=Logout. Readable, but it breaks when the copy or the language changes. -
A short CSS selector on meaningful attributes, such as
css=button[type='submit']orcss=#login button. -
Last resort: positional XPath such as
xpath=//div[2]/div/inputorxpath=//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
targetslist 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.
-
linkTextmatches the whole visible text.linkText=Logoutbreaks when the link is renamed to "Log out" or translated. When the copy changes often, a CSS selector on the link'shref, such ascss=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.