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

The AWS Documentation website is getting a new look!
Try it now and let us know what you think. Switch to the new look >>

You can return to the original look by selecting English in the language selector above.

Working with Appium Ruby for Android 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://keys.gnupg.net --recv-keys $keys # install rvm along with ruby \curl -sSL https://get.rvm.io | bash -s stable --ruby

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

    Note

    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

    Note

    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 MyTests.zip Gemfile vendor/ $(any other source code directory files)

    This is the MyTests.zip 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 https://console.aws.amazon.com/devicefarm.

  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.

    Tip

    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 Android native application ( 
        Android icon.
    ).

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

    Device Farm processes your .apk file before it continues.

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

    Tip

    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 MyTests.zip 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.

Note

Device Farm does not modify Android 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 Android tests on Ubuntu machines (Ubuntu 14.04.5 LTS). Because gems are platform-specific, we recommend that you use the same Ubuntu version when you package your tests. If you don’t have an Ubuntu machine running this version, you can use Amazon EC2 to create an instance that runs it. For instance type, choose Ubuntu Server 14.04 LTS (HVM). For volume type, choose SSD.

  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 --path=vendor/bundle

    The --path switch installs the gems in the vendor/bundle directory instead of the system location, and then sets this as the default path for future installations by creating a .bundle/config file.

    Note

    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 MyTests.zip Gemfile .bundle/ vendor/ $(any other source code directory files)