AWS Device Farm
Developer Guide (API Version 2015-06-23)

Working with Appium Ruby for iOS Applications and AWS Device Farm

This section describes how to configure, package, and upload your Appium Ruby tests to Device Farm. Appium is an open source tool for automating native and mobile web applications. For more information, see Introduction to Appium on the Appium website.

Version Information

  • You can use any Ruby version when you run Appium Ruby tests on Device Farm. Specify the Ruby version (for example, 2.5.1) in the test spec YAML file.

  • Device Farm supports Appium server versions 1.6.5 and later. You can choose any Appium version by using the avm command. For example, to use Appium server version 1.9.1, add these commands to your test spec YAML file:

    phases: install: commands: # To install a newer version of Appium such as version 1.9.1: - export APPIUM_VERSION=1.9.1 - avm $APPIUM_VERSION - ln -s /usr/local/avm/versions/$APPIUM_VERSION/node_modules/.bin/appium /usr/local/avm/versions/$APPIUM_VERSION/node_modules/appium/bin/appium.js

    For more information, see Uploading a Custom Test Spec Using the AWS CLI and Create a Test Run in AWS Device Farm.

Prerequisites for Packaging Your Tests

To package your Appium Ruby tests and upload them to Device Farm, you must install the following on your local machine:

  • Ruby Version Manager (RVM)

    Use this command-line tool when you develop and package your tests so that unnecessary dependencies are not included in your test package.

  • Ruby

  • Bundler (This gem is typically installed with Ruby.)

  1. Install the required keys, RVM, and Ruby. For instructions, see Installing RVM on the RVM website.

    # The following command is for reference only. Go to rvm website and look for the complete command. gpg --keyserver hkp:// --recv-keys $keys # install rvm along with ruby \curl -sSL | bash -s stable --ruby

    After the installation is complete, reload your terminal by signing out and then signing in again.


    RVM is loaded as a function for the bash shell only.

  2. Run this command in the bash shell to verify that RVM is installed correctly. You can switch to the bash shell by using /bin/bash.

    command -v rvm

    You should see rvm as output.

  3. If you want to install a specific version of Ruby (for example, 2.5.1) run the following command:

    rvm install ruby 2.5.1 --autolibs=0

    Run this command to verify that you are using the specified version:

    ruby -v
  4. Although a typical Ruby installation includes Bundler, run this command if you need to install it:

    gem install bundler

Step 1: Create a Zipped Test Package File

The Appium Ruby test packages that you upload to Device Farm must be in .zip format and contain all the dependencies of your test.

  1. Run this command to create a virtual Ruby environment:

    # myGemset is the name of your virtual Ruby environment rvm gemset create myGemset
  2. Run this command to use the environment you just created:

    rvm gemset use myGemset
  3. Check out your source code.

    Make sure you are at the root directory of your project. You can see Gemfile at the root directory.

  4. Run this command to install your local dependencies and all gems from the Gemfile:

    bundle install


    At this point, you should be able to run your tests locally. Use this command to run a test locally:

    bundle exec $test_command
  5. Package your gems in the vendor/cache folder.

    # This will copy all the .gem files needed to run your tests into the vendor/cache directory bundle package
  6. Run the following command to bundle your source code, along with all your dependencies, into a single zipped archive:

    zip -r Gemfile vendor/ $(any other source code directory files)

    This is the file that you upload to Device Farm in the following procedure.

Step 2: Upload Your Test Package to Device Farm

Use the Device Farm console to upload your tests.

  1. Sign in to the Device Farm console at

  2. If you see the AWS Device Farm console home page, choose Get started.

  3. You can upload your tests to an existing project or choose Create a new project.


    If the list of projects is not displayed, on the secondary navigation bar, for Projects, choose the name of the project where you want to upload your tests.

    To create a project, follow the instructions in Create a Project in AWS Device Farm.

  4. If the Create a new run button is displayed, choose it.

  5. On the Choose your application page, choose iOS native application ( 
        iOS icon.

        Choose an application in the Device Farm console.
  6. Choose Upload to upload your .ipa file.

    Device Farm processes your .ipa file before it continues.

  7. In Run name, enter a name for your run.


    Give the run a name that helps you identify a specific build of your app (for example, Beta-0.1). For more information, see Working with Test Runs.

  8. Choose Appium Ruby to configure your test.

  9. To add your Appium test scripts to the test run, choose Upload.

  10. Choose the file you created in the previous procedure.

  11. Follow the instructions to choose a test spec.

    If you are using the default test spec, change the test execution command in the test section of the test spec YAML file.

  12. Choose devices and start the run.

    For more information, see Create a Test Run in AWS Device Farm.


Device Farm does not modify iOS Appium Ruby tests.

Tips for Speeding Up Your Appium Tests

In the packaging instructions in Step 1, you are packaging the gems but the gems are still getting installed on the Device Farm host at runtime. Gems with extensions (for example, Nokogiri) take a considerable amount of time to install on the host.

To speed up your tests, you can package the gems installation directory instead of packaging the gems themselves. Since gems with extension are platform specific, you need to generate the gem installation directory on the same platform that Device Farm uses to run your tests.

Device Farm runs your iOS tests on a macOS machine. For iOS devices, you can use the Device Farm infrastructure to create a gem installation directory.


Device Farm regularly updates the macOS version running on Device Farm hosts. The following packaging steps can break with the change in macOS version if the gem extensions across macOS versions are not compatible.

  1. Package your tests according to the instructions in Step 1: Create a Zipped Test Package File.

  2. Change the following commands in your test spec YAML file when you schedule a test run in Device Farm

    >> bundle install --local bundle install --local --path=$DEVICEFARMLOGDIRECTORY/vendor/bundle >> bundle install Bundle install --path=$DEVICEFARMLOGDIRECTORY/vendor/bundle

    The --path installs the gems in the $DEVICEFARMLOGDIRECTORY/vendor/bundle directory instead of the system location.

    Once the test run finishes, you can download the vendor/bundle directory from the test artifact.

  3. Copy the vendor/bundle directory at the root directory of your project.

  4. Run this command to set the gem installation directory to vendor/bundle:

    bundle config --local path vendor/bundle

    The above command creates a .bundle/config file.


    At this point, you should be able to run your tests locally. Use this command to run a test locally:

    bundle exec $test_command
  5. Run this command to bundle your source code, Gemfile, gem installation directory, and the .bundle directory into a single zipped archive:

    zip -r Gemfile .bundle/ vendor/ $(any other source code directory files)