appium/commands-yml/commands/element/find-elements.yml

Automation for Apps.

---
name: Find Elements
short_description: Search for multiple elements
description:
  >
     Get a list of elements that match the [locator selector](/docs/en/writing-running-appium/finding-elements.md).
selector_strategies:
  - name: Accessibility ID
    description: Read a unique identifier for a UI element. For XCUITest it is the element's `resource-id` attribute. For Android it is the element's `content-desc` attribute.
  - name: Class name
    description: "For IOS it is the full name of the XCUI element and begins with XCUIElementType. For Android it is the full name of the UIAutomator2 class (e.g.: android.widget.TextView)"
  - name: ID
    description: Native element identifier. `resource-id` for android; `name` for iOS.
  - name: Name
    description: Name of element
  - name: XPath
    description: Search the app XML source using xpath (not recommended, has performance issues)
  - name: Android UiAutomator
    description: Use the UI Automator API, in particular the [UiSelector](https://developer.android.com/reference/android/support/test/uiautomator/UiSelector.html) class to locate elements. In Appium you send the Java code, as a string, to the server, which executes it in the application’s environment, returning the element or elements.
  - name: IOS UIAutomation
    description: When automating an iOS application, Apple’s [Instruments](/docs/en/drivers/ios-uiautomation.md) framework can be used to find elements
example_usage:
  java:
    |
      List<MobileElement> elementsOne = (MobileElement) driver.findElementsByAccessibilityId("SomeAccessibilityID");
      List<MobileElement> elementsTwo = (MobileElement) driver.findElementsByClassName("SomeClassName");
  python:
    |
      el = self.driver.find_elements_by_accessibility_id('SomeAccessibilityID')
  javascript_wd:
    |
      let elementsOne = await driver.elementsByAccessibilityId("SomeAccessibilityID");
      let elementsTwo = await driver.elements("id", "SomeID");
  javascript_wdio:
    |
      driver.elements("~SomeAccessibilityId");
  ruby:
    |
      @driver.find_elements(:accessibility_id, "~SomeAccessibilityID")
  php:
    |
      $els = $this->elements($this->using('accessibility id')->value('SomeAccessibilityID'));
  csharp:
    |
      // TODO C# sample

client_docs:
  java: "https://seleniumhq.github.io/selenium/docs/api/java/org/openqa/selenium/WebElement.html#findElements-org.openqa.selenium.By-"
  python: "http://selenium-python.readthedocs.io/api.html#selenium.webdriver.remote.webdriver.WebDriver.find_elements"
  javascript_wdio: "http://webdriver.io/api/protocol/elements.html#Usage"
  javascript_wd: "https://github.com/admc/wd/blob/master/lib/commands.js#L798"
  ruby: "http://www.rubydoc.info/gems/selenium-webdriver/Selenium/WebDriver/SearchContext:find_elements"
  php: "https://github.com/appium/php-client/" # TODO PHP documentation link
  csharp: "https://github.com/appium/appium-dotnet-driver/" # TODO Dotnet documentation link

# Driver support by platform
driver_support:
  ios:
    xcuitest: true
    uiautomation: true
  android:
    uiautomator2: true
    uiautomator: true
  mac:
    mac: true
  windows:
    windows: true
client_support:
  java: true
  python: true
  ruby: true
  php: true
  csharp: true
  javascript_wd: true
  javascript_wdio: true


# Information about the HTTP endpoints
endpoint:
  url: /wd/hub/session/:session_id/elements
  method: 'POST'
  url_parameters:
    - name: session_id
      description: ID of the session to route the command to
  json_parameters:
    - name: using
      type: string
      description: The locator strategy to use
    - name: value
      type: string
      description: The search target
  response:
    - type: Array<String>
      description: A list of of JSON objects for the located elements

# Links to specifications. Should link to at least one specification
specifications:
  w3c: https://www.w3.org/TR/webdriver/#dfn-find-elements
  jsonwp: https://github.com/SeleniumHQ/selenium/wiki/JsonWireProtocol#sessionsessionidelements