Selectors

What are selectors?

Selectors are queries to the Document Object Model that allows to specify DOM items to do interactions and retrieve information. Playwright can use one of four selection engines:

• Text selectors, which selects items based on its text contents and can used like this:

page.$('text="foo"') // selects an element which contains text "foo"
page.$('"foo"') // short form

• CSS selectors, which selects items based on its CSS properties and are used like this:

page.$('css=div') // select a div
page.$('div') // short form

• XPath selectors, which select items based on its XML tree position, and are used like this:

page.$('xpath=//html') // selects the root html element 
page.$('//html') // short form

Selecting many elements

the page.$ function returns, if any, the first element the matches the filter criteria. If many elements are selected, the page.$$ functions returns an array of all matched items

const items = await page.$$('.list-item'); // returns an array
await items[0].click();

• ID selector, which select items based on its id:

page.$('id="foo"') // select element with foo id

Chaining Selectors

Selectors can be combined with the >> operator which searchs for a selector in the context of the previous selection, for example:

page.$('css=article >> css=.bar > .baz >> css=span[attr=value]') 

Selects the span element inside an element with bar class, inside an article.

Examples

const handle = await page.$('css=div');
const handle = await page.$('xpath=//html/body/div');
const handle = await page.$('text="foo"');
const handle = await page.$('xpath=//html/body/div >> css=span');
const handle = await page.$('div');
const handle = await page.$('//html/body/div');
const handle = await page.$('"foo"');
const handle = await divHandle.$('css=span');

Common CSS Selectors

ID and CSS selectors usually are the most used. Here is a list of the most common ones:

Selector Name	Selection
#name	Selects an element by id
.name	Selects an element by class name
type	Selects an element by its type
antecessorSelector selector	Selects an element whose antecessor is antecessorSelector
adjacentSelector + selector	Selects an element immediately preceded by adjacentSelector
antecessorSelector > selector	Selects an element whose direct antecessor is antecessorSelector
type[attribute=value]	Selects an element whose attribute is equal to value
type:not(selector)	Selects all elements except the ones defined by selector
selector:nth-child(number)	Selects the nth child (where n is number) of selector
type:nth-of_type(number)	Selects the nth element (where n is number) of type

Selector Examples

 page.$('#container')
 page.$('.container')
 page.$('div')
 page.$('.container .content')
 page.$('.container > .child')
 page.$('.container + .sibling')
 page.$('.container[title="My title"]')
 page.$('div:not(".error")')
 page.$('span:nth-child(3)')
 page.$('span:nth-of-type(2)')

All selectors can be chained

Element handles

The result of a selection is one or an array of element handles, which represent the actual elements.

You can directly interact with an element handle, but one of the more common uses is to get its text contents with its textContent() function:

const item = await page.$('#text');
const text = await text.textContent();
return text;