Modern Element API

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

/**
 * Find child element within current element
 * @param selector - Child element selector
 * @returns Child element wrapper
 */
element.find(selector: string): Element;
element.get(selector: string): Element; // Alias for find

/**
 * Find multiple child elements within current element
 * @param selector - Child elements selector
 * @returns Array of child element wrappers
 */
element.findAll(selector: string): Element[];
element.getAll(selector: string): Element[]; // Alias for findAll

// Create element wrapper
const loginForm = browser.element("#login-form");
const submitButton = loginForm.find("button[type='submit']");

// Chain operations
const menuItems = browser.element("#navigation").findAll(".menu-item");

/**
 * Find element by visible text content
 * @param text - Text content to search for
 * @param options - Search options
 * @returns Element wrapper
 */
element.findByText(text: string, options?: {exact?: boolean}): Element;

/**
 * Find element by ARIA role
 * @param role - ARIA role name
 * @param options - Search options including accessible name
 * @returns Element wrapper
 */
element.findByRole(role: string, options?: {name?: string}): Element;

/**
 * Find element by placeholder text
 * @param text - Placeholder text to search for
 * @returns Element wrapper
 */
element.findByPlaceholderText(text: string): Element;

/**
 * Find element by associated label text
 * @param text - Label text to search for
 * @returns Element wrapper
 */
element.findByLabelText(text: string): Element;

/**
 * Find element by alt attribute text
 * @param text - Alt text to search for
 * @returns Element wrapper
 */
element.findByAltText(text: string): Element;

/**
 * Find multiple elements by text content
 * @param text - Text content to search for
 * @param options - Search options
 * @returns Array of element wrappers
 */
element.findAllByText(text: string, options?: {exact?: boolean}): Element[];

/**
 * Find multiple elements by ARIA role
 * @param role - ARIA role name
 * @param options - Search options
 * @returns Array of element wrappers
 */
element.findAllByRole(role: string, options?: {name?: string}): Element[];

/**
 * Find multiple elements by placeholder text
 * @param text - Placeholder text to search for
 * @returns Array of element wrappers
 */
element.findAllByPlaceholderText(text: string): Element[];

/**
 * Find multiple elements by label text
 * @param text - Label text to search for
 * @returns Array of element wrappers
 */
element.findAllByLabelText(text: string): Element[];

/**
 * Find multiple elements by alt text
 * @param text - Alt text to search for
 * @returns Array of element wrappers
 */
element.findAllByAltText(text: string): Element[];

// Semantic element finding
const loginButton = browser.element("body").findByRole("button", {name: "Log in"});
const emailInput = browser.element("form").findByLabelText("Email Address");
const searchInput = browser.element(".search").findByPlaceholderText("Search products...");

// Find multiple elements by content
const allButtons = browser.element("main").findAllByRole("button");
const productImages = browser.element(".gallery").findAllByAltText("Product Image");

/**
 * Click element
 * @returns Promise resolving when click completes
 */
element.click(): Promise<void>;

/**
 * Clear element content
 * @returns Promise resolving when content cleared
 */
element.clear(): Promise<void>;

/**
 * Send keystrokes to element
 * @param keys - Keys to send
 * @returns Promise resolving when keys sent
 */
element.sendKeys(...keys: string[]): Promise<void>;

/**
 * Submit form containing element
 * @returns Promise resolving when form submitted
 */
element.submit(): Promise<void>;

/**
 * Check checkbox or radio button
 * @returns Promise resolving when element checked
 */
element.check(): Promise<void>;

/**
 * Uncheck checkbox or radio button
 * @returns Promise resolving when element unchecked
 */
element.uncheck(): Promise<void>;

/**
 * Drag element to destination
 * @param destination - Target element or coordinates
 * @returns Promise resolving when drag completes
 */
element.dragAndDrop(destination: Element | {x: number, y: number}): Promise<void>;

/**
 * Move mouse to element with optional offset
 * @param x - X offset from element center
 * @param y - Y offset from element center
 * @returns Promise resolving when mouse moved
 */
element.moveTo(x?: number, y?: number): Promise<void>;

/**
 * Update element value (clear then set)
 * @param keys - Keys to send after clearing
 * @returns Promise resolving when value updated
 */
element.update(...keys: string[]): Promise<void>;

/**
 * Upload file to file input element
 * @param file - File path to upload
 * @returns Promise resolving when file uploaded
 */
element.upload(file: string): Promise<void>;

/**
 * Click and hold element
 * @returns Promise resolving when click-and-hold completes
 */
element.clickAndHold(): Promise<void>;

/**
 * Double-click element
 * @returns Promise resolving when double-click completes
 */
element.doubleClick(): Promise<void>;

/**
 * Right-click element
 * @returns Promise resolving when right-click completes
 */
element.rightClick(): Promise<void>;

// Fluent element actions
const form = browser.element("#contact-form");
await form.findByLabelText("Name").sendKeys("John Doe");
await form.findByLabelText("Email").sendKeys("john@example.com");
await form.findByRole("button", {name: "Submit"}).click();

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

// Drag and drop
const draggable = browser.element("#draggable-item");
const dropZone = browser.element("#drop-zone");
await draggable.dragAndDrop(dropZone);

/**
 * Get WebDriver element ID
 * @returns Promise resolving with element ID
 */
element.getId(): Promise<string>;

/**
 * Get element dimensions and position
 * @returns Promise resolving with rectangle object
 */
element.getRect(): Promise<{x: number, y: number, width: number, height: number}>;
element.rect(): Promise<{x: number, y: number, width: number, height: number}>; // Alias

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

/**
 * Get element position
 * @returns Promise resolving with position object
 */
element.getLocation(): Promise<{x: number, y: number}>;

/**
 * Get element tag name
 * @returns Promise resolving with tag name
 */
element.getTagName(): Promise<string>;
element.tagName(): Promise<string>; // Alias

/**
 * Get element text content
 * @returns Promise resolving with text content
 */
element.getText(): Promise<string>;
element.text(): Promise<string>; // Alias

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

/**
 * Get DOM property value
 * @param name - Property name
 * @returns Promise resolving with property value
 */
element.getProperty(name: string): Promise<any>;
element.prop(name: string): Promise<any>; // Alias

/**
 * Set DOM property value
 * @param name - Property name
 * @param value - Property value
 * @returns Promise resolving when property set
 */
element.setProperty(name: string, value: any): Promise<void>;

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

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

/**
 * Get CSS property value
 * @param name - CSS property name
 * @returns Promise resolving with property value
 */
element.getCssProperty(name: string): Promise<string>;
element.css(name: string): Promise<string>; // Alias

/**
 * Get element accessible name
 * @returns Promise resolving with accessible name
 */
element.getAccessibleName(): Promise<string>;
element.accessibleName(): Promise<string>; // Alias

/**
 * Get element ARIA role
 * @returns Promise resolving with ARIA role
 */
element.getAriaRole(): Promise<string>;
element.ariaRole(): Promise<string>; // Alias

// Get element properties
const button = browser.element("#submit-button");
const buttonText = await button.getText();
const isDisabled = await button.getProperty("disabled");
const backgroundColor = await button.getCssProperty("background-color");

console.log(`Button "${buttonText}" is ${isDisabled ? 'disabled' : 'enabled'}`);
console.log(`Background color: ${backgroundColor}`);

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

/**
 * Check if element exists in DOM
 * @returns Promise resolving with presence boolean
 */
element.isPresent(): Promise<boolean>;

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

/**
 * Check if element is visible
 * @returns Promise resolving with visibility boolean
 */
element.isVisible(): Promise<boolean>;
element.isDisplayed(): Promise<boolean>; // Alias

/**
 * Check if element is currently active (has focus)
 * @returns Promise resolving with active boolean
 */
element.isActive(): Promise<boolean>;

// Check element state
const form = browser.element("#registration-form");
const submitButton = form.findByRole("button", {name: "Register"});

if (await submitButton.isEnabled()) {
  await submitButton.click();
} else {
  console.log("Submit button is disabled");
}

if (await form.findByLabelText("Terms").isSelected()) {
  console.log("Terms checkbox is checked");
}

/**
 * Get first child element
 * @returns Promise resolving with first child element
 */
element.getFirstElementChild(): Promise<Element>;

/**
 * Get last child element
 * @returns Promise resolving with last child element
 */
element.getLastElementChild(): Promise<Element>;

/**
 * Get next sibling element
 * @returns Promise resolving with next sibling element
 */
element.getNextElementSibling(): Promise<Element>;

/**
 * Get previous sibling element
 * @returns Promise resolving with previous sibling element
 */
element.getPreviousElementSibling(): Promise<Element>;

/**
 * Get shadow DOM root
 * @returns Promise resolving with shadow root
 */
element.getShadowRoot(): Promise<ShadowRoot>;

// Navigate DOM tree
const list = browser.element("ul.menu");
const firstItem = await list.getFirstElementChild();
const secondItem = await firstItem.getNextElementSibling();

await secondItem.click();

/**
 * Take screenshot of element
 * @returns Promise resolving when screenshot taken
 */
element.takeScreenshot(): Promise<void>;

/**
 * Wait for element to meet custom condition
 * @param condition - Function returning boolean or promise
 * @param options - Wait options including timeout
 * @returns Promise resolving when condition met
 */
element.waitUntil(
  condition: (element: Element) => boolean | Promise<boolean>,
  options?: {timeout?: number, message?: string}
): Promise<void>;

// Take element screenshot
await browser.element("#chart").takeScreenshot();

// Wait for custom condition
const statusElement = browser.element("#status");
await statusElement.waitUntil(async (el) => {
  const text = await el.getText();
  return text === "Complete";
}, {timeout: 10000, message: "Status never became Complete"});

/**
 * Assert element is enabled
 * @returns Promise resolving when assertion passes
 */
element.assert.enabled(): Promise<void>;

/**
 * Assert element is selected
 * @returns Promise resolving when assertion passes
 */
element.assert.selected(): Promise<void>;

/**
 * Assert element is visible
 * @returns Promise resolving when assertion passes
 */
element.assert.visible(): Promise<void>;

/**
 * Assert element is present in DOM
 * @returns Promise resolving when assertion passes
 */
element.assert.present(): Promise<void>;

/**
 * Assert element has specific CSS class
 * @param name - CSS class name
 * @returns Promise resolving when assertion passes
 */
element.assert.hasClass(name: string): Promise<void>;

/**
 * Assert element has specific attribute
 * @param name - Attribute name
 * @returns Promise resolving when assertion passes
 */
element.assert.hasAttribute(name: string): Promise<void>;

/**
 * Assert element has child elements
 * @returns Promise resolving when assertion passes
 */
element.assert.hasDescendants(): Promise<void>;

// Element assertions
const submitButton = browser.element("#submit-button");
await submitButton.assert.visible();
await submitButton.assert.enabled();
await submitButton.assert.hasAttribute("type");

const requiredField = browser.element("#email");
await requiredField.assert.hasAttribute("required");

/**
 * Assert element value contains expected text
 * @param expected - Expected text content
 * @returns Promise resolving when assertion passes
 */
elementValue.assert.contains(expected: string): Promise<void>;

/**
 * Assert element value equals expected text
 * @param expected - Expected text content
 * @returns Promise resolving when assertion passes
 */
elementValue.assert.equals(expected: string): Promise<void>;

/**
 * Assert element value matches regular expression
 * @param regex - Regular expression pattern
 * @returns Promise resolving when assertion passes
 */
elementValue.assert.matches(regex: RegExp): Promise<void>;

// Value assertions
const emailInput = browser.element("#email");
await emailInput.sendKeys("user@example.com");

const emailValue = await emailInput.getValue();
await emailValue.assert.contains("@example.com");
await emailValue.assert.matches(/^[^@]+@[^@]+\.[^@]+$/);

const statusMessage = browser.element("#status");
const statusText = await statusMessage.getText();
await statusText.assert.equals("Operation completed successfully");