Element Location & Interaction

/**
 * Find a single element using selector strategy
 * @param using - Selector strategy ('id', 'class name', 'css selector', 'xpath', etc.)
 * @param value - Selector value
 * @param cb - Callback receiving (err, element)
 */
element(using: string, value: string, cb?: callback): Element;

/**
 * Find multiple elements using selector strategy
 * @param using - Selector strategy
 * @param value - Selector value
 * @param cb - Callback receiving (err, elements)
 */
elements(using: string, value: string, cb?: callback): Element[];

/**
 * Find element by ID
 * @param id - Element ID attribute
 * @param cb - Callback receiving (err, element)
 */
elementById(id: string, cb?: callback): Element;

/**
 * Find element by class name
 * @param className - Element class name
 * @param cb - Callback receiving (err, element)
 */
elementByClassName(className: string, cb?: callback): Element;

/**
 * Find element by CSS selector
 * @param selector - CSS selector string
 * @param cb - Callback receiving (err, element)
 */
elementByCss(selector: string, cb?: callback): Element;

/**
 * Find element by XPath
 * @param xpath - XPath expression
 * @param cb - Callback receiving (err, element)
 */
elementByXPath(xpath: string, cb?: callback): Element;

/**
 * Find element by link text
 * @param text - Exact link text
 * @param cb - Callback receiving (err, element)
 */
elementByLinkText(text: string, cb?: callback): Element;

/**
 * Find element by partial link text
 * @param text - Partial link text
 * @param cb - Callback receiving (err, element)
 */
elementByPartialLinkText(text: string, cb?: callback): Element;

/**
 * Find element by tag name
 * @param tagName - HTML tag name
 * @param cb - Callback receiving (err, element)
 */
elementByTagName(tagName: string, cb?: callback): Element;

/**
 * Find element by name attribute
 * @param name - Element name attribute
 * @param cb - Callback receiving (err, element)
 */
elementByName(name: string, cb?: callback): Element;

// Find by ID
browser.elementById('submit-button', function(err, element) {
  if (err) throw err;
  console.log('Found submit button:', element);
});

// Find by CSS selector
browser.elementByCss('.login-form input[type="email"]', function(err, element) {
  // Found email input in login form
});

// Find multiple elements
browser.elementsByCss('.product-item', function(err, elements) {
  console.log('Found', elements.length, 'products');
});

// Promise chain style
browser
  .elementById('menu-toggle')
  .click()
  .elementByCss('.dropdown-menu')
  .isDisplayed()
  .then(visible => console.log('Menu visible:', visible));

/**
 * Find element or return null if not found
 * @param using - Selector strategy
 * @param value - Selector value
 * @param cb - Callback receiving (err, element | null)
 */
elementOrNull(using: string, value: string, cb?: callback): Element | null;

/**
 * Find element only if it exists
 * @param using - Selector strategy
 * @param value - Selector value
 * @param cb - Callback receiving (err, element | null)
 */
elementIfExists(using: string, value: string, cb?: callback): Element | null;

/**
 * Check if element exists without throwing error
 * @param using - Selector strategy
 * @param value - Selector value
 * @param cb - Callback receiving (err, exists)
 */
hasElement(using: string, value: string, cb?: callback): boolean;

// Safe element finding
browser.elementByIdOrNull('optional-element', function(err, element) {
  if (element) {
    // Element exists, interact with it
    element.click();
  } else {
    // Element doesn't exist, continue with test
    console.log('Optional element not found, skipping interaction');
  }
});

// Check element existence
browser.hasElement('css selector', '.error-message', function(err, exists) {
  if (exists) {
    console.log('Error message is displayed');
  }
});

/**
 * Get element text content
 * @param element - Target element
 * @param cb - Callback receiving (err, text)
 */
text(element: Element, cb?: callback): string;

/**
 * Get element attribute value
 * @param element - Target element
 * @param attrName - Attribute name
 * @param cb - Callback receiving (err, value)
 */
getAttribute(element: Element, attrName: string, cb?: callback): string;

/**
 * Get element tag name
 * @param element - Target element
 * @param cb - Callback receiving (err, tagName)
 */
getTagName(element: Element, cb?: callback): string;

/**
 * Get element value (for form inputs)
 * @param element - Target element
 * @param cb - Callback receiving (err, value)
 */
getValue(element: Element, cb?: callback): string;

/**
 * Check if element is displayed
 * @param element - Target element
 * @param cb - Callback receiving (err, isDisplayed)
 */
isDisplayed(element: Element, cb?: callback): boolean;

/**
 * Check if element is enabled
 * @param element - Target element
 * @param cb - Callback receiving (err, isEnabled)
 */
isEnabled(element: Element, cb?: callback): boolean;

/**
 * Check if element is selected (checkboxes, radio buttons)
 * @param element - Target element
 * @param cb - Callback receiving (err, isSelected)
 */
isSelected(element: Element, cb?: callback): boolean;

/**
 * Get computed CSS property value
 * @param element - Target element
 * @param cssProperty - CSS property name
 * @param cb - Callback receiving (err, value)
 */
getComputedCss(element: Element, cssProperty: string, cb?: callback): string;

// Get element information
browser.elementById('username', function(err, element) {
  element.text(function(err, text) {
    console.log('Username field text:', text);
  });
  
  element.getAttribute('placeholder', function(err, placeholder) {
    console.log('Placeholder text:', placeholder);
  });
  
  element.isDisplayed(function(err, visible) {
    console.log('Username field visible:', visible);
  });
});

// Check form field state
browser.elementById('terms-checkbox', function(err, checkbox) {
  checkbox.isSelected(function(err, checked) {
    if (!checked) {
      checkbox.click(); // Check the terms checkbox
    }
  });
});

// Get CSS styles
browser.elementByCss('.error-message', function(err, element) {
  element.getComputedCss('color', function(err, color) {
    console.log('Error message color:', color);
  });
});

/**
 * Get element location on page
 * @param element - Target element
 * @param cb - Callback receiving (err, location)
 */
getLocation(element: Element, cb?: callback): {x: number, y: number};

/**
 * Get element location relative to viewport
 * @param element - Target element
 * @param cb - Callback receiving (err, location)
 */
getLocationInView(element: Element, cb?: callback): {x: number, y: number};

/**
 * Get element size
 * @param element - Target element
 * @param cb - Callback receiving (err, size)
 */
getSize(element: Element, cb?: callback): {width: number, height: number};

// Get element position and size
browser.elementById('modal-dialog', function(err, modal) {
  modal.getLocation(function(err, location) {
    console.log('Modal position:', location.x, location.y);
  });
  
  modal.getSize(function(err, size) {
    console.log('Modal size:', size.width, size.height);
  });
});

// Center click on element
browser.elementByCss('.clickable-area', function(err, element) {
  element.getSize(function(err, size) {
    element.getLocation(function(err, location) {
      const centerX = location.x + size.width / 2;
      const centerY = location.y + size.height / 2;
      browser.moveTo(null, centerX, centerY);
      browser.click();
    });
  });
});

/**
 * Compare two elements for equality
 * @param element1 - First element
 * @param element2 - Second element
 * @param cb - Callback receiving (err, areEqual)
 */
equalsElement(element1: Element, element2: Element, cb?: callback): boolean;

// Compare elements
browser.elementById('current-user', function(err, userElement1) {
  browser.elementByCss('.user-profile', function(err, userElement2) {
    browser.equalsElement(userElement1, userElement2, function(err, areEqual) {
      console.log('Elements are the same:', areEqual);
    });
  });
});

/**
 * Get the currently active (focused) element
 * @param cb - Callback receiving (err, element)
 */
active(cb?: callback): Element;

// Get active element
browser.active(function(err, activeElement) {
  activeElement.getAttribute('id', function(err, id) {
    console.log('Currently focused element ID:', id);
  });
});

// Send keys to currently focused element
browser.active(function(err, element) {
  element.type('Hello World');
});