Gem Version

Build Status

This library is a Ruby client for Appium. The gem is available via appium_lib_core.

This library wraps selenium-webdriver and adapts WebDriver APIs for Appium. ruby_lib calls all of Appium/Selenium related APIs via this core library. It works instance based driver.


Related library

How to start

Run tests

Unit Tests

Run unit tests which check each method and commands, URL, using the webmock.

$ bundle install
$ bundle exec parallel_test test/unit/

Functional Tests

Run functional tests which require the Appium server and real device, Simulator/Emulator.

  • Start Appium server

    $ npm install -g appium opencv4nodejs
    $ appium --relaxed-security # To run all tests in local
  • Conduct tests

    $ bundle install
    $ rake test:func:android # Andorid, uiautomator2
    $ AUTOMATION_NAME_DROID=espresso rake test:func:android # Andorid, uiautomator2
    $ rake test:func:ios     # iOS

Real device for iOS

  • You should pre-install UICatalog in iOS with a particular bundleId
    • Set the bundleId instead of app in test/test_helper#ios
# Create derivedDataPath in "/tmp/#{org_id}" and reuse xctestrun in the directory
$ REAL=true BUNDLE_ID='target-bundleid' WDA_BUNDLEID="ios.appium.WebDriverAgentRunner" ORG_ID=XXXXXXX rake test:func:ios

# Run with xcconfig file. The template is in 'test/functional/ios/temp.xcconfig'
# The PROVISIONING_PROFILE is in '~/Library/MobileDevice/Provisioning\ Profiles/'
$ REAL=true XCODE_CONFIG_FILE='/path/to/xcconfig' ORG_ID=XXXXXXX rake test:func:ios

Run parallel tests with parallel_tests gem


# Generate 3 emulators. Running 3 emulators require much machine power.
# It requires an image which is for Google Play and x86 CPU architecture's image.
$ bundle exec rake android:gen_device
$ PARALLEL=1 bundle exec parallel_test test/functional/android -n 3
  • Create iPhone simulators named iPhone Xs Max- 8100 and iPhone Xs Max - 8101
  • Run iOS functional tests with below command
$ PARALLEL=1 bundle exec parallel_test test/functional/ios -n 2


  • Runs on CI environment (on Azure)
    • Non IGNORE_VERSION_SKIP or IGNORE_VERSION_SKIP=true runs all tests ignoring skip them by Appium versions
    • IGNORE_VERSION_SKIP=false skips the following tests if the Appium version is lower than the requirement
$ IGNORE_VERSION_SKIP=true CI=true bundle exec rake test:func:android

Run a test case

  1. Launch the Appium server locally.
  2. Run the following script.
  • test.rb

    require 'rubygems'
    require 'appium_lib_core'
    opts = {
      desired_capabilities: { # or { caps: {....} }
        platformName: :ios,
        platformVersion: '11.0',
        deviceName: 'iPhone Simulator',
        automationName: 'XCUITest',
        app: '/path/to/'
      appium_lib: {
        wait: 30
    @core = Appium::Core.for(opts) # create a core driver with `opts`
    @driver = @core.start_driver
    # Launch iPhone Simulator and ``
    @driver.find_element(:accessibility_id, 'some accessibility') # find an element
  • Run the script

    # shell 1
    $ appium --log-level warn:error # show only warning and error logs
    # shell 2
    $ ruby test.rb

More examples are in test/functional


Read Appium/Core/Driver to catch up with available capabilities. Capabilities affect only ruby_lib is Appium/Core/Options.



Use appium_thor to release this gem.

$ thor bump # bumpy,
$ thor release


  1. Fork it ( )
  2. Create your feature branch (git checkout -b my-new-feature)
  3. Commit your changes (git commit -am 'Add some feature')
  4. Push to the branch (git push origin my-new-feature)
  5. Create new Pull Request


Apache License v2