# Selectors What is a selector? Human users just see the page and use their intelligent brains to **find the right element to interact with**. Computers on the contrary need more specific instructions to know what to click. **"Selector" is a way of describing a specific element on your page that can be clearly identified.** For example, a *selector* can describe an instruction to `Find an element with a text "Add to cart"` or `Find the first element with id "primary-button-submit"` ## Automatic vs. manual selectors **Automatic selectors** --> BugBug creates them automatically when your [record a test](https://docs.bugbug.io/recording-tests-steps) **Manual selectors** --> You create them on your own using your own human intelligence. Sometimes manual selectors is the only way of creating a reliable automation testing {% hint style="info" %} **See** [**our simple tool for building XPath selectors without code -->**](https://bugbug.io/xpath-selector-builder/?ref=docs) ![](https://3168433179-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MKixgeBPbLvnD0l1eiV%2Fuploads%2FeZuqZJE019x7Mf3MJLz7%2FScreen%20Shot%202022-11-03%20at%2011.37.32.png?alt=media\&token=258375ab-7891-4507-baac-7e9282d965f8) {% endhint %} ## Automatic selectors If you are recording the tests, you don't need to be worried about selectors too much. During the recording, BugBug will automatically create several selectors and decide which is the best.

Selector generated by BugBug during recording session

## Manual selectors You can also enter your own custom XPath or CSS selector. In the details of selected test step click on existing selector and select "Customize" option (last position).

BugBug can understand selectors in the following formats: * CSS selectors, for example `[id="submit"]` * XPath selectors, for example `//*[@id="submit"]` Manual selectors sometimes is the best way of creating stable automated tests in complex apps. For example you if you have a long table with buttons inside each row, you may need to create a selector that first points to the right row and then to the right action button. {% hint style="info" %} **Learn the basics of HTML** To write reliable selectors you need a basic knowledge of HTML and understand what are *tags*, *attributes*, *parents* and *children*. You can learn it in our **extensive tutorial in the** [**no-code XPath selector tool**](https://bugbug.io/xpath-selector-builder/?ref=docs). {% endhint %} ### Nested selectors BugBug allows you to create nested selectors. This is especially helpful when dealing with dynamic table data or nested iframes. Each selector narrows down the context, which gives the superpower to make the right selector for an element. In the below example, BugBug will first narrow down the context of the document with `//*[@data-testid="todo-list"]` and then will find a **child** of this element using the next selector `//li`

The right box is the parent selector, the pink box is the child selector.

In nested selectors, you can refer to **parent**, **child,** or **sibling**.

If you want to read more about XPath and selectors in general you can check out our [BugBug Selector Builder](https://bugbug.io/xpath-selector-builder/). ## Set priority of automatic selectors You can decide about the priorities of automatic selectors and configure your custom attributes in [project settings](https://docs.bugbug.io/preventing-failed-tests/project-settings). This is an advanced setting and usually there's no need to change it. ![](https://3168433179-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MKixgeBPbLvnD0l1eiV%2Fuploads%2FbKFwKP65w8x8P8EFDIwk%2FScreenshot%202022-04-11%20at%2019.08.53.png?alt=media\&token=b921d690-19d8-4fe0-bb3f-d73f1657cd94) ## Use custom attributes for selectors To create robust tests, your app should be coded with additional special attributes that are dedicated to testing automation. The usual convention is to use `data-test` or `data-testid` attributes. BugBug will automatically prioritize such robust selectors when it recognizes them. So if you're working on a complex app, **we highly recommend** that you talk to your front-end developers and ask them to add such attributes. This will also make their life easier because they will see from the code that an element is a subject of testing automation. ![](https://3168433179-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MKixgeBPbLvnD0l1eiV%2Fuploads%2Fmx9CxOn0e8vCLzp4TkuR%2Fimage.png?alt=media\&token=46bb80ef-54b1-47fe-a446-b0555c9bdccd) ## The "element not found" error When your test fails with an error "element not found" or "element not visible", this might be caused by an incorrect [selector](https://docs.bugbug.io/preventing-failed-tests/selectors). Common problems with selectors are: * It is too specific, contains some kind of unique ID that is changing every time you run the test * It is depending on the order of elements, but the order of elements changes, like a list of products in e-commerce might change every day (you can avoid this problem by [building a selector manually](#automatic-vs.-manual-selectors)) * It is pointing to more than one element and some of them are not visible (for example your page has some hidden buttons with `display: none`) * the text in your app changed and you were using a [text-based selector](#fix-text-based-selectors) ![](https://3168433179-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MKixgeBPbLvnD0l1eiV%2Fuploads%2Fg89baEK9bYPbv1mpau8R%2FScreenshot%202022-04-12%20at%2010.41.05.png?alt=media\&token=fc38bccf-7ae8-4d94-a7e5-3b057861839c) ## Tips on fixing selectors ### Use Chrome debugging Chrome is very powerful in debugging and it's worth learning [how to use Chrome developer features](https://docs.bugbug.io/debugging-tests/debug-in-chrome). ### Copy selector to clipboard * Click the button near the selector field * Open Chrome dev tools * Click cmd+f * Paste the selector in the search field * Chrome will highlight the element that is matching your selector * If no element is matched, you may try to manually update the selector or just [re-record the step](https://docs.bugbug.io/recording-tests-steps/re-recording-steps) ![](https://3168433179-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MKixgeBPbLvnD0l1eiV%2Fuploads%2FIQWcH0gfKFjVCiLjJZKu%2Fimage.png?alt=media\&token=708489b4-a602-434d-9470-d45dbc0e9288) ![](https://3168433179-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MKixgeBPbLvnD0l1eiV%2Fuploads%2Fo3cyOjY3FqlMkG7qKgo7%2FScreenshot%202022-04-12%20at%2010.49.54.png?alt=media\&token=4aa112e2-757b-4226-87b4-3e1958b02496) ### Prevent incorrect selectors Prevent failed tests by using [custom attributes for selectors](#use-custom-attributes-for-selectors) ### Fix text-based selectors Some selectors are just finding any element that contains a specific text. Here's an example of such a selector: `//DIV[normalize-space(text())="Create account in Example Project"]` {% hint style="info" %} **Tip:** you can [use variables in selectors](https://docs.bugbug.io/editing-tests/variables#using-text-variables) {% endhint %} If this text changes in your app, you will get an "element not found" error. The element is in fact still there, but the selector does not work anymore. You can [manually update](https://docs.bugbug.io/editing-tests/manually-creating-the-test) the selector or [re-record this step](https://docs.bugbug.io/recording-tests-steps/re-recording-steps). --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.bugbug.io/preventing-failed-tests/selectors.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.