Cross-platform mobile test automation framework for Android (UIAutomator2) and iOS (XCUITest) using Appium and WebdriverIO v9. Includes Screen Object abstractions, hybrid native/WebView context switching, Allure reporting with automatic failure screenshots, ESLint (eslint-plugin-wdio) enforcement, Gherkin BDD specs, and BrowserStack cloud execution via GitHub Actions.
| Artifact | Purpose | Location |
|---|---|---|
| Test Plan | Cross-platform scope, architecture decisions, and CI gating | docs/qa/TEST_PLAN.md |
| Test Case Inventory | 14 mapped Android & iOS mobile scenarios | docs/qa/TEST_CASES.md |
| BDD Specifications | Gherkin scenarios for Android notes and iOS hybrid/native flows | specs/features/ |
| Bug Report Example | Analysis of hardcoded date fragility & config/selector fixes | BUG-001 |
.
├── .github/workflows/
│ └── ci.yaml # ESLint + ESM config check on push; BrowserStack on manual dispatch
├── app/
│ ├── android/ # ColorNote+Notepad.apk & ApiDemos-debug.apk
│ └── ios/ # UIKitCatalog.app & wdiodemoapp.app
├── config/
│ ├── wdio.shared.conf.js # Shared Mocha opts, Allure reporter & failure screenshot hook
│ ├── wdio.android.conf.js # Local Android UIAutomator2 configuration (ColorNote)
│ ├── wdio.ios.conf.js # Local iOS XCUITest configuration (WebView)
│ └── wdio.android.bs.conf.js # BrowserStack Android cloud configuration
├── docs/qa/
│ ├── bug-reports/
│ │ └── BUG-001-hardcoded-date-ios-todo-item.md
│ ├── TEST_CASES.md
│ └── TEST_PLAN.md
├── specs/features/
│ ├── android-notes.feature # BDD scenarios for ColorNote Android
│ └── ios-mobile.feature # BDD scenarios for iOS WebView, UIKitCatalog & Todo
├── test/
│ ├── screenobjects/
│ │ ├── android/ # AddNoteScreen & EditNoteScreen
│ │ ├── item.screen.js # iOS Todo Item Screen Object
│ │ └── list.screen.js # iOS Todo List Screen Object
│ └── specs/
│ ├── android/ # Android E2E specs
│ ├── ios/ # iOS WebView, Native & Todo specs
│ └── ios-findElements.spec.js # iOS locator strategies (Accessibility ID, Class Chain, Predicate)
├── .env_template # Environment variable template for BrowserStack
├── .nvmrc # Node.js 24.11.1
├── eslint.config.mjs # ESLint 9 flat config + eslint-plugin-wdio rules
└── package.json
- Multi-Environment Config Inheritance:
config/wdio.shared.conf.jscentralizes Mocha timeouts, Allure report generation (onComplete), and automatic failure screenshots (afterTest->driver.takeScreenshot()), extended cleanly by local Android, local iOS, and BrowserStack configs. - Screen Object Model: Platform-specific selectors (
resource-id,~accessibilityId,-ios class chain,-ios predicate string) are isolated from test steps undertest/screenobjects/. - Dynamic Hybrid WebView Handling:
test/specs/ios/webview.spec.jspollsdriver.getContexts()viadriver.waitUntil()instead of static sleeps before switching betweenNATIVE_APPandWEBVIEW. - Static WDIO Guardrails:
eslint.config.mjsenforceswdio/await-expect,wdio/no-debug, andwdio/no-pauseacross tests and configs.
- Node.js
>= 22.x(pinned in.nvmrc:24.11.1) - Local Appium drivers (when running against local emulators/simulators):
npm install -g appium appium driver install uiautomator2 appium driver install xcuitest
- Android Studio Emulator (
Pixel 4, API matchingwdio.android.conf.js) or macOS Xcode iOS Simulator (iPhone 12, iOS 17.2)
# 1. Install project dependencies
npm ci
# 2. Run ESLint checks (no device required)
npm run lint
# 3. Run local Android suite (requires running Android emulator)
npm run test:android
# 4. Run local iOS WebView suite (requires macOS + iOS Simulator)
npm run test:ios
# 5. Generate & open Allure report
npm run report- Copy
.env_templateto.env(never commit.env):BROWSERSTACK_USER=your_browserstack_username BROWSERSTACK_KEY=your_browserstack_access_key
- Run locally against BrowserStack:
npm run test:bs
- Or trigger the
BrowserStack Android E2Ejob manually via Actions -> Mobile E2E CI -> Run workflow after configuringBS_USERandBS_KEYin GitHub Repository Secrets.
Luis Fernando Brandão
QA Automation Engineer