Mobile Testing with Appium

CodeceptJS allows to test mobile and hybrid apps in a similar manner web applications are tested. Such tests are executed using Appium (opens new window) on emulated or physical devices. Also, Appium allows to test web application on mobile devices.

What makes CodeceptJS better for mobile testing? Take a look. Here is the sample test for a native mobile application written in CodeceptJS:

I.seeAppIsInstalled("io.super.app");
I.click('~startUserRegistrationCD');
I.fillField('~email of the customer', 'Nothing special'));
I.see('[email protected]', '~email of the customer'));
I.clearField('~email of the customer'));
I.dontSee('Nothing special', '~email of the customer'));
I.seeElement({
  android: /'android.widget.Button',
  ios: '//UIAApplication[1]/UIAWindow[1]/UIAButton[1]'
});

This test is easy to read and write. Also it will work both on iOS and Android devices. Doesn't it sound cool?

Setting Up

Ensure that you have CodeceptJS installed (opens new window). You will also need to install Appium (opens new window). We suggest to use appium-doctor (opens new window) to check if your system is ready for mobile testing.

npm i -g appium-doctor

If everything is OK, continue with installing Appium. If not, consider using cloud based alternatives like SauceLabs (opens new window) or BrowserStack (opens new window). Cloud services provide hosted appium with real and emulated mobile devices.

To install Appium use npm:

npm i -g appium

Then you need to prepare application for execution. It should be packed into apk (for Android) or .ipa (for iOS) or zip.

Next, is to launch the emulator or connect physical device. Once they are prepared, launch Appium:

appium

To run mobile test you need either an device emulator (available with Android SDK or iOS), real device connected for mobile testing. Alternatively, you may execute Appium with device emulator inside Docker container.

CodeceptJS should be installed with webdriverio support:

npm install codeceptjs webdriverio --save

Configuring

Initialize CodeceptJS with init command:

npx codeceptjs init

Select Appium helper (opens new window) when asked.

? What helpers do you want to use?
 ◯ WebDriver
 ◯ Protractor
 ◯ Puppeteer
 ◯ Nightmare
❯◉ Appium
 ◯ REST

You will also be asked for the platform and the application package.

? [Appium] Application package. Path to file or url

Check the newly created codecept.conf.js configuration file. You may want to set some additional Appium settings via desiredCapabilities (opens new window)

helpers: {
  Appium: {
    app: "my_app.apk",
    platform: "Android",
    desiredCapabilities: {}
  }
}

Once you configured Appium, create the first test by running

npx codeceptjs gt

BrowserStack Configuration

If you wish to use BrowserStack's Automated Mobile App Testing (opens new window) platform. Configure the Appium helper like this:

helpers: {
  Appium:
    app: "bs://<hashed app-id>",
    host: "hub-cloud.browserstack.com",
    port: 4444,
    user: "BROWSERSTACK_USER",
    key: "BROWSERSTACK_KEY",
    device: "iPhone 7"
}

Here is the full list of capabilities (opens new window).

You need to upload your Android app (.apk) or iOS app (.ipa) to the BrowserStack servers using the REST API before running your tests. The App URL (bs://hashed appid) is returned in the response of this call.

curl -u "USERNAME:ACCESS_KEY" \
-X POST "https://api-cloud.browserstack.com/app-automate/upload" \
-F "file=@/path/to/app/file/Application-debug.apk"

Writing a Test

A test is written in a scenario-driven manner, listing an actions taken by a user. This is the sample test for a native mobile application:

Scenario('test registration', ({ I }) => {
  I.click('~startUserRegistrationCD');
  I.fillField('~inputUsername', 'davert');
  I.fillField('~inputEmail', '[email protected]');
  I.fillField('~inputPassword', '123456');
  I.hideDeviceKeyboard();
  I.click('~input_preferredProgrammingLanguage');
  I.click('Javascript');
  I.checkOption('#io.demo.testapp:id/input_adds');
  I.click('Register User (verify)');
  I.swipeUp("#io.selendroid.testapp:id/LinearLayout1");
  I.see('Javascript'); // see on the screen
  I.see('davert', '~label_username_data'); // see in element
});

Mobile test is pretty similar to a web test. And it is much the same, if you test hybrid app with a web view context inside. However, mobile apps do not have URLs, Cookies, they have other features which may vary on a running platform.

There are mobile-only methods like:

• swipeUp, swipeLeft, ...
• hideDeviceKeyboard,
• seeAppIsInstalled, installApp, removeApp, seeAppIsNotInstalled - Android only

and others (opens new window).

Locating Elements

To start writing a test it is important to understand how to locate elements for native mobile applications. In both Android and iPhone elements are defined in XML format and can be searched by XPath locators.

I.seeElement('//android.widget.ScrollView/android.widget.LinearLayout')'

Despite showing XPath in this guide we **do not recommend using XPath for testing iOS native apps. XPath runs very slow on iOS. Consider using ID or Accessibility ID locators instead.

CSS locators are not supported in native mobile apps, you need to switch to web context to use them.

Elements can also be located by their accessability id, available both at Android and iOS. Accessibility id is recommended to use for locating element, as it rarely changed.

• iOS uses UIAccessibilityIdentification (opens new window)
• Android accessibility id matches the content-description
• Web view uses [aria-label] attribute as accessibility id
• For React Native for Android see our special guide.

If you test React Native application, consider using Detox helper for faster tests.

Add ~ prefix to search for element by its accessibility id:

I.seeElement('~startUserRegistrationButton');

Elements can also have ids, which can be located with # prefix. On Android it it is important to keep full package name in id locator:

I.seeElement('#io.selendroid.testapp:id/inputUsername');

Buttons can be matched by their visible text:

I.tap('Click me!');
I.click('Click me!');

Native iOS/Android locators can be used with android= and ios= prefixes. Learn more (opens new window).

But how to get all those locators? We recommend to use Appium Inspector (opens new window).

For Android you can use UI Automator Viewer bundled with Android SDK:

Hybrid Apps and Contexts

Mobile applications may have different contexts. For instance, there can be native view and web view with a browser instance in it.

To execute commands in context of a webview use within('webview') function:

I.click('~startWebView');
within('webview', () => {
  I.see('Preferred car');
  I.click('Send me your name!');
});

It will locate first available webview, switch to it, and switch back to native application after. Inside WebView all browser features are enabled: CSS locators, JavaScript, etc.

To set a specific context use { web: 'webview.context' } instead:

within({webview: 'MyWEBVIEW_com.my.app'}, () => );

Alternatively use switchToWeb or switchToNative methods to switch between contexts.

I.click('~startWebView');
I.switchToWeb();
I.see('Preferred car');
I.click('Send me your name!');
I.switchToNative();

To get a list of all contexts use grabAllContexts method:

let contexts = await I.grabAllContexts();

Cross-Platform Testing

It is often happen that mobile applications behave similarly on different platforms. Can we build one test for them? Yes! CodeceptJS provides a way to specify different locators for Android and iOS platforms:

I.click({android: /'//android.widget.Button', ios: '//UIAApplication[1]/UIAWindow[1]/UIAButton[1]'});

In case some code should be executed on one platform and ignored on others use runOnAndroid and runOnIOS methods:

I.runOnAndroid(() => {
  I.click('Hello Android');
});
I.runOnIOS(() => {
  I.click('Hello iOS');
});

The same code can be shared for web applications as well. To execute some code in web browser only, use I.runInWeb:

I.runInWeb(() => {
  I.amOnPage('/login'); // not available for mobile
  I.fillField('name', 'jon');
  I.fillField('password', '123456');
  I.click('Login');
  I.waitForElement('#success'); // no available for mobile
});

Just as you can specify android, and ios-specific locators, you can do so for web:

I.click({web: '#login', ios: '//UIAApplication[1]/UIAWindow[1]/UIAButton[1]'});