Selecting Elements in WebdriverIO

WebdriverIO offers a variety of ways to "select" elements on a webpage. While the basic method of using simple CSS selectors will work for 75% of your needs, sometimes you require a more advanced technique.

The two main types are either XPath or CSS selectors; and truthfully either one works. CSS selectors are normally more brief than XPath, but sometimes they're not as powerful. Which one you use is really a matter of what you're more comfortable with. Front-end developers are likely more familiar with CSS selectors, so I lean that way. Because of that, most of the examples in this article will use CSS selectors.

Before I get started though, I do want to mention that I've got an in-depth course on WebdriverIO available for those interested. Okay, on to the important stuff!

Code Example

To showcase the different selectors strategies, we'll be using the following HTML for our elements:

<ul class="items" dropdown-menu>
	<li class="item">
		<a ng-click="showProjects()">
	<li class="item">
		<a ng-click="showArchive()">

Say you want to select the "Projects" link. In this example, a simple .items .item a selector won't work, as that will also target the "Archive" link. Let's take a look at other ways you can grab the correct link.

Attribute Selectors

The first method we'll try is called "Attribute Selectors". Attributes are the properties of HTML elements (e.g. the "class" part of <li class="item">). These attributes can be helpful for singling out specific elements.

Using CSS Attribute Selectors (shorter version), we can target the ng-click attribute of the link, like so:


Notice how the selector includes both the attribute and its value. You don't have to include both, but for our needs we needed to target the element with that specific ng-click value.

We can also combine attribute selectors to be more specific with our link:

browser.element("[dropdown-menu] a[ng-click='showProjects()']");

That selector asks for a link with an attribute of ng-click and an attribute value of showProjects() that is the child of an element with an attribute of dropdown-menu.

nth-child Selectors

Another method to find your element is to base it on the position in the HTML. The first-child selector allows us to do this:


That will select any link (<a>) that is the first child of its parent. That's a pretty broad selector though, so we should narrow this down to our dropdown using the attribute selector from before:

browser.element("[dropdown-menu]  a:first-child");

What if we wanted to get the second child? We can use The nth-child selector:

browser.element("[dropdown-menu]  a:nth-child(2)");

nth-child takes a numeric value, which corresponds to the position in the HTML.

nth-child can get pretty complicated and is a very powerful selector. There are also related selectors like nth-of-type or nth-last-child. and CSS-Tricks go in to more detail on it.

Text based selectors

Sometimes we don't care about the HTML at all and are more focused on the content itself. In those instances, we can use text matching to find our elements.

The WebdriverIO docs go in to good detail on selecting by element text, but I think it's worth it to show it for our example:


We can narrow it down to the dropdown menu by chaining selectors:


Because selecting by text is a special type of selector not official supported by CSS, you cannot do the following:

browser.element("[dropdown-menu] =Projects");

It simply won't know what you mean.

Building and testing selectors

The Chrome Developer tools can help evaluate and validate XPath/CSS selectors. This is a useful tool for building and testing selectors.

More Selectors!

We only covered a few types of advanced CSS selectors here, but there are many, many more. Sauce Labs covers some common CSS/Xpath selectors and CSS Tricks has an almanac of all the selectors available.

More WebdriverIO!

I have a WebdriverIO video course available if you'd like an in-depth guide to WebdriverIO.