The Appium Mobile Extensions package contains tools that help you execute JUnit-format Appium mobile tests for Android and iOS apps (native, web, and hybrid). In this section:

About the Tools

The package includes the Appium Mobile Executor tool, Start Appium Server tool, and Stop Appium Server tool. Each is described below.

Appium Mobile Executor Tool

The Appium Mobile Executor tool enables you to execute JUnit-format Appium tests in conjunction with the various other types of tests you can run with SOAtest. It supports JUnit functional tests for Android and iOS apps (native, web, and hybrid). Tests can execute on the Android emulator, the iOS simulator, or native devices (iOS or Android). Support for the specific OS versions you want to test depends on the Appium server. See the Appium documentation for more information.

You can design and execute a single, holistic test scenario that orchestrates mobile tests as part of a broader sequence of events. For example, you can use the intuitive SOAtest interface to:

• run a single scenario that performs several actions to set up a test environment or test data
• run unit and service-level tests
• execute mobile tests

You can extract values from any of these for validations and/or to populate other tools involved in the end-to-end test scenario.

Start Appium Server Tool

This tool automates the process of starting the Appium application on a Node.js Server with the desired configuration.

Stop Appium Server Tool

This tool automates the process of closing all server instances opened with a Start Appium Server tool.

Requirements

• SOAtest 9.10.x or later running Eclipse with Java 8 or later.
• Appium Server 1.6.5 or later. You can either install the Desktop App or Appium on a Node.js server.
• The prerequisites and configuration that Appium expects for the type of tests you plan to run. See the Appium documentation for details, especially Setting up the Appium Client.

• If you plan to connect with the emulator, the JUnit must have the Desired Capabilities set as described under Appium Concepts or the Desired Capabilities documentation. For example:

  DesiredCapabilities capabilities = new DesiredCapabilities(); capabilities.setCapability("platformName", "Android"); capabilities.setCapability("deviceName", "testDevice"); capabilities.setCapability("platformVersion", "4.4.2"); capabilities.setCapability("app", "C:\path\to\application.apk");

  This is an Appium requirement. Other settings must be set in either the JUnit test itself or in the tool UI. Settings specified in the tool UI will override values set in the JUnit.

• Appium Selenium WebDriver tests written in JUnit 3.8.x and 4 format are supported. Tests should be written and configured according to Appium requirements as described in the Running tests help topic.

Installation

The tool set can be installed from the UI or command line.

UI Installation

1. Go to Parasoft > Preferences and click System Properties.
2. Click Add JARs and choose the appiumextensions.jar file.
3. Click Apply.
4. Restart SOAtest/Virtualize.

Command Line Installation

Add the appiumextensions.jar file to the system.properties.classpath property in your settings properties file. For example:

system.properties.classpath=<path to jar>/ appiumextensions.jar

General Configuration

Your environment needs to be set up for the particular mobile platforms that you want to run tests on. See the Appium documentation for details, especially requirements and setup.

Start Appium Server Tool Usage

You can add Start Appium Server tools as standalone tools with the Add Test wizard (see Adding Projects, .tst files, and Test Suites). Place the Start Appium Server tool before the Appium Mobile Executor tool in the test suite.

The Start Appium Server tool output will be saved in a AppiumServerLog-< TIMESTAMP>.txt file in a temporary directory at <TEMP>/parasoft/xtest/.

Start Appium Server Tool Configuration

You must configure the tool to launch Appium on the device or emulator before you can run it.

Environment Settings

Device Settings

App Settings

Specific Configurations for Android

ANDROID_HOME must be defined if you plan to launch Android devices. For example, this variable can be set to %LOCALAPPDATA%\Android\Sdk on Windows. 

If you're using a physical Android device plugged into the machine, specify the Device Name setting and leave Android Virtual Device Name setting empty.

If you're using an emulated Android device, specify the Android Virtual Device Name setting and leave the Device Name setting empty. In the following example, Start Appium Server settings are configured for an Android test running on an emulator:

Specific Configurations for iOS

The following sample ~/.bash_profile adds Node.js to the PATH and sets the APPIUM_HOME variable based on the Appium Desktop application for OSX:

If Appium was installed with the Appium Homebrew package manager and you have a symbolic link at the path /usr/local/bin/appium, you do not need to complete the Node.js Installation and Appium Installation fields in the Environment Settings page. Use the which appium command to verify:

In the following example, Start Appium Server settings are configured for an iOS application based on the Appium Desktop app:

You can use the Device Name setting for simulators and for physical devices. Always leave the Android Virtual Device Name setting empty.

Stop Appium Server Tool Usage

You can add Start Appium Server tools as standalone tools with the Add Test wizard (see Adding Projects, .tst files, and Test Suites). Place the Stop Appium Server tool after the Appium Mobile Executor and Start Appium Server tools in the test suite.

You can add the tool as a teardown test if you want to ensure that it gets run even if any tools in the containing suite fail.

No configuration is required for this tool. It is preconfigured to close all server instances opened with a Start Appium Server tool. The tool will not shut down the following components:

• Android emulators or iPhone simulators (because Appium does not handle these operations).
• Servers that were not started with the Start Appium Server tool.

Appium Mobile Executor Usage

You can add Appium Mobile Executor tools as standalone tools with the Add Test wizard (see Adding Projects, .tst files, and Test Suites).

The test's class folder or .jar file must contain the JUnit that you want executed. Other dependencies can be included in the jar/folder, added to the system properties, or both. The tool looks at the jar/folder first, then the system properties (if needed). The Appium Server needs to be running before the Appium Executor can run any JUnit tests. The server will not be started automatically.

Running a Single JUnit Test Method

1. Specify the test's class folder or jar file, as well as the test class and test method you want to run.
   
2. (Optional) If you want to dynamically change JUnit values from this tool, enter the key-value pairs separated by a semicolon in the Data field.
   

You can access the variables from within your JUnit source code using Java's System Properties object. For example:

String lastName = System.getProperty("lastName")

Running All Test Methods in a Class

1. Specify the test's class folder or jar file, as well as the test class. Leave the Method field empty.
   
2. (Optional) If you want to dynamically change JUnit values from this tool, enter the key-value pairs separated by a semicolon in the Data field.
   

You can access the variables from within your JUnit source code using Java's System Properties object. For example: 

String lastName = System.getProperty("lastName")

Reviewing Execution Details

When the test begins, your application will be launched in the associated simulator, emulator, or device. As the tests execute, you can watch the simulator/emulator/device to see how the test actions impact the application. Appium-related execution details will be reported in the Appium Server window.

Viewing Results

Execution details and results will be reported in the Console view. Additionally, any test failures detected will be reported in the Quality Tasks view:

Reporting Messages from your JUnit Test to the Console

To report messages from within your JUnit test to the console (for example, for debugging or to gain insight into execution details):

Application.showMessage("this displays in the console");

To access the Application Context, your JUnit needs to import the com.parasoft.api package. Be sure to add <INSTALL_DIR>/plugins/com.parasoft.ptest.libs.web_[version]/root/com.parasoft.api.jar to your Java project classpath to enable this import.

Retrieving Data from a JUnit Test

SOAtest/Virtualize can retrieve data from your JUnit test and it in other SOAtest/Virtualize tools. You need to configure the JUnit to indicate which values you want stored and attach an appropriate tool to the JUnit Output of the executor tool. The data will be passed to the attached tool in XML format. For example, you could send the data to a Diff, XML Assertor, or XML Data Bank tool.

Configuring the JUnit Output

Before you can use the JUnit Output type, your JUnit must access the application context and store the desired values in a standard Java Map under the "custom_tool_junit_output" key. The Appium Mobile Executor tool will check the application context for the stored map and convert it to XML that gets passed to the tool's "JUnit Output" output. The map's keys and values must be strings. If you want the JUnit to return a page source string, put the entire source into a value in the map (this is demonstrated in the example below).

To access the application context, your JUnit needs to import the com.parasoft.api package. Be sure to add <INSTALL_DIR>/plugins/com.parasoft.ptest.libs.web_<VERSION>/root/com.parasoft.api.jar to your Java project classpath to enable this import.

Sending the Data to Another Tool

1. Right-click the Appium Mobile Executor tool and choose Add Output.
2. Choose JUnit Output (on the left) and the tool that you want to receive this output (on the right).
3. Click Finish.

Example

Assume that you want to get an app's layout source in XML, then send it to an XML Data Bank so that you can extract a value from the mobile app that can be used in a subsequent test.

You would start by creating a JUnit that 1) constructs a map containing the values that should be sent to the XML Data Bank, and 2) puts that map into the application context. The values in the map will be converted to an XML document that's passed to any tools attached to the JUnit Output:

@org.junit.Test
public void testAccessibilityPage() throws Exception {
  WebElement element = driver.findElement(By.xpath("//android.widget.TextView[1]"));
  element.click();
  // Create map representing name-value pairs for XML
  Map<String, String> map = new HashMap<String, String>();
  // Get App's layout source in XML
  String source = driver.getPageSource();
  // Place source in map with key "source"
  map.put("source", source);
  // Get the Parasoft Scripting Context
  ScriptingContext context = Application.getContext();
  // Place the map in the context with the custom_tool_junit_output
  context.put("custom_tool_junit_output", map);
}

Add an Appium Mobile Executor tool configured to run this test next. Give the tool a JUnit output that sends this data to an XML Data Bank tool.

From here, you could specify which values to extract, then use them in other tools. Note that the content of the map appears below a <root> element within the XML document that gets passed to the tools attached to the JUnit output.

Third-party Content

This tool set includes items that have been sourced from third parties as outlined below.

• Appium (Apache License 2.0)
• JUnit (Eclipse Public License 1.0)

Additional license details are available in this plugin's licenses folder.