An Element Object is an object representing a Element on the remote user agent, e.g. a DOM Node when running a session within a browser or a mobile element for mobile. It can be received using one of the many element query commands, e.g.
An element object has the following properties:
|Session id assigned from the remote server.|
|Associated web element reference that can be used to interact with the element on the protocol level|
|Selector used to query the element.|
|Either the Browser Object when element was fetched from the it (e.g. |
|WebdriverIO options depending on how the browser object was created. See more setup types.|
A element object provides all methods from the protocol section, e.g. WebDriver protocol as well as commands listed within the element section. Available protocol commands depend on the type of session. If you run an automated browser session, none of the Appium commands will be available vice versa.
In addition to that the following commands are available:
|Allows to define custom commands that can be called from the browser object for compisition purposes. Read more in the Custom Command guide.|
|Allows to overwite any browser command with custom functionality. Use carefully as it can confuse framework users. Read more in the Custom Command guide.|
When working with elements WebdriverIO provides special syntax to simplify querying them and composite complex nested element look ups. As element objects allow you to find elements within their tree branch using common query methods, users can fetch nested elements as follows:
const header = await $('#header')
const headline = await header.$('#headline')
console.log(await headline.getText()) // outputs "I am a headline"
With deep nested structures assigning any nested element to an array to then use it can be quite verbose. Therefor WebdriverIO has the concept of chained element queries that allow to fetch nested elements like this:
This also works when fetching a set of elements, e.g.:
// get the text of the 3rd headline within the 2nd header
When working with a set of elements this can especially useful when trying to interact with them, so instead of doing:
const elems = await $$('div')
const locations = await Promise.all(
elems.map((el) => el.getLocation())
You can directly call Array methods on the element chain, e.g.:
const location = await $$('div').map((el) => el.getLocation())
p-iteration under the hood so all commands from their API are also supported for these use cases.
You can set custom commands on the browser scope to abstract away workflows that are commonly used. Check out our guide on Custom Commands for more information.