Web & Mobile (iOS) Automation Demo Project: Selenium & Appium

This multi-module Java framework for test automation has been built with Maven and utilizes Selenium and Appium for browser and mobile automation, providing fast and reliable execution of web & mobile tests with detailed reporting and integration capabilities.

Tech Stack:

• Programming Language: Java
• Build Tool: Maven
• UI Automation Frameworks: Selenium, Appium
• Testing Framework: TestNG
• Reporting: Allure Report
• IDE for iOS development: Xcode

Requirements:

Requires Java 17, Maven 3.9.x, Allure Report 2.33.x, and Xcode 16.x to be installed and properly configured on your local machine.

Supported Platform:

• (Mac) OS X

Table of Contents

1. Getting Started
   • 1.1. Installation prerequisites
   • 1.2. Build WebDriverAgent (WDA) in Xcode
   • 1.3. Build Test Application
2. Framework Structure
   • 2.1. Configuring project
   • 2.2. Design pattern architecture
3. Tests Execution
   • 3.1. Web:
   • 3.2. Mobile:
4. Generate and Review Allure Report

1. Getting Started

1.1. Installation prerequisites:

1. Xcode (>= v.16.4)
   
   • Update Components (Xcode -> Settings -> Components) to the latest versions.
     

2. Appium2 with appium-xcuitest-driver
   
3. Appium-Doctor (a tool for checking Appium installation). It checks if Node.js, JDK, Android SDK, and Xcode are installed.
   

Install Homebrew, then NodeJS, and verify versions:

brew install node
node -v
npm -v

Install Appium and verify the version:

npm install -g appium
appium -v

Basic commands for working with Appium Drivers:

appium driver list
appium driver install <driver name>
appium driver update <driver name>
appium driver uninstall <driver name>

• Parameter:
  <driver name> - XCUITest driver

Basic commands for working with Appium Plugins:

appium plugin list
appium plugin install <plugin name>
appium plugin update <plugin name>
appium plugin uninstall <plugin name>

Starting the Appium server with default settings (after installing Appium-Doctor):

appium

Check the installation of Appium and dependencies:

npm install -g appium-doctor

Run to check for iOS (after installing Carthage):

appium-doctor --ios

1.2. Build WebDriverAgent (WDA) in Xcode:

Building WebDriverAgent (WDA) in Xcode is crucial for using Appium to automate iOS applications. WDA is a server that allows Appium to interact with iOS devices and simulators. Here’s a step-by-step guide on how to build and configure WebDriverAgent in Xcode:

1. Locate the WebDriverAgent Directory:

Path typically:

/usr/local/lib/node_modules/appium/node_modules/appium-xcuitest-driver/WebDriverAgent

Or:

~/.npm-global/lib/node_modules/appium/node_modules/appium-xcuitest-driver/WebDriverAgent

2. Open WebDriverAgent in Xcode:

• Open Xcode
  
• Select File -> Open
  
• Navigate to the WebDriverAgent folder you found in the previous step
  
• Open WebDriverAgent.xcodeproj
  

3. Select Scheme: At top left, choose WebDriverAgentRunner scheme

4. Configure Signing:

Ensure the project is set to use automatic signing:

• Click on the WebDriverAgentRunner in the project navigator
  
• Select the target (on the right side in the project settings)
  
• Under the Signing & Capabilities tab:
  
  • Select your development team from the Team drop-down
    
  • Make sure the Automatically manage signing option is enabled
    

5. Connect Device:

• Connect your physical iOS device via USB or choose a simulator
  
• In the top left corner, select your device or simulator from the device drop-down list
  

6. Build the Project:

• With the correct scheme selected and device input, click on Product in the Xcode menu
  
• Select Build or press Command + B
  
• Monitor the Issue Navigator (the triangle icon) for any errors
  

7. Fix Errors (if any): Resolve signing issues, dependencies, or iOS compatibility

8. Run WebDriverAgent Server:

• Open a new terminal window
  
• Run the following commands to start the Appium server:
  

   appium --log-level debug

• WebDriverAgent will launch automatically
  

9. Verify WebDriverAgent Status:

   http://<device-ip>:8100/status

Replace <device-ip> with the IP address of your iOS device while ensuring that the device’s WDA server is running.

Result:

1.3. Build Test Application:

1. Clone (or use option 'Open with Xcode') the project (iOS app for testing) from this GitHub repository. This is a simple 'Hello World!' application for iOS devices using Swift 6.1.2, created for testing purposes with Appium.
2. Select a iOS simulator (e.g., iPad (A16)) in Xcode and build application. After a successful build, the .app file will appear in DerivedData:
   

   ~/Library/Developer/Xcode/DerivedData/YourProject-XXXXXX/Build/Products/Debug-iphonesimulator/TestApp.app

Result:

2. Framework Structure

This template provides a UI test automation solution suitable for both web and mobile (iOS). It is structured as a Maven multi-module project, with the following relationships between the modules:

|———core-frmk
    |—-pom.xml
    |—-config
        |—-.env
    |—-module-app
        |—-pom.xml
        |—-src
            |—-main
                |—-java
    |—-module-tests
        |—-pom.xml
        |—-src
            |—-test
                |—-java
                    |—-resources
                        |—-testng.xml
                        |—-allure.properties
    |—-module-tools
        |—-pom.xml
        |—-src
            |—-main
               |—-java

1. Root Module (core-frmk). The parent project that defines shared dependencies, plugin configurations, and manages overall builds. Contains the config directory, where environment variables (.env files of various extensions) are stored for easy configuration management.
   
2. Modules:
   • module-app. The main module containing page object classes, UI components, and core application logic. It depends on module-tools for shared utilities and design pattern implementations.
     
   • module-tools. A utility module providing shared helpers, including support for browser configuration and Selenium integration, scalable Page Object pattern implementations, report generation, logging, and other common functions used across modules.
     
   • module-tests. This module contains test classes and test configurations (testng.xml). It depends on module-app to access page objects and perform web UI testing in a controlled environment.
     

2.1. Configuring project:

Run this command from the start to ensure that you don't have anything corrupted.

cd core-frmk
mvn clean install -U -DskipTests=true

2.2. Design pattern architecture:

3. Tests Execution

Maven is used as the build and test management tool, with additional options for test configuration:
-Denv={String} specifies the environment for test execution (default: test)
-Dbrowser={String} - defines the browser to run web tests on (default: chrome)
-DiOS={int} - defines the iOS version to run mobile tests on (default: the version set in Xcode)
-Ddevice={String} - defines the name of device for run mobile tests on (default: the name set in Xcode)
-Dthreads={int} - specifies the number of threads for parallel test execution
-Dtest={String} - the specific test class to run

Common Maven Commands:

1. Removes the target directory before running tests. Ensures that previous results do not affect the Allure report.

mvn clean

2. Runs tests defined in your testng.xml, using default system property settings (e.g., env, browser). By default, it executes with Chrome.
   

mvn test

For example:

cd core-frmk
mvn clean test

3.1. Web:

Create a hidden .env file containing the BASE_URL parameter to configure the web URL for testing. This will allow you to easily manage the base URL used during your web tests.

BASE_URL = https://demoqa.com

Supported Browsers:

• Google Chrome
• Mozilla Firefox
• Safari [Mac OS X]

Usage web examples:

To execute a specific test with default settings the next command line should be used:

mvn clean test -Dtest=HomeWebTest

To execute a test with custom options the next command line should be used:

mvn clean test -Dtest=HomeWebTest -Dbrowser=firefox -Denv=dev

To execute tests in parallel with testng.xml the next command line should be used:

mvn clean test -DsuiteFile=src/test/resources/suites/web.xml -Dthreads=3

3.2. Mobile:

Create a hidden .env file containing the parameters APPIUM_URL, APP_NAME, and APP_BUNDLE_ID to configure the testing environment for mobile tests.
Place your builded iOS application (e.g., TestApp.app) from DerivedData folder into the local app directory.
The APP_BUNDLE_ID is a unique bundle identifier for a mobile application on the iOS or Android platform. This identifier is used to differentiate apps in systems and services such as the App Store or Google Play.

APPIUM_UR = http://0.0.0.0:4723/
APP_NAME = "TestApp.app"
APP_BUNDLE_ID = com.kmartita

To execute the mobile test itself the next command line should be used:

cd core-frmk
mvn clean test -Denv=dev -Dtest=HomeMobileTest -DiOS=18.6 -Ddevice="iPad Pro 13-inch (M4)"

Supported iOS Simulators (by default):

• iPad (A16) - iOS 18.6

List of available devices:

4. Generate and Review Allure Report

To generate a report by Allure after tests have finished, use the following command:

mvn allure:report

The report can be found in the root folder of a project. The folder named allure-report contains the generated report. Just open the index.html file in a browser.

Alternatively, Allure provides a command to serve the report directly:

mvn allure:serve 

This command starts a local web server and automatically opens the generated report in your default browser.

An example of the generated Allure TestNG report looks like this:

Suites (Web & Mobile):

mvn clean test -Denv=dev

Browser: Chrome
iOS-version: 18.6
Deevice: iPad (A16)

Result:

Mobile:

mvn clean test -DiOS=18.6 -Ddevice="iPad Air 11-inch (M3)" -Denv=dev -DsuiteFile=src/test/resources/suites/mobile.xml

Result:

Web:

mvn clean test -Dbrowser=firefox -DsuiteFile=src/test/resources/suites/web.xml

Env: test

Result:

---

Copyright (c) 2025 Marta Kravchuk under MIT License.