Build your own Mobile Automation Framework — Appium 2.x, WebDriverIO and Typescript

Rochelle Abeywickrama

6 min read3 days ago

First, let me answer why to select Appium 2.xx with WebdriverIO and Typescript?

Using Appium 2.0, WebdriverIO, and TypeScript for mobile test automation offers several advantages:

1. Appium 2.0 — Modern Mobile Automation

Appium 2.0 brings significant improvements over Appium 1.x:

Modular Architecture: Supports custom drivers and plugins, making it more flexible.
Better Performance: Optimized architecture reduces execution time.
Improved Extensibility: You can create and use plugins to enhance automation capabilities.
Enhanced Driver Management: Supports multiple driver versions for different platforms (iOS/Android).
Future-Proof: Keeps up with the latest mobile OS updates.

2. WebdriverIO — Robust and Developer-Friendly

WebdriverIO is a powerful automation framework that integrates well with Appium:

Unified Automation: Can be used for mobile (Appium), web (Selenium), and desktop automation.
Simple Configuration: Offers easy setup with wdio CLI and configuration options.
Built-in Test Runners: Supports Mocha, Jasmine, and Cucumber.
Parallel Execution: Runs tests faster using parallel execution.
Rich Plugin Ecosystem: Offers built-in reporters, assertion libraries, and integration with cloud testing services.

3. TypeScript — Strong Typing and Code Quality

TypeScript improves code quality and maintainability:

Static Typing: Prevents runtime errors and improves code reliability.
Auto-Completion & IntelliSense: Enhances developer productivity with better editor support.
Scalability: Easier to manage large test automation projects.
Better Code Documentation: Type annotations make code more readable and maintainable.

Why This Stack?

✅ Scalable & Maintainable: TypeScript + WebdriverIO ensures cleaner, structured test automation code.
✅ Faster Execution: Appium 2.0 + WebdriverIO improves performance and efficiency.
✅ Cross-Platform Support: Test on Android & iOS with the same framework.
✅ Cloud Integration: Works seamlessly with BrowserStack, Sauce Labs, and other testing clouds.

Having said that I found many challenges to set it up myself. Hence decided to put up a series of tutorials as there were lots of new things I tried out, failed and improved. And, will try to document everything as I hope it will help you in many ways.

Now, let’s get to our business.. begin with the prerequisites.

How to initiate my own project?

Starting a mobile automation project using Appium 2.0 involves several key steps, from setting up your environment to writing and running your first test. Below is a step-by-step guide:

Ensure you have the following installed on your system:

Node.js (LTS recommended)
Appium
WebDriverIO
Android Studio (for Android)
XCode (for iOS)
Android SDK & Emulator / Physical Android device

1. Install Prerequisites

Install Java (JDK)

Download and install the latest Java JDK (17 or later)

#Set up JAVA_HOME environment variable
java -version

Install Node.js and NPM

Appium 2.0 requires Node.js (v14+), download and verify installation

node -v
npm -v

Install Appium 2.0 and Drivers

Install Appium globally using npm & verify installation

npm install -g appium@latest
appium -v

Install Appium Drivers : Appium 2.0 does not come with pre-installed drivers. You need to install them manually

#For Android: Install uiautomator2 driver
appium driver install uiautomator2

#For iOS: Install xcuitest driver
appium driver install xcuitest

#List installed drivers:
appium driver list

#Install the Appium Doctor to check your environment:
npm install -g @appium/doctor

#Run the doctor to ensure everything is set up correctly:
appium-doctor

2. Set Up Mobile Device & Platform Dependencies

Android Setup

Install Android Studio & set up Android SDK, ADB, and AVD Manager.

#Check connected devices
adb devices

#Android envrionment variables
export ANDROID_HOME=/path/to/android/sdk
export PATH=$PATH:$ANDROID_HOME/platform-tools

Ensure you have enabled, Developer Options → USB Debugging on your Android device.

iOS Setup (For macOS & iOS Testing)

Install Xcode from the Mac App Store.
Install Xcode Command Line Tools and other dependencies

#Install Xcode Command Line Tools:
xcode-select --install

#Install Carthage, ios-deploy, and WebDriverAgent dependencies:
brew install carthage ios-deploy

#Enable Developer Mode on macOS:
sudo DevToolsSecurity --enable
sudo systemsetup -setremotelogin on

#Check connected iOS devices:
idevice_id -l

Refer to the “prerequisites for iOS setup” section for more configuration instructions.

3. Start Appium Server

Run Appium server with default settings:

#Run Server
appium server

#Run Server with relaxed security (to disable additional secure layer)
appium --relaxed-security

4. Initiate Project

Step 1: Create a new project

mkdir appium-wdio-ts && cd appium-wdio-ts
npm init -y

Step 2: Install dependencies

npm install --save-dev webdriverio appium typescript ts-node @wdio/cli @wdio/appium-service @wdio/mocha-framework

Step 3: Initialize TypeScript

npx tsc --init

Modify tsconfig.json to set:

{
  "compilerOptions": {
    "target": "ES6",
    "module": "CommonJS",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "outDir": "dist"
  },
  "include": ["tests", "pages"]
}

Step 4: Initialize WebDriverIO

#Initialise WDIO wizard
npx wdio config

#Use these configurations for basic test
Test Runner: Mocha
Services: appium
Framework: Mocha
Reporters: spec
Base URL: Leave empty
Specs Location: ./src/specs/**/*.ts

NOTE: This wizard will allow you to setup your whole project according to your choice, including installation of Appium, drivers, plugins etc..

Sample configuration:

5. Create WebDriverIO Configuration

Modify wdio.conf.ts in the project root:

export const config: WebdriverIO.Config = {
    runner: "local",
    specs: ["./src/specs/**/*.ts"],
    maxInstances: 1,
    capabilities: [
        {
            platformName: "Android",
            "appium:deviceName": "emulator-5554",
            "appium:platformVersion": "14.0",
            "appium:automationName": "UiAutomator2",
            "appium:app": "/path/to/your/app.apk",
            "appium:autoWebview": true,  // Enables webview automation
            "appium:chromedriverAutodownload": true,  // Automatically downloads matching Chromedriver
            "appium:chromedriverExecutable": "src/drivers/chromedriver" //path to the chromedriver binary
        }
    ],
    logLevel: "info",
    waitforTimeout: 10000,
    framework: "mocha",
    reporters: ["spec"],
    services: ["appium"],
    mochaOpts: {
        timeout: 60000,
    },
};

Create a Sample Test

Create a test file src/specs/sampleTest.ts:

import { expect } from '@wdio/globals'
import LoginPage from '../pageobjects/login.page'
import SecurePage from '../pageobjects/secure.page'

describe('My Login application', () => {
    it('should login with valid credentials', async () => {
        await LoginPage.open()

        await LoginPage.login('tomsmith', 'SuperSecretPassword!')
        await expect(SecurePage.flashAlert).toBeExisting()
        await expect(SecurePage.flashAlert).toHaveText(
            expect.stringContaining('You logged into a secure area!'))
    })
})

Run the Test

To run webdriver tests, start appium server and run the tests

#Start Appium Server:
appium --relaxed-security

#Run the WebDriverIO test:
npx wdio run wdio.conf.ts

#More info: https://appium.io/docs/en/2.0/guides/security/

How to improve your project aligning to framework structure

Here’s how you can structure your Appium 2.0 + TypeScript + WebDriverIO project using the Page Object Model (POM) with Fluent Design Principles:

Project Structure:

appium-wdio-ts/
│── src/
│   ├── app/
│   │   ├── app.apk            # Add apk file
│   ├── config/
│   │   ├── capabilities.ts    # Capabilities
│   │   ├── wdio.conf.ts       # WebDriverIO config
|── tests/
│   ├── specs/                 # Test scripts
│   │   ├── login.spec.ts
│   ├── pages/                 # Page objects
│   │   ├── BasePage.ts
│   │   ├── LoginPage.ts
│   ├── fixtures/             # Test data
│   │   ├── Testdata.json
├── .env                      # Environment variables
├── package.json
├── tsconfig.json

Test APK free download : https://software-testing.en.softonic.com/android

Additional Configurations for iOS setup

Check XCode and WebDriverAgent (WDA) Setup for iOS

#Install xcode
xcode-select --install

#Confirm the correct path, should see something like `/Applications/Xcode.app/Contents/Developer`
xcode-select -p

Manually build WebDriverAgent: Since WDA is part of ‘appium-xcuitest-driver’, try reinstall driver.

#Reinstall driver
 appium driver install xcuitest

This should install WebDriverAgent in the correct location. After installation, check if WebDriverAgent is available:

find / -name "WebDriverAgent.xcodeproj" 2>/dev/null

#If found, note the path.
#Else, manually clone and set up WebDriverAgent.

Now, go to your working directory &clone WebDriverAgent:

cd ~
git clone https://github.com/appium/WebDriverAgent.git

#Go into the WebDriverAgent folder:
cd WebDriverAgent

#Open WebDriverAgent in Xcode:
open WebDriverAgent.xcodeproj

Configure WebDriverAgent in Xcode

#Open WebDriverAgent in Xcode:
open WebDriverAgent.xcodeproj

Now that WebDriverAgent is open in Xcode:

Select “WebDriverAgent” in the left panel.
Go to “Signing & Capabilities” > Select your Apple ID under Team.
If you don’t have an Apple ID added, go to Xcode > Settings > Accounts and add it.
Choose your iOS simulator (e.g., iPhone 15, iOS 17.2)
Build the project:
— Click Product > Build.
— If the build succeeds, click Product > Test.

Finally, link WebDriverAgent to Appium

#Find WebDriverAgent's directory - it should return something like '/Users/your-username/WebDriverAgent'
pwd

#Run Appium with this WebDriverAgent path
appium --webdriveragent-root /Users/your-username/WebDriverAgent --relaxed-security

Let’s look at the additional improvements you can make on your project..

To develop a good test automation framework, it requires many features including;

Running tests in different environment configurations
Test Reporting
Multiple devices and Parallel execution

and many more..

But without further lengthening this guide, I’ll publish my next article with supporting steps.

Until then,

Thank you and Happy Automating!! 🚀

References:

Sample Project

https://appium.io/docs/en/2.0/

https://webdriver.io/docs/api/mobile

https://www.typescriptlang.org/docs/