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

Working with Appium Python for iOS 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 iOS on GitHub.

For a Device Farm test sample, see Appium Python Sample Tests for the Device Farm Sample iOS 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 Appium server versions 1.7.2, 1.7.1, and 1.6.5. You can also use newer versions with the avm command in a custom test environment. For example, to use Appium server version 1.8.1, add these commands to your test spec YAML file:

    phases: install: commands: # To install a newer version of Appium such as version 1.8.1: - export APPIUM_VERSION=1.8.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.

Note

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

    Tip

    • 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 test_bundle.zip tests/ wheelhouse/ requirements.txt

    Your workspace should look like this:

    ─ workspace ├─ tests/ ├─ test_bundle.zip ├─ 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 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.

  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.

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

Note

Device Farm does not modify iOS Appium Python tests.

Step 3: Take Screenshots of Your iOS 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("java.io.tmpdir", "")); File screenshot = ((TakesScreenshot) driver).getScreenshotAs(OutputType.FILE); return screenshot.renameTo(new File(screenshotDirectory, String.format("%s.png", name))); }