Selectors
How blocks find elements on a page, how to pick one visually, and why selectors break.
How a block finds an element
Every block that touches the page — click, type, read text — needs to know which element it means. That is what a selector is. Get selectors right and a workflow runs for months; get them wrong and it breaks the first time the site changes a class name.
- CSS selector — the usual choice, and what the picker produces by default.
- XPath — for the cases CSS cannot express, such as matching an element by its text content.
Picking an element
You do not have to write selectors by hand. Open the picker from any selector field, choose a running browser tab, and click the element you want on the page. The picker floats above the browser so you can see both at once, and Escape cancels.
It offers several candidates for the element you clicked rather than one answer, because there is rarely only one right selector. Each candidate shows how many elements it matches and whether it is judged stable.
- Unique — matches exactly one element. This is what you want.
- Multiple — matches several. Fine for a loop over a list, wrong for a single click.
- Stable — built from attributes unlikely to change. An id or a data attribute is stable; a generated class like css-1x7fk2p is not.
Prefer a stable candidate over a short one. A long selector anchored to an id survives a redesign; a short one built from styling classes does not.
Testing before you run
Type or paste a selector into the test box and run it against the live page. It reports how many elements matched, which tells you immediately whether the selector is too broad, too narrow, or wrong. Doing this costs seconds; discovering it inside a failed run costs a lot more.
Waiting for elements
Most selector fields carry a wait option with a timeout. Leave it on. Pages load their content asynchronously, and a block that looks for an element the instant the page opens will often look before that element exists. Waiting is the difference between a workflow that works and one that works only on a fast connection.