Element Interaction

/**
 * Find single element by selector
 * @param selector - CSS selector or XPath
 * @returns Promise resolving with element
 */
browser.findElement(selector: string): Promise<WebElement>;

/**
 * Find multiple elements by selector
 * @param selector - CSS selector or XPath
 * @returns Promise resolving with array of elements
 */
browser.findElements(selector: string): Promise<WebElement[]>;

/**
 * Create element wrapper for chaining operations
 * @param selector - CSS selector or XPath
 * @returns Element wrapper instance
 */
browser.element(selector: string): Element;

/**
 * Create elements collection wrapper
 * @param selector - CSS selector or XPath
 * @returns Elements collection wrapper
 */
browser.elements(selector: string): Elements;

/**
 * Find child element by parent element ID
 * @param id - Parent element WebDriver ID
 * @param selector - Child element selector
 * @returns Promise resolving with child element
 */
browser.elementIdElement(id: string, selector: string): Promise<WebElement>;

/**
 * Find child elements by parent element ID
 * @param id - Parent element WebDriver ID
 * @param selector - Child elements selector
 * @returns Promise resolving with array of child elements
 */
browser.elementIdElements(id: string, selector: string): Promise<WebElement[]>;

// Find single element
browser.findElement("#login-button").then(button => {
  console.log("Found login button");
});

// Find multiple elements
browser.findElements(".menu-item").then(items => {
  console.log(`Found ${items.length} menu items`);
});

// Use element wrapper
const loginForm = browser.element("#login-form");

/**
 * Click element at selector
 * @param selector - Element selector
 * @returns Promise resolving when click completes
 */
browser.click(selector: string);

/**
 * Double-click element
 * @param selector - Element selector
 * @returns Promise resolving when double-click completes
 */
browser.doubleClick(selector: string);

/**
 * Right-click element
 * @param selector - Element selector
 * @returns Promise resolving when right-click completes
 */
browser.rightClick(selector: string);

/**
 * Click and hold element
 * @param selector - Element selector
 * @returns Promise resolving when click-and-hold completes
 */
browser.clickAndHold(selector: string);

/**
 * Send keystrokes to element
 * @param selector - Element selector
 * @param keys - Keys to send
 * @returns Promise resolving when keys sent
 */
browser.sendKeys(selector: string, keys: string | string[]);

/**
 * Clear element input value
 * @param selector - Element selector
 * @returns Promise resolving when value cleared
 */
browser.clearValue(selector: string);

/**
 * Set element input value
 * @param selector - Element selector
 * @param value - Value to set
 * @returns Promise resolving when value set
 */
browser.setValue(selector: string, value: string);

/**
 * Update element value (clears then sets)
 * @param selector - Element selector
 * @param value - Value to update
 * @returns Promise resolving when value updated
 */
browser.updateValue(selector: string, value: string);

/**
 * Set password field value (secure input)
 * @param selector - Password field selector
 * @param password - Password to set
 * @returns Promise resolving when password set
 */
browser.setPassword(selector: string, password: string);

/**
 * Submit form containing element
 * @param selector - Form or form element selector
 * @returns Promise resolving when form submitted
 */
browser.submitForm(selector: string);

/**
 * Upload file to input element
 * @param selector - File input selector
 * @param filepath - Path to file to upload
 * @returns Promise resolving when file uploaded
 */
browser.uploadFile(selector: string, filepath: string);

// Basic interactions
browser.click("#submit-button");
browser.setValue("input[name='username']", "testuser");
browser.clearValue("input[name='search']");

// Form submission
browser.setValue("#username", "user");
browser.setValue("#password", "pass");
browser.submitForm("#login-form");

// File upload
browser.uploadFile("input[type='file']", "/path/to/document.pdf");

/**
 * Check if element is visible
 * @param selector - Element selector
 * @returns Promise resolving with visibility boolean
 */
browser.isVisible(selector: string): Promise<boolean>;

/**
 * Check if element exists in DOM
 * @param selector - Element selector
 * @returns Promise resolving with presence boolean
 */
browser.isPresent(selector: string): Promise<boolean>;

/**
 * Check if element is enabled for interaction
 * @param selector - Element selector
 * @returns Promise resolving with enabled boolean
 */
browser.isEnabled(selector: string): Promise<boolean>;

/**
 * Check if element is selected (checkboxes/radio buttons)
 * @param selector - Element selector
 * @returns Promise resolving with selected boolean
 */
browser.isSelected(selector: string): Promise<boolean>;

// Check element states
browser.isVisible("#modal").then(visible => {
  if (visible) {
    browser.click("#modal .close-button");
  }
});

browser.isEnabled("#submit-button").then(enabled => {
  if (enabled) {
    browser.click("#submit-button");
  }
});

/**
 * Get element text content
 * @param selector - Element selector
 * @returns Promise resolving with text content
 */
browser.getText(selector: string): Promise<string>;

/**
 * Get element input value
 * @param selector - Element selector
 * @returns Promise resolving with input value
 */
browser.getValue(selector: string): Promise<string>;

/**
 * Get element attribute value
 * @param selector - Element selector
 * @param attribute - Attribute name
 * @returns Promise resolving with attribute value
 */
browser.getAttribute(selector: string, attribute: string): Promise<string>;

/**
 * Set element attribute
 * @param selector - Element selector
 * @param attribute - Attribute name
 * @param value - Attribute value
 * @returns Promise resolving when attribute set
 */
browser.setAttribute(selector: string, attribute: string, value: string);

/**
 * Get CSS property value
 * @param selector - Element selector
 * @param property - CSS property name
 * @returns Promise resolving with property value
 */
browser.getCssProperty(selector: string, property: string): Promise<string>;

/**
 * Get DOM property value
 * @param selector - Element selector
 * @param property - Property name
 * @returns Promise resolving with property value
 */
browser.getElementProperty(selector: string, property: string): Promise<any>;

/**
 * Get element tag name
 * @param selector - Element selector
 * @returns Promise resolving with tag name
 */
browser.getTagName(selector: string): Promise<string>;

/**
 * Get element accessible name
 * @param selector - Element selector
 * @returns Promise resolving with accessible name
 */
browser.getAccessibleName(selector: string): Promise<string>;

/**
 * Get element ARIA role
 * @param selector - Element selector
 * @returns Promise resolving with ARIA role
 */
browser.getAriaRole(selector: string): Promise<string>;

// Get element properties
browser.getText("#status-message").then(message => {
  console.log("Status:", message);
});

browser.getAttribute("img", "src").then(src => {
  console.log("Image source:", src);
});

browser.getCssProperty("#header", "background-color").then(color => {
  console.log("Header color:", color);
});

/**
 * Get element dimensions
 * @param selector - Element selector
 * @returns Promise resolving with size object
 */
browser.getElementSize(selector: string): Promise<{width: number, height: number}>;

/**
 * Get element rectangle properties
 * @param selector - Element selector
 * @returns Promise resolving with rectangle object
 */
browser.getElementRect(selector: string): Promise<{x: number, y: number, width: number, height: number}>;

/**
 * Get element position coordinates
 * @param selector - Element selector
 * @returns Promise resolving with position object
 */
browser.getLocation(selector: string): Promise<{x: number, y: number}>;

/**
 * Get element position in viewport
 * @param selector - Element selector
 * @returns Promise resolving with viewport position
 */
browser.getLocationInView(selector: string): Promise<{x: number, y: number}>;

// Get element geometry
browser.getElementSize("#sidebar").then(size => {
  console.log(`Sidebar: ${size.width}x${size.height}`);
});

browser.getLocation("#button").then(pos => {
  console.log(`Button at: ${pos.x}, ${pos.y}`);
});

/**
 * Get first child element
 * @param selector - Parent element selector
 * @returns Promise resolving with first child element
 */
browser.getFirstElementChild(selector: string): Promise<WebElement>;

/**
 * Get last child element
 * @param selector - Parent element selector
 * @returns Promise resolving with last child element
 */
browser.getLastElementChild(selector: string): Promise<WebElement>;

/**
 * Get next sibling element
 * @param selector - Element selector
 * @returns Promise resolving with next sibling element
 */
browser.getNextSibling(selector: string): Promise<WebElement>;

/**
 * Get previous sibling element
 * @param selector - Element selector
 * @returns Promise resolving with previous sibling element
 */
browser.getPreviousSibling(selector: string): Promise<WebElement>;

/**
 * Check if element has child elements
 * @param selector - Element selector
 * @returns Promise resolving with boolean indicating children presence
 */
browser.hasDescendants(selector: string): Promise<boolean>;

/**
 * Get shadow DOM root
 * @param selector - Element selector
 * @returns Promise resolving with shadow root
 */
browser.getShadowRoot(selector: string): Promise<ShadowRoot>;

// Navigate element tree
browser.getFirstElementChild("ul").then(firstItem => {
  console.log("First list item found");
});

browser.getNextSibling("#current-item").then(nextItem => {
  browser.click(nextItem);
});

/**
 * Move mouse to element with optional offset
 * @param selector - Element selector
 * @param xOffset - X offset from element center
 * @param yOffset - Y offset from element center
 * @returns Promise resolving when mouse moved
 */
browser.moveToElement(selector: string, xOffset?: number, yOffset?: number);

/**
 * Drag element to target location
 * @param source - Source element selector
 * @param target - Target element selector
 * @returns Promise resolving when drag completed
 */
browser.dragAndDrop(source: string, target: string);

/**
 * Take screenshot of specific element
 * @param selector - Element selector
 * @returns Promise resolving when screenshot taken
 */
browser.takeElementScreenshot(selector: string);

/**
 * Check checkbox or radio button
 * @param selector - Checkbox/radio selector
 * @returns Promise resolving when element checked
 */
browser.check(selector: string);

/**
 * Uncheck checkbox or radio button
 * @param selector - Checkbox/radio selector
 * @returns Promise resolving when element unchecked
 */
browser.uncheck(selector: string);

// Advanced interactions
browser.moveToElement("#dropdown-trigger");
browser.dragAndDrop("#draggable-item", "#drop-zone");
browser.check("input[type='checkbox'][name='agree']");
browser.takeElementScreenshot("#chart");

/**
 * Wait for element to be present in DOM
 * @param selector - Element selector
 * @param timeout - Maximum wait time in milliseconds
 * @returns Promise resolving when element present
 */
browser.waitForElementPresent(selector: string, timeout?: number);

/**
 * Wait for element to be visible
 * @param selector - Element selector
 * @param timeout - Maximum wait time in milliseconds
 * @returns Promise resolving when element visible
 */
browser.waitForElementVisible(selector: string, timeout?: number);

/**
 * Wait for element to be absent from DOM
 * @param selector - Element selector
 * @param timeout - Maximum wait time in milliseconds
 * @returns Promise resolving when element not present
 */
browser.waitForElementNotPresent(selector: string, timeout?: number);

/**
 * Wait for element to be invisible
 * @param selector - Element selector
 * @param timeout - Maximum wait time in milliseconds
 * @returns Promise resolving when element not visible
 */
browser.waitForElementNotVisible(selector: string, timeout?: number);

// Wait for elements
browser.waitForElementVisible("#loading-spinner", 5000);
browser.waitForElementNotVisible("#loading-spinner", 10000);
browser.waitForElementPresent("#results", 3000);

// Chain operations after waiting
browser
  .waitForElementVisible("#modal", 2000)
  .click("#modal .confirm-button")
  .waitForElementNotVisible("#modal", 2000);