Testing mobile applications (legacy) - 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.1.0-RC1+

In windows, you may need to use quotes ('') when passing variables via maven!
mvn verify -D'it.test'='com.privalia.mytestproject.mypackage.CucumberRestIT'

Prerequisites
Running mobile applications
- Using a Selenium Grid
- Using the Appium desktop client
  - Running your feature

With Gingerspec, you have the possibility of testing native mobile application in Android and iOS using Appium

Prerequisites

Mobile applications are executed using a MobileDriver (which is very similar to the WebDriver used in Selenium tests), so, the runner class has a very similar structure to the selenium runner classes. Check out this as an example. Notice that the only real difference is that dataProvider = "availableMobileBrowsers" (instead of availableUniqueBrowsers). This is for indicating GingerSpec to only consider connected devices that have platform as iOS or Android.

The feature referenced in the runner class should include the @mobile annotation at the beginning (in a very similar way that the @web annotation works for Selenium features). Check this feature for reference.

Since Appium is a NodeJS package, you will need to first install NodeJS on your system and then follow the instructions on the Appium web page. To verify that Appium is correctly installed on your system just execute the command:

appium -v

In your system terminal. It should return the version of Appium installed.

Running mobile applications

There are to ways of running mobile features:

1.- The first is by connecting your mobile devices to a selenium Grid using Appium as a node and running your features in the exact same way as you would with selenium features. This method allows you to test the same feature on several devices.

2.- Using Appium directly as the server. You can use the Appium desktop client (available for Windows/Mac/Linux) to create a sort of standalone server and run your tests directly against it, in a similar way as you would run your selenium tests with a standalone selenium node. this method is probably the best for local development.

Using a Selenium Grid

Starting the grid/hub

You will first have to start a Selenium Grid/Hub. This process is exactly the same as the one described here. Once it is up and running, you should be able to access the grid console in http://localhost:4444/grid/console

Starting the nodes

The nodes, in this case, will be simulated Android or iOS devices

For Android

1.- Start an android emulator: You can use an android emulator (the emulated device must have ADB debugging on), or you can use a real device. The important thing is that the device should be listed when executing "adb devices". If you dont know what ADB (Android debug bridge) is, take a look here

2.- create a file nodeconfig-android.json (or whichever name you prefer) with the following capabilities:

{
    "capabilities": [
        {
            "platformName": "Android",
            "automationName": "UiAutomator2",
            "deviceName": "Android Emulator",
            "app": "/full/path/to/file/app.apk"
        }
    ],
    "configuration": {
        "cleanUpCycle": 2000,
        "timeout": 30000,
        "proxy": "org.openqa.grid.selenium.proxy.DefaultRemoteProxy",
        "url": "http://127.0.0.1:4723/wd/hub",
        "maxSession": 1,
        "register": true,
        "registerCycle": 5000,
        "hubPort": 4444,
        "hubHost": "127.0.0.1",
        "hubProtocol": "http",
        "role": "node"
    }
}

Notice that you have to specify the app to automate. You can also use -DAPP via maven variable an provide the full path of the app file (or remote web address)

3.- Run the file using Appium in the following way

appium -p 4723 --nodeconfig nodeconfig-android.json

4.- You should see your device listed as a node in the grid console :)

For iOS

The process for iOS is basically the same as for Android, but for starting an emulator you will need to use Xcode (Mac only). You can see how it is done here

2.- create a file nodeconfig-ios.json (or whichever name you prefer) with the following capabilities:

{
    "capabilities": [
        {
            "platformName": "iOS",
            "automationName": "XCUITest",
            "deviceName": "iPhone 8",
            "app": "/full/path/to/file/app.zip"
        }
    ],
    "configuration": {
        "cleanUpCycle": 2000,
        "timeout": 30000,
        "proxy": "org.openqa.grid.selenium.proxy.DefaultRemoteProxy",
        "url": "http://127.0.0.1:4733/wd/hub",
        "maxSession": 1,
        "register": true,
        "registerCycle": 5000,
        "hubPort": 4444,
        "hubHost": "127.0.0.1",
        "hubProtocol": "http",
        "role": "node"
    }
}

Notice that you have to specify the app to automate. You can also use -DAPP via maven variable an provide the full path of the app file (or remote web address). The device name should match the device name in the simulator (int his case, iPhone 8)

3.- Run the file using appium in the following way

appium -p 4733 --nodeconfig nodeconfig-ios.json

4.- You should see your device listed as a node in the grid console :)

Running your feature

Now you can run your feature file in basically the same way that you would with Selenium features that make use a Selenium Grid (only that in this case the connected nodes are mobile devices). Assuming your grid is running in 127.0.0.1:4444:

mvn verify -Dit.test=myproject.mypackage.MymobileRunnerClassIT -DSELENIUM_GRID=127.0.0.1:4444

-Dit.test if the reference to your runner class, this is just an example

Using the Appium desktop client

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

For Android

1.- Start the Android emulator in the same way as described earlier in this tutorial

2.- Once the app is running, you can create a session with the following minimum capabilities

"platformName": "Android",
"automationName": "UiAutomator2",
"deviceName": "Android Emulator",
"app": "/full/path/to/file/app.apk"

For iOS

1.- Start the iOS simulator in the same way as described earlier in this tutorial

2.- Once the app is running, you can create a session with the following minimum capabilities

"platformName": "iOS",
"automationName": "XCUITest",
"deviceName": "iPhone 8",
"app": "/full/path/to/file/app.zip"

The device name should match the device name in the simulator (int his case, iPhone 8)

Running your feature

Now you can run your feature file in basically the same way that you would with Selenium features that make use of a Selenium Standalone Node.

Now, assuming your session is running in 127.0.0.1:4723, you can use the @mobile tag for running the test:

mvn verify -Dcucumber.options="--tags @mobile" -DSELENIUM_NODE=localhost:4723

(This will execute all feature files that contain the @mobile tag). You can also directly execute the runner class like this:

mvn verify -Dit.test=myproject.mypackage.MymobileRunnerClassIT -DSELENIUM_NODE=127.0.0.1:4723

'myproject.mypackage.MymobileRunnerClassIT' is the reference to your runner class, this is just an example