Skip to content

How to Find Elements by CSS Selector in Selenium

CSS selectors are a powerful tool for locating elements on a web page when automating browser testing with Selenium. Using CSS selectors allows you to target elements in a precise and flexible way. In this comprehensive guide, we‘ll cover everything you need to know to become a pro at finding elements by CSS selector in Selenium.

An Introduction to CSS Selectors

CSS selectors allow you to select HTML elements based on id, class, attribute, position in the DOM tree and more. Here are some of the most commonly used CSS selectors:

  • ID selector – Selects an element based on its unique ID. For example #main-header will select the element with id="main-header".

  • Class selector – Selects elements based on the class name. For example .article will select all elements with class="article".

  • Attribute selector – Selects elements based on a certain attribute or attribute value. For example input[type="text"] will select all input elements with type="text".

  • Descendant selector – Selects elements that are descendants of another specified element. For example div p will select all p elements inside div elements.

  • Child selector – Selects elements that are direct children of another specified element. For example div > p will select p elements that are direct children of div.

  • Adjacent sibling selector – Selects the sibling element that immediately follows another element. For example h2 + p will select the p element that comes immediately after an h2 element.

  • General sibling selector – Selects all sibling elements that follow another element. For example h2 ~ p will select all p elements that come after an h2 element.

These are just a few examples of the many CSS selector types. You can combine multiple selectors to target elements in a very specific way.

Finding Elements by CSS Selector in Selenium

Selenium provides two main methods for finding elements using CSS selectors:


This method will return the first matching element.

element = driver.find_element_by_css_selector(‘#main-header‘)


This method will return a list of all matching elements.

elements = driver.find_elements_by_css_selector(‘.article‘)

When using these methods, you pass the CSS selector as a string. Here are some examples of how you would locate elements with different selectors:





By Attribute:



driver.find_element_by_css_selector(‘div#content p.summary‘)


driver.find_element_by_css_selector(‘ >‘) 

Adjacent Sibling:

driver.find_element_by_css_selector(‘h1 + p.intro‘)

General Sibling:

driver.find_element_by_css_selector(‘h2 ~ p.related-posts‘)

As you can see, CSS selectors give you a lot of options for targeting elements in different ways.

Tips for Writing Effective CSS Selectors

Here are some tips to follow when writing CSS selectors for finding elements in Selenium:

  • Be as specific as possible – Use id, class, attributes, and multiple selectors together to precisely target elements. This avoids false positive matches.

  • Prefer class over tag name – Tag names like div, p, a, etc. are not very distinctive. Classes allow more specific targeting.

  • Use unique attributes like name or title – The name and title attributes typically have unique values that can pinpoint a single element.

  • Use sibling selectors carefully – Adjacent and general sibling selectors can match more elements than intended if not written properly.

  • Avoid complex nested selectors – Chaining lots of descendant selectors can make selectors prone to breaking. Try to limit each selector to 3-4 chained levels.

  • Break long selectors into multiple lines – CSS selectors don‘t have to be single line. Breaking them into multiple lines can improve readability.

Following these tips will help you write robust and maintainable CSS selectors for automating web tests.

Common Examples and Use Cases

Now let‘s look at some common examples of how CSS selectors are used for web scraping and browser testing with Selenium:

Selecting navigation links

To select the main navigation links, we can use a class selector:

nav_links = driver.find_elements_by_css_selector(‘ul.main-nav > li > a‘)

Selecting form fields

We can select form input fields based on the input tag and type attribute:

username = driver.find_element_by_css_selector(‘input[type="text"][name="username"]‘)
password = driver.find_element_by_css_selector(‘input[type="password"]‘)

Selecting table rows and columns

CSS selectors make it easy to target specific rows and cells in an HTML table:

# Get second row 
row = driver.find_element_by_css_selector(‘#data-table tr:nth-child(2)‘) 

# Get cell in specific row/column
cell = driver.find_element_by_css_selector(‘#data-table tr:nth-child(2) td:nth-child(3)‘)

Selecting child elements

To select only direct div children of a container, we can use the child selector:

children = driver.find_elements_by_css_selector(‘#container > div‘)

Selecting elements based on text

We can partially match link text using the * selector:

contact_link = driver.find_element_by_css_selector(‘a[href*="contact"]‘]

These examples demonstrate how CSS selectors can be used in real-world test automation scenarios.

Using CSS Selectors in Other Languages

The examples so far have used Python, but CSS selectors can be used in any language bindings for Selenium:


// By.cssSelector 
WebElement element = driver.findElement(By.cssSelector("div.main #login-form"));


// FindElement 
IWebElement element = driver.FindElement(By.CssSelector("div.main #login-form"));


// $ 
const element = await driver.$(‘div.main #login-form‘);

No matter what language you are using, CSS selectors provide a powerful and flexible way to target elements.

Locating Elements by Class Name

A common use case is locating elements by class name. Here are some tips for selecting by class in Selenium:

  • Match the exact class name – driver.find_element_by_class_name(‘primary-btn‘)

  • Use a CSS class selector – driver.find_element_by_css_selector(‘.primary-btn‘)

  • Partial match multiple classes – driver.find_element_by_css_selector(‘.primary.btn‘)

  • Match descendant with class – driver.find_element_by_css_selector(‘div .primary-btn‘)

  • Use multiple classes for uniqueness – driver.find_element_by_css_selector(‘.primary-btn.large‘)

Matching by class name is very useful but be sure to target classes that are unique on the page.

Finding Elements by Tag Name

Locating elements by HTML tag name is another common Selenium task. Here are some examples:

Find first instance of tag name:

element = driver.find_element_by_tag_name(‘button‘) 

Find all instances of tag name:

buttons = driver.find_elements_by_tag_name(‘button‘)

Combine with CSS selector:

submit_btn = driver.find_element_by_css_selector(‘form button[type="submit"]‘)

Since tag names like <div> and <span> are common, try to also use IDs, classes or attributes to uniquely identify the element.

Finding Elements by Name or ID

If elements have id or name attributes, the simplest option is locating by name or ID.

Find by precise ID:

element = driver.find_element_by_id(‘signup-form‘)

Find by exact name:

element = driver.find_element_by_name(‘email‘) 

The ID and name locators will only match the exact attribute values. This makes them very specific but also prone to breaking if IDs or names change.

Finding Elements by XPath vs. CSS Selector

XPath is the other common element location strategy in Selenium. So when should you use XPath vs. CSS selectors?

Here are some differences:

  • Readability – CSS selectors are more readable and easier to understand for most developers.

  • Maintenance – CSS selectors are less brittle and prone to breaking changes compared to long complex XPaths.

  • Capabilities – XPath can access some element properties that CSS selectors cannot, like text content.

  • Performance – CSS selectors are faster for browsers to match compared to complex XPaths.

In general, prefer CSS selectors for maintainability and performance. Only use XPath when needed to access something not possible with CSS.

Best Practices When Using CSS Selectors

Here are some best practices to follow when locating elements with CSS selectors:

  • Favor uniqueness over complexity – Avoid long chains of nested selectors if possible.

  • Use IDs and classes over tag names and nesting.

  • Try to match 3 or fewer chained levels – More levels increases fragility.

  • Avoid universal selectors like * – These are prone to false positive matches.

  • Break long selectors into multiple lines – Improves readability.

  • Cache commonly used selectors – Saves repeated selector lookups.

  • Use descriptive selector names – Helps clarify intent and avoids magic strings.

Following these best practices will help write robust, readable, and reliable CSS selectors for Selenium automation.

Tips for Debugging CSS Selectors

Debugging CSS selectors is an essential skill for test automation. Here are some tips for troubleshooting:

  • Use your browser‘s developer tools to test selectors – Chrome DevTools provides a convenient element inspector.

  • Print and inspect matched elements – After running find_elements(), print the results to see what was matched.

  • Catch NoSuchElementException – Wrap finds in a try/except block to catch when an element is not found.

  • Generate XPath from target element – Many browsers let you copy the XPath, which can help build the CSS selector.

  • Simplify complex selectors – Try removing attributes/classes/nesting until the selector works.

  • Use explicit waits if needed – Dynamic pages may require waits for selectors to become available.

  • Validate selector accuracy – Ensure the selector is actually finding the desired element, not just any element.

Taking the time to carefully debug selectors will pay off through more stable tests.


This guide covered all the key aspects of locating elements by CSS selector in Selenium:

  • CSS selector syntax and types
  • Usage with Selenium‘s find_element methods
  • Writing precise and maintainable selectors
  • Common use cases and examples
  • Comparison to XPath
  • Debugging and best practices

CSS selectors provide a powerful, flexible way to target elements for web scraping and test automation. By mastering the techniques shown here, you can write robust automation scripts that are resistant to changes in the application UI. Proper use of CSS selectors is a must-have skill for any seasoned Selenium engineer.

Join the conversation

Your email address will not be published. Required fields are marked *