Working with Appium Java TestNG for iOS and AWS Device Farm

This section describes how to configure, package, and upload your Appium Java TestNG tests for iOS 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 and links to working tests, see Device Farm Sample App for iOS on GitHub.

Version Information

Currently, Device Farm supports Java 8 for running Appium Java 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.

Topics

Step 1: Configure Your Appium Test Package
Step 2: Configure Your Tests to Run with Cucumber (Optional)
Step 3: Create a Zipped Test Package File
Step 4: Upload Your Test Package to Device Farm
Step 5: Take Screenshots of Your iOS Appium Java TestNG Tests (Optional)

Step 1: Configure Your Appium Test Package

Use the following instructions to configure your test package. The Appium Java TestNG tests for your iOS application must be contained in a .zip file.

Update Your Maven Settings

Modify pom.xml to set packaging to a JAR file:


<groupId>com.acme</groupId>
<artifactId>acme-android-appium</artifactId>
<version>1.0-SNAPSHOT</version>
<packaging>jar</packaging>

Modify pom.xml to use maven-jar-plugin to build your tests into a JAR file.

The following plugin builds your test source code (anything in the src/test directory) into a JAR file:


<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-jar-plugin</artifactId>
  <version>2.6</version>
  <executions>
    <execution>
      <goals>
        <goal>test-jar</goal>
      </goals>
    </execution>
  </executions>
</plugin>

Modify pom.xml to use maven-dependency-plugin to build dependencies as JAR files.

The following plugin copies your dependencies into the dependency-jars directory:


<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-dependency-plugin</artifactId>
  <version>2.10</version>
  <executions>
    <execution>
      <id>copy-dependencies</id>
      <phase>package</phase>
      <goals>
        <goal>copy-dependencies</goal>
      </goals>
      <configuration>
        <outputDirectory>${project.build.directory}/dependency-jars/</outputDirectory>
      </configuration>
    </execution>
  </executions>
</plugin>

Step 2: Configure Your Tests to Run with Cucumber (Optional)

If you use Cucumber with your Appium Java TestNG for iOS tests, use this step to configure Maven with your Cucumber settings. Otherwise, skip to the next step.

Note

You must run your tests in a custom test environment to use Cucumber with your Appium tests.
1. Modify pom.xml to add cucumber-java as a dependency.
```

<dependency>
    <groupId>io.cucumber</groupId>
    <artifactId>cucumber-java</artifactId>
    <version>4.0.0</version>
</dependency>
```
2. Modify pom.xml to add cucumber-testng as a dependency.
```

<dependency>
    <groupId>io.cucumber</groupId>
    <artifactId>cucumber-testng</artifactId>
    <version>4.0.0</version>
</dependency>
```

Step 3: Create a Zipped Test Package File

Save the following XML assembly to src/main/assembly/zip.xml.

The following XML is an assembly definition that, when configured, instructs Maven to build a .zip file that contains everything in the root of your build output directory and the dependency-jars directory:


<assembly
    xmlns="http://maven.apache.org/plugins/maven-assembly-plugin/assembly/1.1.0"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://maven.apache.org/plugins/maven-assembly-plugin/assembly/1.1.0 http://maven.apache.org/xsd/assembly-1.1.0.xsd">
  <id>zip</id>
  <formats>
    <format>zip</format>
  </formats>
  <includeBaseDirectory>false</includeBaseDirectory>
  <fileSets>
    <fileSet>
      <directory>${project.build.directory}</directory>
      <outputDirectory>./</outputDirectory>
      <includes>
        <include>*.jar</include>
      </includes>
    </fileSet>
    <fileSet>
      <directory>${project.build.directory}</directory>
      <outputDirectory>./</outputDirectory>
      <includes>
        <include>/dependency-jars/</include>
      </includes>
    </fileSet>
  </fileSets>
</assembly>

Modify pom.xml to use maven-assembly-plugin to package tests and all dependencies into a single .zip file.

The following plugin uses the preceding assembly to create a .zip file named zip-with-dependencies in the build output directory every time mvn package is run:


<plugin>
  <artifactId>maven-assembly-plugin</artifactId>
  <version>2.5.4</version>
  <executions>
    <execution>
      <phase>package</phase>
      <goals>
        <goal>single</goal>
      </goals>
      <configuration>
        <finalName>zip-with-dependencies</finalName>
        <appendAssemblyId>false</appendAssemblyId>
        <descriptors>
          <descriptor>src/main/assembly/zip.xml</descriptor>
        </descriptors>
      </configuration>
    </execution>
  </executions>
</plugin>

Build, package, and verify. For example:


$ mvn clean package -DskipTests=true
$ tree target
.
|— acme-android-appium-1.0-SNAPSHOT.jar (this is the JAR containing everything built from the ./src/main directory)
|— acme-android-appium-1.0-SNAPSHOT-tests.jar (this is the JAR containing everything built from the ./src/test directory)
|— zip-with-dependencies.zip (this .zip file contains all of the items)
`— dependency-jars  (this is the directory that contains all of your dependencies, built as JAR files)
      |— com.some-dependency.bar-4.1.jar
      |— com.another-dependency.thing-1.0.jar
      |— joda-time-2.7.jar
      |— log4j-1.2.14.jar
      |— (and so on...)

Use the Device Farm console to upload the test package.

Note

If you receive an error that says annotation is not supported in 1.3, add the following to pom.xml:


<plugin>
  <artifactId>maven-compiler-plugin</artifactId>
  <configuration>
    <source>1.7</source>
    <target>1.7</target>
  </configuration>
</plugin>

Step 4: Upload Your Test Package to Device Farm

You can use the Device Farm console to upload your tests.

Sign in to the Device Farm console at https://console.aws.amazon.com/devicefarm.
If you see the AWS Device Farm console home page, enter a name for your project, and then choose Create project. Refresh the page to see your new project.
If you already have a project, you can upload your tests to it.
Open your project, and then choose Create a new run.
On the Choose your application page, choose iOS native application ( ), and then choose Upload.
Browse to and choose your iOS app file. The file must be an .ipa file.
Choose Next step.
On the Configure a test page, choose Appium Java TestNG, and then choose Upload.
Browse to and choose the .zip file that contains your tests. The .zip file must follow the format described in Step 1: Configure Your Appium Test Package.
Choose the Appium version you are using.
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 Java TestNG tests.

Step 5: Take Screenshots of Your iOS Appium Java TestNG Tests (Optional)

You can take screenshots as part of your tests.

When Device Farm runs your Appium Java TestNG 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)));
}

Warning Javascript is disabled or is unavailable in your browser.

To use the AWS Documentation, Javascript must be enabled. Please refer to your browser's Help pages for instructions.

Document Conventions

« Previous Next »