Testing mobile applications - veepee-oss/gingerspec GitHub Wiki

The following tutorial was only tested o simulated devices (Simulated Android device in Android Studio or simulated iOS device using Xcode).

The functionality described in this tutorial requires GingerSpec 2.2.1-RC2+. If you are using an older version, check the legacy documentation

Some considerations
Running your feature
Configuring the driver
Using extra capabilities

With Gingerspec, you have the possibility of testing native mobile applications in Android and iOS using Appium. You can also test web applications in a mobile browser (i.e. Chrome for Android/Safari for iOS)

Running Mobile tests is no different than running any other kind of test. You can run then using the console or you can also use your IDE to run your tests either as a cucumber java test or as a TestNG test.

If you add the mobile annotation to your scenarios (or features), GingerSpec will automatically create an appropriate driver for running the different steps in the scenario. This driver will be automatically closed at the end of the scenario and it can be further configured using VM arguments.

@mobile
Feature: Running tests in mobile devices

  Scenario: Opening and closing the app
    Given I open the application
    And I wait '5' seconds
    Given I close the application

  Scenario: Changing orientation
    Given I rotate the device to 'landscape' mode
    And I wait '3' seconds
    Given I rotate the device to 'portrait' mode

Some considerations

Appium provides a desktop application (available in Windows/Linux/Mac) that you can use to bootstrap a standalone Appium server and at the same time provides a UI for you to access the different locators of the mobile app (take a look here and download it from here)

If you would like to run and test mobile applications, a good place to start is by using an emulator. You can create an android emulator for example. The important thing is that the device should be listed when executing "adb devices". If you don't know what ADB (Android debug bridge) is, take a look here

You can also create an iPhone emulator, but for starting an emulator you will need to use Xcode (Mac only). You can see how it is done here

Running your feature

You can then, proceed to run your tests in any of the ways described in the running your tests section. For example, you can choose to directly run all your scenarios with @mobile annotation like this

mvn verify -Dcucumber.filter.tags="@mobile" -Dapp=/path/to/your/app

The only required capability that you need to specify when running your mobile tests is the path of the application that you're gonna be testing. This could be an absolute path to an apk or ipa file or even a remote URL. GingerSpec will try its best to create a set of bare minimum capabilities for initializing the driver.

Working with mobile devices can be a bit tricky at times, and GingerSpec will try to fill the gaps and select the most sensible configuration for you to run your tests. So, unless you configure the driver it will assume the following:

An Appium server running at http://localhost:4723/wd/hub. This is the default URL when you're using Appium server to test locally. You can specify any other URL using -DSELENIUM_GRID=<you-appium_url>
GingerSpec will assume Android as the default platform and will initialize the driver using platformName=Android. You can configure this using VM arguments as explained in the following section.

If platformName=Android (default), the following capabilities are used:

{
    "app": "/path/to/yous/app",
    "automationName": "UiAutomator2",
    "platformName": "Android"
}

If platformName=iOS, the following capabilities are used:

{
    "app": "/path/to/my/app",
    "automationName": "XCUITest",
    "deviceName": "My iphone",
    "platformName": "ios"
}

Configuring the driver

Gingerspec allows you to configure certain capabilities for the initialization of the driver, specifically, the General Capabilities. You can set any of those as VM arguments when running your tests (for example: -DautomationName, -DplatformName, -DplatformVersion, -DdeviceName, etc).

So, for example, if you want to run your test on an iPhone, you will have to run your tests like this.

mvn verify -Dcucumber.filter.tags="@mobile" -Dapp=/path/to/your/app -DplatformName=ios

PRO Tip: if you run your tests using the VM argument -DlogLevel=DEBUG, GingerSpec will print all debug information. Within that information, you should be able to see the final list of capabilities the framework uses before initializing the driver

Using extra capabilities

As explained before, when running features/scenarios that make use of the @mobile annotation, GingerSpec will try its best to construct a set of capabilities. These capabilities are usually the minimum set necessary to initialize the driver (platformName, automationName, etc). You can further configure any of these basic capabilities using the corresponding VM arguments as mentioned before (-DautomationName, -DplatformName, -DplatformVersion, -DdeviceName, etc). This is usually, more than enough to get you started.

However, in a similar fashion to that of selenium tests, you can also set a file with all the capabilities that you want to use in a JSON file. GingerSpec will read that file and use all the capabilities listed to initialize the driver

So, assuming you have the following capabilities.json file:

{
  "app": "https://github.com/appium/appium/raw/master/sample-code/apps/ApiDemos-debug.apk",
  "platformName": "Android",
  "automationName": "UiAutomator2",
  "deviceName": "My android phone"
}

You can indicate GingerSpec to use those capabilities when initializing the driver like this:

mvn verify -Dcucumber.filter.tags="@mobile" -DCAPABILITIES=/path/to/capabilities.json