These guidelines should help you to write high quality selectors.

Selectors SHOULD be written in CSS instead of XPath whenever possible

CSS is generally easier to read than XPath. For example, //*[@id="foo"] in XPath can be expressed as simply as #foo in CSS. See this XPath Cheatsheet for more examples.

XPath selectors SHOULD NOT use @attribute="foo".

This would fail if the attribute was attribute="foo bar". Instead you SHOULD use contains(@attribute, "foo") where @attribute is any valid attribute such as @text or @class.

CSS and XPath selectors SHOULD be implemented in their most simple form

  • GOOD: #foo
  • BAD: button[contains(@id, "foo")]

CSS and XPath selectors SHOULD avoid making use of hardcoded indices

Instead you SHOULD parameterize the selector.

  • GOOD: .foo:nth-of-type()
  • BAD: .foo:nth-of-type(1)

  • GOOD: button[contains(@id, "foo")][]
  • BAD: button[contains(@id, "foo")][1]

  • GOOD: #actions____aggregator
  • BAD: #actions__1__aggregator

CSS and XPath selectors MUST NOT reference the @data-bind attribute

The @data-bind attribute is used by KnockoutJS, a framework Magento uses to create dynamic Javascript pages. Since this @data-bind attribute is tied to a specific framework, it should not be used for selectors. If Magento decides to use a different framework then these @data-bind selectors would break.