Test framework for automating mobile apps with appium using webdriverio & typescript!

---

About | Getting Started | Installation | Writing Tests | Page Objects | Finding Elements | Reports

About

Currently this framework has been developed to run scripts in ANDROID platform with real device.

The tests run both on Android Native App and Mobile Browser. Chrome browser is configured currently for running browser tests.

Tech Stack

• Appium - This is the node server which interacts with the mobile devices
• WebdriverIO - It is the selenium webdriver api bindings for node.js, It has a very simple api which could be used to automate web & browser apps in a fast and scalable way.
• Typescript(Javascript) - It is the superset of javascript which has additional static typings and features like JAVA and other languaes. Now you could write your code which compiles to pure javascript.
• Cucumber - The popular BDD test framework which helps us write automated tests.

Getting Started

Pre-requisites

1. NodeJS installed globally in the system. https://nodejs.org/en/download/

2. JAVA(jdk) installed in the system.

3. Andriod(sdk) installed in the system.

4. Set JAVA_HOME & ANDROID_HOME paths correctly in the system.

5. Chrome browser installed.

6. Text Editor/IDE (Optional) installed-->Sublime/Visual Studio Code/Brackets.

Tip: Install npm install -g appium-doctor and run it from the command-line which checks if your java jdk and android sdk paths are set correctly or not.

Installation

Setup Scripts

• Clone the repository into a folder
• Go inside the folder and run following command from terminal/command prompt

npm install 

• All the dependencies from package.json and typescript typings would be installed in node_modules folder.

Tip: Use Yarn to install your modules npm install -g yarn as it caches & locks them which would help us install correct versions of modules across various platforms without any issues. This project is configured with yarn.lock file. So you could make use of it.

Run Tests

• First step is to start the appium server, This project includes the appium node module so you don't have to download it externally. You can run the appium server by the following npm command.

npm run appium

• Next you have to transpile/compile your typescript files to javascript files, you could do this by running the command -

npm run build

Next step is to execute the config files. This project has 2 config files -

• wdio.app.config.js - This config file is used to run tests in real mobile native apps. You would have to change the appium settings to run tests in your device.

capabilities: [
{
    appiumVersion: '1.7.1',                             // Appium module version
    browserName: '',                                   // browser name is empty for native apps
    platformName: 'Android',
    app: './app/LGCalculator.apk',                     // Path to the native app
    appPackage: 'com.android.calculator2',             // Package name of the app
    appActivity: 'com.android.calculator2.Calculator', // App activity of the app
    platformVersion: '5.1.1',                         // Android platform version of the device
    deviceName: 'THF755e0384',                       // device name of the mobile device
    waitforTimeout: waitforTimeout,
    commandTimeout: commandTimeout,
    newCommandTimeout: 30 * 60000,
}
],

To know your device name you could run the adb devices command which comes out of the box from Android SDK.

The node command to run Native app tests of this project is -

npm run app-test

The above command which is set in package.json internally calls the WebdriverIO's binary wdio ./config/wdio.app.config.js and runs the app config file.

• wdio.browser.config.js - This config file is used to run tests in the chrome browser of the configured mobile device. The appium settings would looks like this-

capabilities: [
{
    appiumVersion: '1.7.1',
    browserName: 'chrome',  // browser name should be specified
    platformName: 'Android',
    platformVersion: '5.1.1',
    deviceName: 'THF755e0384', // device name is mandatory
    waitforTimeout: waitforTimeout,
    commandTimeout: commandTimeout,
    newCommandTimeout: 30 * 60000,
}
],

The node command to run browser tests of this project is -

npm run browser-test

The above command internally calls the WebdriverIO's binary wdio ./config/wdio.browser.config.js and runs the browser config file.

Run Test Suite

You could run both the native app and browser tests by running the following command -

npm test

The above command internally calls npm run app-test and npm run browser-test.

Writing Tests

Cucumber framework has been integrated with thi project, WebdriverIO's wdio-cucumber-framework adapter helps write BDD style tests with Features & Step Definitions.

const {Given, When, Then} = require('cucumber');
import {expect} from 'chai';
import {CalculatorPageObject} from '../pages/calcPage';

const calc: CalculatorPageObject = new CalculatorPageObject();

Given(/^I am on my mobile calculator app$/, () => {
    const title = browser.getText('android.widget.TextView');
    expect(title).to.equal('Calculator');
});

Page Objects

This framework is strictly written using page-object design pattern.

class GooglePageObject {
    public get searchTextBox(): any { return browser.element('#lst-ib'); }
    public get searchButton(): any { return browser.element('button[name="btnG"]'); }
    public get results(): any { return browser.waitForVisible('#rso', 5000); }
    public get firstLink(): any { return browser.element('#rso div._H1m._ees'); }
}
/*
Public Interface - export instances of classes
**/
export const GooglePage = new GooglePageObject()

Finding-Elements

Finding elements in mobile apps and browser's could be tricky sometimes.

• Best way to find elements in native mobile apps is using UIAutomatorViewer .This supports Android 4.3 and above only, If you are using android version less than that, you could use Selendriod
• Best way to find elements in mobile browser is by Remote debugging with Chrome DevTools. I personally find it lot easier & hassle free. You could find detail steps about it in this blog

Reports

Currently this project has been integrated with Allure-Reports. WebdriverIO's wdio-allure-reporter helps us generate detailed reports of our mobile automated tests. Once the test execution is finished you would find the allure-results folder generated automatically. Then you would have to run the following command to generate HTML Report

npm run report

Caveat: Chrome browser has an issue rendering the AJAX requests from local files generated by allure, You could use Firefox for seeing the html report. You could find more details about this issue here

License

MIT License

Copyright (c) 2021 Sivasankaramalan Gunasekarasivam