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

Working with Appium Ruby for Web 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 web application ( 
        HTML 5 web icon.

        Choose an application in the Device Farm console.
  6. 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.

  7. Choose Appium Ruby to configure your test.

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

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

  10. 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.

  11. Choose devices and start the run.

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


Device Farm does not modify web application Appium Ruby tests.