Skip to main content

$

Overview​

Use the $ command instead of findElement as a shorter command to get a single element on the page.

The $ command returns an object describing the element, on which you can call action commands without passing the selector. However, if you do pass a selector, it will first find the corresponding element and then call the action for that element. You can also pass an object as the selector, where the object contains the property element-6066-11e4-a52e-4f735466cecf with the value of the element reference. The command then converts the reference into an extended WebdriverIO element. Note: Use these element objects only if you are certain they exist on the page. This can be verified, for example, using the isExisting command.

You can chain $ or $$ together to navigate down the DOM tree. But note that chaining $ and $$ commands makes sense only when using multiple selector strategies. Otherwise, you will be making unnecessary requests that will slow down the test (e.g., $('body').$('div') creates two requests, whereas $('body div') does the same in one request).

info

Read more about how to select specific elements in the recipe "How to use selectors".

Usage​

await browser.$(selector);

Command Parameters​

NameTypeDescription
selectorString or Function or MatcherSelector, JS function, or Matcher object to get a specific element.

Usage Examples​

index.html

<ul id="menu">
    <li>
        <a href="/">Home</a>
    </li>
    <li>
        <a href="/">Developer Guide</a>
    </li>
    <li>
        <a href="/">API</a>
    </li>
    <li>
        <a href="/">Contribute</a>
    </li>
</ul>
it("should get text of a menu link - JS Function", async ({ browser }) => {
    const text = await browser.$("#menu");

    console.log(
        await text
            .$$("li")[2]
            .$(function () {
                // Arrow function cannot be used here.
                // This is Element – https://developer.mozilla.org/en-US/docs/Web/API/Element
                // in this specific example – this is HTMLLIElement
                //
                // TypeScript users can do something like:
                // return (this as Element).querySelector('a')
                return this.querySelector("a"); // Element
            })
            .getText(),
    ); // outputs: "API"
});

it("should get text of a menu link", async ({ browser }) => {
    const text = await browser.$("#menu");

    console.log(await text.$$("li")[2].$("a").getText()); // outputs: "API"
});

it("should allow to convert protocol result of an element into a WebdriverIO element", async ({
    browser,
}) => {
    const activeElement = await browser.getActiveElement();

    console.log(await browser.$(activeElement).getTagName()); // outputs the active element
});

it("should use Android's DataMatcher or ViewMatcher selector", async ({ browser }) => {
    const menuItem = await browser.$({
        name: "hasEntry",
        args: ["title", "ViewTitle"],
        class: "androidx.test.espresso.matcher.ViewMatchers",
    });
    await menuItem.click();

    const menuItem = await browser.$({
        name: "hasEntry",
        args: ["title", "ViewTitle"],
    });
    await menuItem.click();
});

References​

We'd like to give credit to the original WebdriverIO docs article, from which we drew some information while writing our version.