Element Interaction

/**
 * Click on an element
 * @param options - Click options including button type and coordinates
 * @returns Promise that resolves when click is complete
 */
click(options?: ClickOptions): Promise<void>;

/**
 * Double-click on an element
 * @returns Promise that resolves when double-click is complete
 */
doubleClick(): Promise<void>;

/**
 * Move mouse cursor to an element
 * @param options - Movement options with optional offset coordinates
 * @returns Promise that resolves when movement is complete
 */
moveTo(options?: {xOffset?: number, yOffset?: number}): Promise<void>;

interface ClickOptions {
  button: 'left' | 'middle' | 'right' | number;
  x: number;
  y: number;
  duration: number;
  skipRelease: boolean;
}

const button = await browser.$('#submit-btn');

// Basic click
await button.click();

// Right-click
await button.click({ button: 'right' });

// Click with offset
await button.click({ x: 10, y: 5 });

// Double-click
await button.doubleClick();

// Move to element
await button.moveTo();
await button.moveTo({ xOffset: 20, yOffset: 10 });

/**
 * Drag this element and drop it on another element or coordinate
 * @param target - Target element or coordinates to drop on
 * @returns Promise that resolves when drag and drop is complete
 */
dragAndDrop(target: WebdriverIO.Element | {x: number, y: number}): Promise<void>;

const source = await browser.$('#draggable-item');
const target = await browser.$('#drop-zone');

// Drag to another element
await source.dragAndDrop(target);

// Drag to specific coordinates
await source.dragAndDrop({ x: 100, y: 200 });

/**
 * Set the value of an input element, clearing any existing value
 * @param value - Value to set in the input field
 * @returns Promise that resolves when value is set
 */
setValue(value: string | number): Promise<void>;

/**
 * Add value to an input element without clearing existing value
 * @param value - Value to append to the input field
 * @returns Promise that resolves when value is added
 */
addValue(value: string | number): Promise<void>;

/**
 * Clear the value of an input element
 * @returns Promise that resolves when value is cleared
 */
clearValue(): Promise<void>;

const emailInput = await browser.$('#email');
const passwordInput = await browser.$('#password');

// Set complete value (clears existing)
await emailInput.setValue('user@example.com');
await passwordInput.setValue('secretpassword');

// Add to existing value
await emailInput.addValue('+work');

// Clear input
await emailInput.clearValue();

/**
 * Check if element exists in the DOM
 * @returns Promise resolving to boolean indicating existence
 */
isExisting(): Promise<boolean>;

/**
 * Check if element is displayed (visible)
 * @returns Promise resolving to boolean indicating visibility
 */
isDisplayed(): Promise<boolean>;

/**
 * Check if element is enabled for interaction
 * @returns Promise resolving to boolean indicating enabled state
 */
isEnabled(): Promise<boolean>;

/**
 * Check if element is selected (checkboxes, radio buttons, options)
 * @returns Promise resolving to boolean indicating selected state
 */
isSelected(): Promise<boolean>;

/**
 * Check if element currently has focus
 * @returns Promise resolving to boolean indicating focus state
 */
isFocused(): Promise<boolean>;

/**
 * Check if element is clickable (visible, enabled, not obscured)
 * @returns Promise resolving to boolean indicating clickable state
 */
isClickable(): Promise<boolean>;

/**
 * Check if element is stable (not moving or changing)
 * @returns Promise resolving to boolean indicating stability
 */
isStable(): Promise<boolean>;

/**
 * Check if this element is equal to another element
 * @param element - Element to compare with
 * @returns Promise resolving to boolean indicating equality
 */
isEqual(element: WebdriverIO.Element): Promise<boolean>;

const button = await browser.$('#submit-btn');
const checkbox = await browser.$('#agree-terms');

// Check various states
const exists = await button.isExisting();
const visible = await button.isDisplayed();
const enabled = await button.isEnabled();
const clickable = await button.isClickable();

// Check form element states
const checked = await checkbox.isSelected();
const focused = await checkbox.isFocused();

// Compare elements
const anotherButton = await browser.$('#cancel-btn');
const same = await button.isEqual(anotherButton);

/**
 * Get the visible text content of the element
 * @returns Promise resolving to the element's text content
 */
getText(): Promise<string>;

/**
 * Get the value of an input element
 * @returns Promise resolving to the element's value
 */
getValue(): Promise<string>;

/**
 * Get the value of an element attribute
 * @param attributeName - Name of the attribute to retrieve
 * @returns Promise resolving to the attribute value or null
 */
getAttribute(attributeName: string): Promise<string | null>;

/**
 * Get the value of an element property
 * @param propertyName - Name of the property to retrieve
 * @returns Promise resolving to the property value
 */
getProperty(propertyName: string): Promise<any>;

/**
 * Get the computed CSS property value
 * @param cssProperty - Name of the CSS property to retrieve
 * @returns Promise resolving to CSS property object
 */
getCSSProperty(cssProperty: string): Promise<object>;

/**
 * Get the HTML content of the element
 * @param includeSelectorTag - Whether to include the element's own tag
 * @returns Promise resolving to the HTML content
 */
getHTML(includeSelectorTag?: boolean): Promise<string>;

/**
 * Get the tag name of the element
 * @returns Promise resolving to the element's tag name
 */
getTagName(): Promise<string>;

/**
 * Get the size dimensions of the element
 * @returns Promise resolving to object with width and height
 */
getSize(): Promise<{width: number, height: number}>;

/**
 * Get the location coordinates of the element
 * @returns Promise resolving to object with x and y coordinates
 */
getLocation(): Promise<{x: number, y: number}>;

/**
 * Get the computed ARIA role of the element
 * @returns Promise resolving to the computed role
 */
getComputedRole(): Promise<string>;

/**
 * Get the computed ARIA label of the element
 * @returns Promise resolving to the computed label
 */
getComputedLabel(): Promise<string>;

const element = await browser.$('#my-element');

// Get text and value
const text = await element.getText();
const value = await element.getValue();

// Get attributes and properties
const id = await element.getAttribute('id');
const className = await element.getAttribute('class');
const disabled = await element.getProperty('disabled');

// Get CSS properties
const color = await element.getCSSProperty('color');
const fontSize = await element.getCSSProperty('font-size');

// Get HTML and tag information
const html = await element.getHTML();
const htmlWithTag = await element.getHTML(true);
const tagName = await element.getTagName();

// Get dimensions and position
const size = await element.getSize();
const location = await element.getLocation();

// Get accessibility information
const role = await element.getComputedRole();
const label = await element.getComputedLabel();

/**
 * Select option by its index position
 * @param index - Zero-based index of the option to select
 * @returns Promise that resolves when selection is complete
 */
selectByIndex(index: number): Promise<void>;

/**
 * Select option by attribute value
 * @param attribute - Attribute name to match against
 * @param value - Value of the attribute to select
 * @returns Promise that resolves when selection is complete
 */
selectByAttribute(attribute: string, value: string): Promise<void>;

/**
 * Select option by its visible text content
 * @param text - Visible text of the option to select
 * @returns Promise that resolves when selection is complete
 */
selectByVisibleText(text: string): Promise<void>;

const selectElement = await browser.$('#country-select');

// Select by index (first option = 0)
await selectElement.selectByIndex(2);

// Select by attribute value
await selectElement.selectByAttribute('value', 'US');

// Select by visible text
await selectElement.selectByVisibleText('United States');

/**
 * Perform touch action on the element
 * @param action - Touch action configuration object
 * @returns Promise that resolves when touch action is complete
 */
touchAction(action: object): Promise<void>;

const element = await browser.$('#touch-target');

// Single tap
await element.touchAction('tap');

// Long press
await element.touchAction({
  action: 'longPress',
  duration: 1000
});

// Complex touch sequence
await element.touchAction([
  { action: 'press' },
  { action: 'wait', duration: 500 },
  { action: 'moveTo', x: 100, y: 0 },
  { action: 'release' }
]);

/**
 * Wait for element to be displayed (visible in the viewport)
 * @param options - Wait options including timeout and reverse condition
 * @returns Promise resolving to true when element is displayed
 */
waitForDisplayed(options?: {
  timeout?: number;
  reverse?: boolean;
  timeoutMsg?: string;
  interval?: number;
}): Promise<boolean>;

/**
 * Wait for element to be enabled (not disabled)
 * @param options - Wait options including timeout and reverse condition
 * @returns Promise resolving to true when element is enabled
 */
waitForEnabled(options?: {
  timeout?: number;
  reverse?: boolean;
  timeoutMsg?: string;
  interval?: number;
}): Promise<boolean>;

/**
 * Wait for element to exist in the DOM
 * @param options - Wait options including timeout and reverse condition
 * @returns Promise resolving to true when element exists
 */
waitForExist(options?: {
  timeout?: number;
  reverse?: boolean;
  timeoutMsg?: string;
  interval?: number;
}): Promise<boolean>;

/**
 * Wait for element to be clickable (visible, enabled, and not overlapped)
 * @param options - Wait options including timeout and reverse condition
 * @returns Promise resolving to true when element is clickable
 */
waitForClickable(options?: {
  timeout?: number;
  reverse?: boolean;
  timeoutMsg?: string;
  interval?: number;
}): Promise<boolean>;

/**
 * Wait for element to be stable (not moving or changing)
 * @param options - Wait options including timeout
 * @returns Promise resolving to true when element is stable
 */
waitForStable(options?: {
  timeout?: number;
  timeoutMsg?: string;
  interval?: number;
}): Promise<boolean>;

const element = await browser.$('#dynamic-content');

// Wait for element to be displayed
await element.waitForDisplayed({ timeout: 5000 });

// Wait for element to disappear
await element.waitForDisplayed({ 
  reverse: true, 
  timeoutMsg: 'Element should have disappeared' 
});

// Wait for button to be clickable
const submitBtn = await browser.$('#submit');
await submitBtn.waitForClickable();
await submitBtn.click();

// Wait for element to exist in DOM
await element.waitForExist({ timeout: 10000 });

// Wait for form field to be enabled
const inputField = await browser.$('#user-input');
await inputField.waitForEnabled();
await inputField.setValue('test data');

// Wait for element to stop moving/changing
const animatedElement = await browser.$('#animation');
await animatedElement.waitForStable();

/**
 * Scroll the element into the viewport
 * @param options - Scroll behavior options
 * @returns Promise that resolves when scrolling is complete
 */
scrollIntoView(options?: object): Promise<void>;

/**
 * Take a screenshot of just this element
 * @param filename - Path where screenshot should be saved
 * @returns Promise that resolves when screenshot is saved
 */
saveScreenshot(filename: string): Promise<void>;

/**
 * Execute JavaScript code with this element as context
 * @param script - JavaScript code or function to execute
 * @param args - Additional arguments to pass to the script
 * @returns Promise resolving to the script's return value
 */
execute(script: string | Function, ...args: any[]): Promise<any>;

/**
 * Execute asynchronous JavaScript code with this element as context
 * @param script - Async JavaScript code or function to execute
 * @param args - Additional arguments to pass to the script
 * @returns Promise resolving to the script's return value
 */
executeAsync(script: string | Function, ...args: any[]): Promise<any>;

const element = await browser.$('#my-element');

// Scroll element into view
await element.scrollIntoView();
await element.scrollIntoView({ behavior: 'smooth', block: 'center' });

// Take element screenshot
await element.saveScreenshot('./element-screenshot.png');

// Execute JavaScript on element
const backgroundColor = await element.execute(function() {
  return this.style.backgroundColor;
});

// Execute async JavaScript
const result = await element.executeAsync(function(done) {
  setTimeout(() => {
    done(this.getBoundingClientRect());
  }, 100);
});