Maestro UI Automation — BrowserStack App Automate

Run declarative Maestro UI flows for Android (Wikipedia) and iOS (Wikipedia) apps on real devices using BrowserStack App Automate.

---

Repository structure

maestro-ui-automation/
├── android/                          # Android platform
│   ├── tests/                        # Maestro flows
│   │   ├── wiki-generalFlow-aiVerify.yaml   # Home screen AI verification
│   │   ├── wiki-scroll-aiAssert.yaml        # Scroll feed + AI defect audit
│   │   ├── wiki-swipe.yaml                  # Swipe + AI defect audit
│   │   ├── wiki-aiExtract.yaml              # AI text extraction (Einstein article)
│   │   ├── wiki-conditional-nestedFlows.yaml # Conditional scroll to Top read
│   │   ├── common/functions/
│   │   │   ├── scroll.yaml                  # Reusable scroll sub-flow
│   │   │   └── swipe.yaml                   # Reusable swipe sub-flow
│   │   └── subflows/
│   │       └── skipOnboarding.yaml          # Skip onboarding / dismiss dialogs
│   ├── browserstack.yml              # Capabilities, devices, shards & run profile
│   ├── run-android.sh                # macOS / Linux runner
│   ├── run-android.ps1               # Windows PowerShell runner
│   ├── run-android.bat               # Windows CMD runner
│   └── README.md
├── ios/                              # iOS platform
│   ├── tests/                        # Maestro flows (identical flows to Android)
│   │   ├── wiki-generalFlow-aiVerify.yaml
│   │   ├── wiki-scroll-aiAssert.yaml
│   │   ├── wiki-swipe.yaml
│   │   ├── wiki-aiExtract.yaml
│   │   ├── wiki-conditional-nestedFlows.yaml
│   │   └── subflows/
│   │       └── skipOnboarding.yaml
│   ├── browserstack.yml
│   ├── run-ios.sh
│   ├── run-ios.ps1
│   ├── run-ios.bat
│   └── README.md
├── app/
│   ├── Wikipedia.ipa                 # iOS test app
│   └── WikipediaSample.apk           # Android test app
├── build_payload.py                  # Builds the BrowserStack API JSON payload
└── read_devices.py                   # Reads device list from browserstack.yml

---

Prerequisites

Tool	macOS	Windows
curl	Pre-installed	Pre-installed on Windows 10+
python3	Pre-installed on macOS 12+	python.org
zip / tar	Pre-installed	Pre-installed on Windows 10+

Credentials — find yours at app-automate.browserstack.com → Account → Settings.

---

Quick start

1 — Set credentials

macOS / Linux

export BROWSERSTACK_USERNAME="your-username"
export BROWSERSTACK_ACCESS_KEY="your-access-key"

Windows (PowerShell)

$env:BROWSERSTACK_USERNAME="your-username"
$env:BROWSERSTACK_ACCESS_KEY="your-access-key"

2 — Run Android

cd android
./run-android.sh --upload   # first run: upload app + suite, then trigger build
./run-android.sh            # subsequent runs: trigger build only

3 — Run iOS

cd ios
./run-ios.sh --upload       # first run: upload app + suite, then trigger build
./run-ios.sh                # subsequent runs: trigger build only

---

AI commands used

Command	Purpose
assertWithAI	Validate complex UI states with natural language
assertNoDefectsWithAI	Visual/functional audit for UI bugs and broken layouts
extractTextWithAI	Extract dynamic content (e.g. article text, prices)

Requires maestroVersion: latest in browserstack.yml. Omitting or pinning an older version causes TESTSUITE_PARSE_ERROR.

---

View results

Visit app-automate.browserstack.com to see build results, session videos, device logs, and network logs.