Exit course
Chapter 3 of 12 Intermediate 6 min read 2 quick checks Updated

Inspect the DOM and Test Selectors in DevTools

On this page
  1. Inspect the element, then read around it
  2. Search the Elements panel
  3. Test selectors in the Console
  4. "Copy selector" and "Copy XPath" are a starting point
  5. The same check from your test code
  6. Playwright's picker
  7. Summary

Writing a locator in your editor, running the test and waiting for NoSuchElementException is a slow way to find out it was wrong. Every browser ships a faster loop: the developer tools. This chapter uses Chrome DevTools; Firefox and Edge have the same features under nearly the same names.

Inspect the element, then read around it#

Right-click the element and choose Inspect. DevTools opens the Elements panel with the element selected. Before you copy anything, read the markup around it and look for the most meaningful handle:

  • Is there a data-testid, data-test or data-qa attribute? That is the best candidate (chapter 6).
  • Does it have a visible label, or is it a button or link with text? Then a role or label locator will work (chapter 5).
  • Does it have an id or name that a human wrote, such as id="username", rather than id="input-4821"?
  • If none of these: what is the nearest ancestor that does have a good handle, so you can scope from there?

The Accessibility pane in the Elements panel shows the element's computed role and accessible name: the values getByRole matches on. If the name there is empty, a role locator cannot find the element by name, and that is worth reporting to the developers as an accessibility bug as well.

Search the Elements panel#

With the Elements panel focused, press Ctrl+F (Cmd+F on macOS). The search box accepts plain text, a CSS selector or an XPath expression, and shows "1 of 4" next to it. That count is the first thing to check: a locator for a single element should give exactly one match. Two or more means the test will act on whichever comes first in the document, which may not be the one you meant.

Test selectors in the Console#

The Console has helper functions that are only available when you type there (they are not part of the page's JavaScript):

Helper Returns
$$('css selector') an array of all matching elements
$x('xpath expression') an array of all matching nodes
$0 the element currently selected in the Elements panel

On the data tables page, https://the-internet.herokuapp.com/tables, try:

$$('#table2 td.email').length
// 4
$$('#table2 td.email').map(td => td.textContent)
// ['jsmith@gmail.com', 'fbach@yahoo.com', 'jdoe@hotmail.com', 'tconway@earthlink.net']
$x("//table[@id='table1']//td[text()='jdoe@hotmail.com']").length
// 1
$x("//table[@id='table1']//td[text()='jdoe@hotmail.com']/..")[0].children[0].textContent
// 'Doe'

Because the results are real arrays of elements, you can check not only how many matched but which ones, which is how you catch a selector that matches four cells when you meant one.

Two caveats:

  • $ is often taken. That page loads jQuery, so $('#table1') there is jQuery's function, not the DevTools helper. $$ and $x are rarely overridden, so prefer them. If you need the standard browser API, document.querySelectorAll(...) and document.evaluate(...) always work.
  • The console does not look inside shadow roots. On a page that renders its inputs inside a web component, $$('input') returns an empty array even though you can see the input. Chapter 7 shows how both frameworks handle this.

You type $$('button.primary') in the Console and get an array of three buttons. The test should click the "Pay now" button. What do you do?

find_element returns the first match in document order, whether or not it is visible, so three matches is a bug waiting to happen. A position fixes today's page and breaks when a button is added. Find a property that only that button has.

"Copy selector" and "Copy XPath" are a starting point#

Right-click a node in the Elements panel and choose Copy > Copy selector or Copy XPath. DevTools generates something that is unique today, and it gets there the cheapest way it can: an id if there is one (generated or not), otherwise a chain of :nth-child() steps or positional XPath. "Copy full XPath" is the worst of them, an absolute path from /html.

Treat the generated value as a pointer to the element, then rewrite it by hand using the handles you found when you read the markup. A rule that works well: if you would not be able to explain the locator to a colleague in one sentence ("the email cell in the row for Jason Doe"), rewrite it.

The same check from your test code#

When a locator misbehaves in a test, assert on the count instead of guessing:

from selenium.webdriver.common.by import By

matches = driver.find_elements(By.CSS_SELECTOR, "#table2 td.email")
assert len(matches) == 4, [m.text for m in matches]

find_elements returns a possibly empty list and never raises, so the assertion message shows exactly what matched. In Playwright, await expect(locator).toHaveCount(1) does the same, and Playwright's strict mode refuses to click or fill a locator that matches more than one element at all (chapter 5).

Playwright's picker#

Playwright has its own inspector that suggests locators, preferring test ids, roles, labels and text over CSS:

npx playwright codegen https://the-internet.herokuapp.com/login

Hover over an element and Playwright highlights it with the locator it would use; with Pick locator you click an element and get that locator in the inspector to copy. The suggestions are good, but they are suggestions: check that the text they rely on is stable, and prefer a test id where the copy is likely to change.

"Copy selector" in DevTools gives you #root > div > div:nth-child(2) > form > div:nth-child(3) > input. Why should this not go into a test unchanged?

The generated selector is unique today, and every combinator and pseudo-class in it works in all browsers. The problem is what it depends on: three positions and five levels of nesting, none of which say what the input is.

Summary#

  • Read the markup around an element before copying anything, and look for test ids, labels, roles and human-written ids.
  • In the Elements panel search and with $$ and $x in the Console, check that a locator matches exactly the elements you mean.
  • Generated selectors are a pointer, not a locator; rewrite them.
  • Our XPath and CSS selector tester does the same check on pasted HTML when you do not have the page open.