Implementation:Webdriverio Webdriverio Url Dollar DollarDollar Commands

Overview

The url(), $(), and $$() commands are the concrete tools provided by the WebdriverIO library for navigating to URLs and querying DOM elements. Together they form the primary navigation and element interaction API used in every WebdriverIO test.

Description

These three commands provide the core navigation and element interaction capabilities:

• url(): Navigates the browser to a given URL. Respects the configured baseUrl for relative URL resolution. When using WebDriver BiDi, it supports advanced options including custom wait states (none, interactive, complete, networkIdle), custom request headers, basic authentication, and onBeforeLoad hooks for environment mocking.

• $(): Finds a single element matching a selector. Returns a ChainablePromiseElement that allows fluent chaining of further queries and actions without intermediate await calls. When using WebDriver BiDi, performs a deep lookup that traverses shadow DOM boundaries.

• $$(): Finds all elements matching a selector. Returns a ChainablePromiseArray with support for array indexing, async iterators (for await...of), and chained sub-queries. Also supports deep lookups via BiDi.

Both $ and $$ support multiple selector strategies: CSS selectors, XPath expressions, text content (e.g., =Link Text), partial text (e.g., *=Partial), accessibility ID, tag name, element reference objects, custom strategy functions, and HTMLElement instances (in browser runner).

Source Locations

Command	File	Lines
url()	packages/webdriverio/src/commands/browser/url.ts	L159-290
$()	packages/webdriverio/src/commands/browser/$.ts	L68-100
$$()	packages/webdriverio/src/commands/browser/$$.ts	L49-96

Repository: https://github.com/webdriverio/webdriverio

Signatures

// url command
async function url(
    this: WebdriverIO.Browser,
    path: string,
    options?: UrlCommandOptions
): Promise<WebdriverIO.Request | void>

// $ command (single element)
async function $(
    this: WebdriverIO.Browser | WebdriverIO.Element,
    selector: Selector
): Promise<WebdriverIO.Element>

// $$ command (multiple elements)
async function $$(
    this: WebdriverIO.Browser | WebdriverIO.Element,
    selector: Selector | ElementReference[] | WebdriverIO.Element[] | HTMLElement[]
): Promise<WebdriverIO.ElementArray>

Where the key types are defined as:

type Selector = string | ElementReference | ElementFunction | CustomStrategyReference | HTMLElement

interface UrlCommandOptions {
    wait?: 'none' | 'interactive' | 'complete' | 'networkIdle'
    headers?: Record<string, string>
    auth?: { user: string; pass: string }
    timeout?: number
    onBeforeLoad?: () => unknown
}

Import

// In standalone mode, available as methods on the browser instance
const browser = await remote({ capabilities: { browserName: 'chrome' } })
await browser.url('https://example.com')
const elem = await browser.$('#myId')
const elems = await browser.$$('.myClass')

// In testrunner mode, $ and $$ are available as globals
await browser.url('https://example.com')
const elem = await $('#myId')
const elems = await $$('.myClass')

Inputs

Command	Parameter	Type	Required	Description
url()	path	string	Yes	The URL to navigate to. Resolved against baseUrl if configured.
url()	options	UrlCommandOptions	No	Navigation options including wait state, headers, auth, timeout, and onBeforeLoad hook. Requires WebDriver BiDi.
$()	selector	Selector	Yes	CSS selector, XPath, text selector, accessibility ID, element reference, custom strategy, or HTMLElement.
$$()	selector	ElementReference[] | WebdriverIO.Element[] | HTMLElement[]	Yes	Same as $, plus arrays of element references or HTMLElements for batch conversion.

Outputs

Command	Return Type	Description
url()	void>	When using BiDi, returns a Request object containing URL, response status, headers, cookies, redirect chain, and child requests. Returns void when using WebDriver Classic.
$()	Promise<WebdriverIO.Element>	A ChainablePromiseElement wrapping the found element. Supports chaining further $/$$ calls and element commands (click, getValue, getText, etc.) without intermediate awaits.
$$()	Promise<WebdriverIO.ElementArray>	A ChainablePromiseArray containing all matching elements. Supports array indexing, async iterators (for await...of), and chained sub-queries.

Usage Example

import { remote } from 'webdriverio'

const browser = await remote({
    capabilities: { browserName: 'chrome' }
})

try {
    // Navigate to a URL
    const request = await browser.url('https://webdriver.io')
    console.log('Status:', request?.response?.status) // 200

    // Find a single element by CSS selector and click it
    const apiLink = await browser.$('=API')
    await apiLink.click()

    // Find multiple elements and iterate
    const items = await browser.$$('.nav-item')
    console.log('Nav items found:', items.length)

    for await (const item of items) {
        console.log(await item.getText())
    }

    // Chain selectors without intermediate awaits
    const imgSrc = await browser.$$('div')[0].$('img').getAttribute('src')
    console.log('Image source:', imgSrc)

    // Use XPath selector
    const heading = await browser.$('//h1')
    console.log('Heading:', await heading.getText())

    // Use text selector
    const link = await browser.$('=Get Started')
    await link.click()
} finally {
    await browser.deleteSession()
}

Internal Flow

url()

1. Validates that path is a string.
2. Resolves against baseUrl using new URL(path, baseUrl).
3. If BiDi is available and the URL starts with http:
   • Sets up onBeforeLoad preload script if provided.
   • Configures authentication headers if auth is specified.
   • Sets up request mocking for custom headers.
   • Calls browsingContextNavigate() with the computed wait state.
   • If networkIdle wait is requested, polls pending requests until none remain.
   • Returns the request/response metadata.
4. If BiDi is not available, falls back to this.navigateTo() (WebDriver Classic).

$()

1. In browser runner context, delegates to globalThis.wdio.execute('$', selector).
2. If selector is an element reference object, converts it directly via getElement().
3. Otherwise, calls findElement() which resolves the selector strategy and issues the protocol command.
4. Wraps the result in a ChainablePromiseElement via getElement().

$$()

1. If BiDi is available and selector is a string, performs a deep element lookup via findDeepElements().
2. Otherwise, calls findElements() for protocol-level multi-element lookup.
3. Supports arrays of element references or HTMLElements for batch conversion.
4. Wraps results in a ChainablePromiseArray via enhanceElementsArray().

Related Pages

• implements Principle:Webdriverio_Webdriverio_Browser_Navigation_and_Interaction - The Browser Navigation and Interaction principle that these commands implement.
• Environment:Webdriverio_Webdriverio_Node_Runtime_Environment
• Environment:Webdriverio_Webdriverio_Browser_Driver_Environment
• Heuristic:Webdriverio_Webdriverio_Click_Interception_Workaround
• Heuristic:Webdriverio_Webdriverio_Mobile_Platform_Differences