Featured project 4 · Java · Android

Appium Android Framework

Android test automation with Appium 3, Java 17 and TestNG for the Sauce Labs My Demo App: 40 tests on an Android 15 emulator, locally and in GitHub Actions, with three real app bugs found.

View source code View documentation View latest CI runs View test report

Purpose

Shows mobile test automation end to end: setup on Windows without Android Studio, screen objects, device behaviour, evidence for every failure, and an Android emulator in CI.

Technology stack

Area	Tools
Mobile automation	Appium 3.8 server, UiAutomator2 driver 8.7, Appium Java client 11
Test runner	TestNG 7.12 (groups, suites, retry analyzer)
Device	Android 15 emulator (API 35), or a real phone over USB
Reporting	Custom HTML report with steps, screenshots and screen recordings
CI	GitHub Actions with reactivecircus/android-emulator-runner

Architecture overview

Tests (TestNG) ──▶ Screen objects + Header component + Device actions
                        │
                   BaseScreen (wait, tap, type, scroll, log each step)
                        │
                   DriverManager (one session per thread; app data cleared before each test)
                        │
        Appium server ──▶ UiAutomator2 ──▶ emulator / phone

Design reasons, and the failures that shaped them, are in docs/framework-design.md.

Key engineering decisions

One Appium session per thread, reset per test with mobile: clearApp (about 2 s instead of 5–10 s for a new session)
Locators: resource ids first, accessibility ids next, UiAutomator text only where there is no id, never XPath
Swipe-based scrolling in both directions with end-of-list detection, because the app's list is not marked scrollable
Retry only when Android shows "app isn't responding"; assertion failures are never retried
Known app bugs kept as tests that assert the correct behaviour, outside the main suite

Implemented features

Login, sorting, cart and a full checkout with the order total checked as cart total + delivery (BigDecimal)
Device tests: back button, background and resume, cold start, rotation lock, keyboard
17 interview scenario tests: locator strategies, W3C gestures, permission dialogs, mocked GPS, files, logcat, WebView context
Every failure keeps a screenshot and a screen recording in the report

Setup and execution

scripts/get-app.sh                           # downloads the pinned APK
emulator -avd Pixel_API_35 -no-snapshot-save
appium --use-plugins=inspector --allow-cors
mvn test                                     # 40 tests, about 16 min locally
mvn test -DsuiteXmlFile=known-bugs.xml       # the 3 known app bugs

Full setup guide: docs/setup.md.

Sample test results

Appium report: 40 of 40 passed — 40 of 40 passed on the Android 15 emulator.

Bugs found in the demo app (My Demo App 2.3.0)

Opening the 7th or a later catalog product crashes the app (ArrayIndexOutOfBoundsException, from logcat)
The product quantity can be lowered to 0
The missing-country message is cut off ("Please provide your")

Report of the crash test with steps, error, screenshot and recording — The crash in the report: steps, error, the home screen at failure and the recording.

CI workflow

On every push: Java 17, Node 24, Appium and the driver at the same versions as the setup guide, KVM, an API 35 Pixel 7 emulator with animations off, totals in the run summary and the report, failure videos and Appium log as an artifact. 40 of 40 pass in about 9.5 minutes.

Known limitations and future improvements

Limitations

Android only: iOS needs a Mac with Xcode
One device, so the suite runs on one thread (the design supports one device per thread)
WebView screens are checked for their context but not automated inside (needs a matching Chromedriver)

Next steps

Parallel runs on several emulators (one udid and systemPort per thread)
Real-device or device-cloud run
iOS screens with shared accessibility ids