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

Working with Appium Python for Android Applications and AWS Device Farm

This section describes how to configure, package, and upload your Appium Python 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.

For a sample app, see Device Farm Sample App for Android on GitHub.

For a Device Farm sample test, see Appium Python Sample Tests for the Device Farm Sample Android App on GitHub.

Version Information

  • Currently, Device Farm supports Python version 2.7.6 (pip version 1.5.4) for running Appium Python tests.

  • Device Farm supports all Appium server versions 1.6.5 and above. 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

    To use all the features of the framework, like annotations, choose a custom test environment, and use the AWS CLI or the Device Farm console to upload a custom test spec.

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

Step 1: Create a Zipped Test Package File

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


The following instructions are based on Linux x86_64 and macOS. In the currently supported scheme, Device Farm requires that you package your Appium Python tests on Linux x86_64 if your tests contain non-universal Python wheels dependencies. For the platform on which you execute a command, the wheels tools gather your .whl dependent files under the wheelhouse/ folder. If you execute the Python wheel command on a platform other than Linux x86_64, you gather the flavor of a non-universal wheel dependency for the platform, which might lead to errors when you execute your tests on Device Farm.

  1. We strongly recommend that you set up Python virtualenv for developing and packaging tests so that unnecessary dependencies are not included in your app package.

    $ virtualenv workspace $ cd workspace $ source bin/activate


    • Do not create a Python virtualenv with the --system-site-packages option, because it inherits packages from /usr/lib/pythonx.x/site-packages or the location of your global site-packages directory. This can result in including dependencies in your virtual environment that are not required by your tests.

    • You should also verify that your tests do not use dependencies that are dependent on native libraries, because these native libraries might not be present on the instance where these tests run.

  2. Install py.test in your virtual environment.

    $ pip install pytest
  3. Install the Appium Python client in your virtual environment.

    $ pip install Appium-Python-Client
  4. Store all Python test scripts under the tests/ folder in your workspace.

    ─ workspace └─ tests/ (your tests go here)
  5. Run this command from your virtual environment workspace folder to show a list of your tests without running them.

    $ py.test --collect-only tests/

    Confirm the output shows the tests that you want to run on Device Farm.

  6. Run the following command in your workspace to generate the requirements.txt file:

    $ pip freeze > requirements.txt
  7. Run the following command in your workspace to generate the wheelhouse/ folder:

    $ pip wheel --wheel-dir wheelhouse -r requirements.txt
  8. You can use the following commands to clean all cached files under your tests/ folder:

    $ find . -name '__pycache__' -type d -exec rm -r {} + $ find . -name '*.pyc' -exec rm -f {} + $ find . -name '*.pyo' -exec rm -f {} + $ find . -name '*~' -exec rm -f {} +
  9. Zip the tests/ folder, wheelhouse/ folder, and the requirements.txt file into a single archive:

    $ zip -r tests/ wheelhouse/ requirements.txt

    Your workspace should look like this:

    ─ workspace ├─ tests/ ├─ ├─ requirements.txt └─ wheelhouse/

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


    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 Python to configure your test.

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

  10. Choose the Appium version you are using.

  11. Choose Next step, and then follow the instructions to select devices and start the run. For more information, see Create a Test Run in AWS Device Farm.


Device Farm does not modify Android Appium Python tests.

Step 3: Take Screenshots of Your Android Appium Python Tests (Optional)

You can take screenshots as part of your tests.

When Device Farm runs your Appium Python test, the service sets the following system properties that describe the configuration of the Appium server with which you're communicating:

  • appium.screenshots.dir: Path where the screenshots are saved.

  • appium.server.address: Host address of the Appium server.

  • appium.server.port: Port on which the Appium server is listening.

Device Farm sets the SCREENSHOT_PATH property to a fully qualified path on the local file system where Device Farm expects Appium screenshots to be saved. The test-specific directory where the screenshots are stored is defined at runtime. The screenshots are pulled into your Device Farm reports automatically. To view the screenshots, in the Device Farm console, choose the Screenshots section.

The following example shows how to use and consume the appium.screenshots.dir property to capture an Appium screenshot that is pulled into your Device Farm report.

public boolean takeScreenshot(final String name) { String screenshotDirectory = System.getProperty("appium.screenshots.dir", System.getProperty("", "")); File screenshot = ((TakesScreenshot) driver).getScreenshotAs(OutputType.FILE); return screenshot.renameTo(new File(screenshotDirectory, String.format("%s.png", name))); }