Page tree

Skip to end of metadata
Go to start of metadata

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 following tools are included in the package.

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");

    'Device name’ must always be set in the tool UI and in the JUnit

    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. Choose Parasoft> Preferences.
  2. In the System Properties preferences page, click Add JARs.
  3. Navigate to the appiumextensions.jar file.
  4. Restart SOAtest/Virtualize.

Command Line Installation

Add the appiumextensions.jar file to the system.properties.classpath property in your localsettings 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 in a temporary directory at <temp>/parasoft/xtest/AppiumServerLog-< timestamp>.txt.

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

Node.js Installation DirectorySpecify the directory where Node.js is installed. The directory should contain node.exe (Windows) or bin/node (Linux or Mac). On Windows, this directory is commonly "C:\Program Files\nodejs". You only need to configure this setting if Node.js is not on the path.
Appium Installation Directory

Specify the directory where Appium Server is installed (not Appium Desktop).

If you installed Appium into Node.js, the following directory typically contains the server:

<APPIUM_DESKTOP_INSTALL>/resources/app/node_modules/appium.

If you acquired Appium Server by installing Node.js, the following directory typically contains the server:

%APPDATA%\npm\node_modules\appium (Windows) or /usr/local/lib/node_modules/appium (Linux or Mac).

This setting is not required if APPIUM_HOME is undefined and points to a valid Appium installation.

If Appium was installed on a Mac using HomeBrew (as described in the Appium documentation), you do not need to specify APPIUM_HOME or enter a value in this field.

Port

(Appium flag: --port)

The port on which the Appium Server is running. Default is 4713.
Additional Server Flags (optional)

Specify any optional server flags you want to use.

The –log server flag is not applicable because logging is automatically redirected to the following file:

<temp>/parasoft/xtest/AppiumServerLog-< timestamp>.txt

Device Settings

Platform Name

(Appium flag: --platform-name)

The name of the device's platform. Possible values are iOS or Android. Platform names must be entered exactly as specified (e.g., iOS, not I OS).

Platform Version

(Appium flag: --platform-version)

Specify the version of the platform (e.g., 7.1, 4.4).

Device Name

(Appium flag: --device-name)

For iOS, specify the name of the simulated or physical device.

For Android physical devices, specify the name of the physical device. If you want to launch an emulated Android device, use the Android Virtual Device Name field instead. Enter either a Device Name or an Android Virtual Device name—not both.

Android Virtual Device Name

(Appium flag: --avd)

Specify the name of the Android Virtual Device you want to launch. Enter either a Device Name or an Android Virtual Device name—not both.

App Settings

App Location

(Appium flag: --app)

Specify the location of the executable for the application you want to launch.

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 (e.g., 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.xtest.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.xtest.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 from the shortcut menu.
  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.

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

  • No labels