Appium 2 Project

The Appium 2 Project is a Java-based test automation framework built with Appium 2, supporting the testing of native and web mobile applications in both local and cloud-based (BrowserStack) environments.

---

Table of Contents

• About the Project
• Key Features and Technical Solutions
• Tech Stack
• Tested Applications
• Setup and Prerequisites
  • Prerequisites for Execution
• Usage and Running Tests
  • Configuration
  • Execution Strategies and TestNG configuration
  • Running the Tests
• Screenshots and Videos of the Tests

About the Project

This project was created for learning purposes, allowing me as a junior software tester to practice and deepen my knowledge in the field of test automation, particularly in testing mobile and web-based systems. I aimed to create a test framework that, in its structure and operation, resembles solutions used in professional work environments.

The framework was built entirely from scratch. The core technologies are Java, Appium 2, Selenium, TestNG, and Log4j. The system can automatically manage the Appium server, generate logs and reports (Extent Reports, as well as HTML-formatted email reports), and take screenshots in case of failure. It is also capable of uploading these artifacts to Netlify and sending them via email using the SendGrid API. Although these functions are often handled centrally in a real CI/CD environment, my goal was to understand their operation by implementing them manually, thereby learning new Java libraries and techniques.

The tests operate in a data-driven manner, with input data sourced from JSON files. During the design phase, key considerations were modularity, reusability, and easy maintainability. Code quality was also enhanced using tools like PMD and SpotBugs.

Of course, there are still countless opportunities for development and refinement. My next goals include implementing parallel test execution and CI/CD integration, for example, using Jenkins.

Testing was performed on a real Android device (Xiaomi Redmi Note 8T - Android 11) and in the BrowserStack cloud service, which I demonstrate in the videos below.

Key features and technical solutions

The project follows modern software development and test automation best practices:

• Page Object Model (POM): UI elements and their corresponding actions are separated from the test logic, resulting in clean and maintainable code.
• Data-Driven Configuration: Driver capabilities, environment settings, and test data are stored in external JSON and .properties files. This allows for modifying the test environment without changing the Java code.
• Factory and Builder Design Patterns:
  • DriverFactory: A central "factory" for creating various AndroidDriver instances (native/web, local/cloud).
  • OptionsBuilder classes: Responsible for the dynamic and readable assembly of complex Appium capabilities objects.
• POJO and Enum Classes for Structured Data Representation:
  • The system uses POJO classes (e.g., AppiumOptionsData) to read JSON configurations and test data with the help of Jackson. This provides type safety and better readability compared to raw Map objects.
  • Enums are used for the safe handling of fixed, predefined values (e.g., execution environments), preventing errors from typos.
• Layered Logic with Steps, Assertions, and Providers:
  • Tests are broken down into well-defined layers. Page Object classes contain reusable, business-level steps (e.g., login()), while test methods are responsible for calling these steps and performing assertions.
  • Data-driven testing is supported through DataProvider classes.
• Environment-Dependent Execution: A single configuration switch allows for toggling between local (on a real device or emulator) and cloud-based (BrowserStack) execution.
• Programmatic Server Management: The AppiumServerManager can automatically start/stop the Appium server, eliminating the need for manual intervention.
• Detailed Reporting: The system offers two parallel reporting mechanisms:
  • ExtentReports: Generates interactive, visual HTML reports with screenshots on failure.
  • Custom Email Reporting: Uses the SendGrid API to send HTML-formatted notifications, providing a reporting mechanism independent of any CI/CD system.
• Timestamped Logging to File (logback): The Log4j logging system creates a separate, timestamped log file for each test run and server start, preventing log overwrites and simplifying debugging. The logging level and target location are configurable in the log4j.properties file for test runs and in config.properties for the Appium server.
• Exception Handling with Custom Exception Hierarchy: The framework introduces dedicated custom exception classes (e.g., ConfigurationException, JsonReadException, LogFileException) all extending a base AppiumProjectException. This promotes clearer, contextualized error reporting and better maintainability.
• Refactoring Based on the DRY (Don't Repeat Yourself) Principle: The entire project is built following the DRY principle. Frequently repeated operations—such as driver management, configuration reading, or common UI interactions—are centralized in reusable components. This significantly reduces code duplication and increases long-term maintainability.

Tech Stack

The project uses the latest or near-latest versions of the following main technologies and libraries:

• Java 22.0
• Maven 3.9.9
• Appium 2.19.0
• Appium Java Client 9.2.2
• Selenium 4.22.0
• TestNG 7.10.2
• Log4j 2.24.0
• Jackson 2.19
• Extent reports 5.1.2
• Sendgrid 4.10.3 (for email sending)
• Netlify-CLI 18.0.4 (for uploading files to a server)

Tested Applications

• SauceLabs Swag Labs (native) app (MyDemoAppRN.1.3.0.build-244) <br>
• Battery Alarm (native) app (v76) (Battery Alarm webpage) <br>
• CURA Healthcare Service (web) app (Katalon demo webpage)
• Chrome version: 137.0.7151.89

Setup and Prerequisites

Prerequisites for Execution

• Java Development Kit (JDK) 22 or newer
• Apache Maven – for building the project and running tests
• Node.js and npm – for installing and running Appium
• Appium 2 – installed globally (npm install -g appium@next)
• Android SDK – it is recommended to install it with Android Studio, which also provides the necessary tools and an AVD manager
• Registration and configuration of external services:
  • Sendgrid – for sending email-based test reports. Configuration file: src/main/resources/emailsendingdata/sendgrid_account.json
  • Netlify – for public access to files in test reports (e.g., screenshots), a simple Netlify account and deploy are required
  • BrowserStack – for test execution in a cloud-based device farm. Configuration files: src/test/resources/testdatafiles/options/browserstack/

Usage and Running Tests

Configuration

• Execution Environment and Browser: The following settings can be configured in the src/main/resources/config.properties file:
  • run.environment: The test execution environment. Possible values: local or cloud (BrowserStack).
  • browser.type: The browser used for web tests. Possible values: chrome or firefox.
• Driver Capabilities: Platform- and environment-specific Appium settings are located in separate JSON files under the following path: src/test/resources/testdatafiles/options/appium/.

Execution Strategies and TestNG Configuration

The framework uses TestNG to configure and run tests, leveraging its advanced control features.

• Test Suites: Predefined execution packages for various testing purposes (e.g., quick checks, full regression) are located in the src/test/resources/testng-configs/ folder. This allows running only relevant tests, optimizing time and resources.
  • smoke-tests.xml: Fast-running tests to check basic functionality.
  • regression-tests.xml: A test suite ensuring full functional coverage of the system.
• TestNG Groups: Tests can be logically separated using the @Test(groups = {"smoke"}) annotation.
• Data-Driven Testing (@DataProvider): The framework supports a data-driven testing approach. The DataProviderTests class for the CURA H.S. application provides an example of how to read test data (username, password) from an external JSON file (from the src/test/resources/testdatafiles/testinputs/ folder). The CuraLoginTestDataProvider class separates the data supply from the test logic, allowing the same test case to be executed with multiple input combinations.
• Priority and Dependencies: The @Test(priority = ...) annotation allows specifying the execution order of tests, which is particularly useful for testing complex, interdependent use