Mobile Testing

CodeceptJS allows to test mobile and hybrid apps in a similar manner web applications are tested. Such tests are executed using Appium 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('davert@codecept.io', '~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. You will also need to install Appium. We suggest to use appium-doctor 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 or BrowserStack. 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 -g codeceptjs webdriverio

Configuring

Initialize CodeceptJS with init command:

codeceptjs init

Select Appium helper 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

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

Once you configured Appium, create the first test by running

codeceptjs gt

BrowserStack Configuration

If you wish to use BrowserStack's Automated Mobile App Testing 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.

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', 'davert@codecept.io');
  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:

and others.

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')'

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.

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.

But how to get all those locators? We recommend to use Appium Inspector.

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]'});