Element Selection

/**
 * Find a single element using CSS selector, XPath, or element function
 * @param selector - CSS selector, XPath, or element function
 * @returns Promise resolving to the first matching element
 */
$(selector: Selector): Promise<WebdriverIO.Element>;

/**
 * Find a single element using custom locator strategy
 * @param strategy - Custom locator strategy name
 * @param selector - Selector string for the custom strategy
 * @returns Promise resolving to the first matching element
 */
custom$(strategy: string, selector: string): Promise<WebdriverIO.Element>;

/**
 * Find a single React component by its component name or props
 * @param selector - React component selector (component name or props)
 * @returns Promise resolving to the first matching React component element
 */
react$(selector: string): Promise<WebdriverIO.Element>;

type Selector = string | Function | object;

// CSS selector
const button = await browser.$('#submit-btn');
const input = await browser.$('input[type="email"]');

// XPath selector
const element = await browser.$('//div[@data-testid="user-profile"]');

// Element function
const dynamicElement = await browser.$(() => {
  return document.querySelector('.dynamic-content');
});

// Custom selector strategy
const element = await browser.custom$('accessibility id', 'my-button');

// React component selector
const component = await browser.react$('MyComponent');
const componentWithProps = await browser.react$('Button[disabled=true]');

/**
 * Find multiple elements using CSS selector, XPath, or element function
 * @param selector - CSS selector, XPath, or element function
 * @returns Promise resolving to array of matching elements
 */
$$(selector: Selector): Promise<WebdriverIO.Element[]>;

/**
 * Find multiple elements using custom locator strategy
 * @param strategy - Custom locator strategy name
 * @param selector - Selector string for the custom strategy
 * @returns Promise resolving to array of matching elements
 */
custom$$(strategy: string, selector: string): Promise<WebdriverIO.Element[]>;

/**
 * Find multiple React components by their component name or props
 * @param selector - React component selector (component name or props)
 * @returns Promise resolving to array of matching React component elements
 */
react$$(selector: string): Promise<WebdriverIO.Element[]>;

// Find all list items
const listItems = await browser.$$('li.item');

// Find all buttons with specific attribute
const buttons = await browser.$$('button[data-action]');

// Find multiple React components
const allButtons = await browser.react$$('Button');

// Custom strategy for multiple elements
const elements = await browser.custom$$('class name', 'my-class');

/**
 * Find a single child element within this element's scope
 * @param selector - CSS selector, XPath, or element function
 * @returns Promise resolving to the first matching child element
 */
$(selector: Selector): Promise<WebdriverIO.Element>;

/**
 * Find multiple child elements within this element's scope
 * @param selector - CSS selector, XPath, or element function
 * @returns Promise resolving to array of matching child elements
 */
$$(selector: Selector): Promise<WebdriverIO.Element[]>;

/**
 * Find a single child element using custom locator strategy
 * @param strategy - Custom locator strategy name
 * @param selector - Selector string for the custom strategy
 * @returns Promise resolving to the first matching child element
 */
custom$(strategy: string, selector: string): Promise<WebdriverIO.Element>;

/**
 * Find multiple child elements using custom locator strategy
 * @param strategy - Custom locator strategy name
 * @param selector - Selector string for the custom strategy
 * @returns Promise resolving to array of matching child elements
 */
custom$$(strategy: string, selector: string): Promise<WebdriverIO.Element[]>;

const form = await browser.$('#user-form');

// Find child elements within the form
const emailInput = await form.$('input[name="email"]');
const allInputs = await form.$$('input');
const submitButton = await form.$('button[type="submit"]');

// Chaining element selection
const tableRow = await browser.$('table tbody tr:first-child');
const firstCell = await tableRow.$('td:first-child');

/**
 * Find a single child React component within this element's scope
 * @param selector - React component selector (component name or props)
 * @returns Promise resolving to the first matching child React component
 */
react$(selector: string): Promise<WebdriverIO.Element>;

/**
 * Find multiple child React components within this element's scope
 * @param selector - React component selector (component name or props)
 * @returns Promise resolving to array of matching child React components
 */
react$$(selector: string): Promise<WebdriverIO.Element[]>;

const modal = await browser.$('[data-testid="modal"]');

// Find React components within the modal
const closeButton = await modal.react$('CloseButton');
const allButtons = await modal.react$$('Button');

/**
 * Find a single element within the Shadow DOM of this element
 * @param selector - CSS selector for Shadow DOM element
 * @returns Promise resolving to the first matching Shadow DOM element
 */
shadow$(selector: string): Promise<WebdriverIO.Element>;

/**
 * Find multiple elements within the Shadow DOM of this element
 * @param selector - CSS selector for Shadow DOM elements
 * @returns Promise resolving to array of matching Shadow DOM elements
 */
shadow$$(selector: string): Promise<WebdriverIO.Element[]>;

// Find element with Shadow DOM
const customElement = await browser.$('my-custom-element');

// Access Shadow DOM children
const shadowButton = await customElement.shadow$('button.shadow-btn');
const allShadowElements = await customElement.shadow$$('.shadow-content');

/**
 * Get the parent element of this element
 * @returns Promise resolving to the parent element
 */
parentElement(): Promise<WebdriverIO.Element>;

/**
 * Get the next sibling element
 * @returns Promise resolving to the next sibling element
 */
nextElement(): Promise<WebdriverIO.Element>;

/**
 * Get the previous sibling element
 * @returns Promise resolving to the previous sibling element
 */
previousElement(): Promise<WebdriverIO.Element>;

const listItem = await browser.$('li.selected');

// Navigate to related elements
const parentList = await listItem.parentElement();
const nextItem = await listItem.nextElement();
const prevItem = await listItem.previousElement();

const W3C_SELECTOR_STRATEGIES: {
  'css selector': string;
  'link text': string;
  'partial link text': string;
  'tag name': string;
  'xpath': string;
};

// ID selector
await browser.$('#my-id');

// Class selector
await browser.$('.my-class');

// Attribute selectors
await browser.$('[data-testid="submit"]');
await browser.$('input[type="email"]');

// Pseudo-selectors
await browser.$('tr:first-child');
await browser.$('option:checked');

// Complex selectors
await browser.$('form .input-group input[required]');

// XPath with attributes
await browser.$('//button[@data-action="submit"]');

// XPath with text content
await browser.$('//a[contains(text(), "Click here")]');

// XPath with position
await browser.$('//table//tr[2]/td[3]');

// XPath with multiple conditions
await browser.$('//input[@type="text" and @required]');

// Simple element function
await browser.$(() => document.getElementById('dynamic-id'));

// Complex element function with logic
await browser.$(() => {
  const elements = document.querySelectorAll('.item');
  return Array.from(elements).find(el => 
    el.textContent.includes('specific text')
  );
});

// Element function with parameters
const searchTerm = 'example';
await browser.$((term) => {
  return document.querySelector(`[data-search="${term}"]`);
}, searchTerm);

// Component by name
await browser.react$('MyComponent');

// Component with props
await browser.react$('Button[disabled=true]');
await browser.react$('Input[type="email"]');

// Nested component selection
await browser.react$('Form').react$('SubmitButton');