Maestro explicit wait example

// flows/login-flow.ts
import { maestro, element, text } from '@maestro-project/maestro';

export const loginFlow = async () => {
  // Launch app and wait for stability
  await maestro.launchApp({ stopApp: true });
  
  // Wait for login screen with explicit timeout
  const loginButton = element({ text: 'Login' });
  await loginButton.waitForExist(5000);

  // Input credentials using secure variable injection
  await element({ text: 'Email' }).inputText(process.env.TEST_USER_EMAIL);
  await element({ text: 'Password' }).inputText(process.env.TEST_USER_PASSWORD);

  // Tap login and wait for navigation
  await element({ text: 'Sign In' }).tap();
  
  // Assert home screen presence
  const homeTitle = element({ text: 'Welcome' });
  await homeTitle.waitForExist(10000);
  
  console.log('Login flow successful');
};

// test/e2e/appium.driver.ts
impo

rt { remote, RemoteOptions } from 'webdriverio';

const caps: RemoteOptions = { path: '/wd/hub', port: 4723, capabilities: { platformName: 'Android', 'appium:deviceName': 'Pixel_6_API_33', 'appium:automationName': 'UiAutomator2', 'appium:app': './build/app-debug.apk', 'appium:noReset': false, 'appium:ensureWebviewsHavePages': true, } };

export async function setupDriver() { const driver = await remote(caps);

// Page Object Model integration const loginPage = { get emailInput: () => driver.$('~email-input'), get passwordInput: () => driver.$('~password-input'), get loginButton: () => driver.$('~login-button'),

async login(email: string, password: string) {
  await this.emailInput.setValue(email);
  await this.passwordInput.setValue(password);
  await this.loginButton.click();
  // Wait for next screen
  await driver.$('~dashboard').waitForDisplayed({ timeout: 10000 });
}

};

return { driver, loginPage }; }

### 3. CI/CD Integration Strategy

Tests must run in parallel across device classes. A production pipeline should trigger:
1.  **Push Events:** Linting, Unit Tests, Integration Tests, E2E on Local Emulator.
2.  **Merge Requests:** E2E on Cloud Real Devices (Top 5 devices).
3.  **Release Tags:** Full Matrix Regression on Cloud Real Devices.

### 4. Network and Performance Testing

Mobile apps must handle erratic networks. Integrate network throttling into E2E suites:
*   **Throttling Profiles:** Simulate 3G, High Latency, and Packet Loss.
*   **Performance Baselines:** Measure Cold Start Time, FPS, and Memory Leaks.
*   **Implementation:** Use `adb shell` commands for network simulation in Android or Instruments for iOS profiling within the test runner.

## Pitfall Guide

### 1. Testing on Emulators/Simulators Only
**Mistake:** Assuming emulator behavior mirrors physical devices.
**Reality:** Emulators lack GPU constraints, thermal throttling, and OEM-specific behaviors. They cannot replicate camera interactions, biometric sensors, or background app switching on low-memory devices.
**Best Practice:** Mandate a "Real Device Gate" in CI. At minimum, run smoke tests on a device cloud for every build.

### 2. Flaky Tests Due to Timing Assumptions
**Mistake:** Using hardcoded sleeps (`sleep(2000)`) to wait for UI elements.
**Reality:** Device performance varies. A sleep that works on an iPhone 15 may fail on an iPhone 11.
**Best Practice:** Use explicit waits based on element presence or state changes. Implement retry logic for transient network failures within tests.

```yaml
# Maestro explicit wait example
- tapOn: "Submit"
- waitForAnimationToEnd:
    timeout: 5000
- assertVisible: "Success Message"

3. Ignoring Permission and Auth Flows

Mistake: Tests assume permissions are granted or auth tokens are valid. Reality: Mobile OSs revoke permissions aggressively. Auth tokens expire. Tests fail when permissions are reset or tokens expire during long runs. Best Practice: Reset app state before every test run. Mock permission dialogs where possible. Implement token refresh logic in test setup.

4. Hardcoding Selectors

Mistake: Selecting elements by text or coordinates. Reality: Text changes for localization break tests. Coordinates break on different screen sizes. Best Practice: Enforce accessibilityLabel or testID attributes in the app codebase. Selectors must reference these stable identifiers.

5. Neglecting Data Isolation

Mistake: Tests rely on shared state or pre-existing data. Reality: Parallel test execution causes race conditions. Tests fail when data is modified by concurrent runs. Best Practice: Use unique test data per run (e.g., user_test_12345). Clean up data after tests. Use ephemeral test accounts.

6. Skipping Performance Regression Checks

Mistake: Treating performance as a manual QA activity. Reality: Performance degrades incrementally. Without automated checks, regressions go unnoticed until user complaints spike. Best Practice: Instrument critical paths to measure FPS and memory. Fail the build if metrics deviate by >5% from the baseline.

7. Inadequate Network Condition Testing

Mistake: Testing only on stable Wi-Fi. Reality: Users operate in subways, elevators, and rural areas. Apps must handle disconnects and slow responses gracefully. Best Practice: Integrate network simulation tools (e.g., Charles Proxy, network-link-conditioner) into the test suite to verify error handling and retry mechanisms.

Production Bundle

Action Checklist

• Define Device Matrix: Select top 10 devices covering 80% of user base based on analytics data.
• Implement Unit Test Gate: Require >70% code coverage for new features; block merges on regression.
• Deploy Hybrid E2E Suite: Configure local fast tests for PRs and cloud real-device tests for nightly runs.
• Enforce Selectors: Audit codebase to ensure all interactive elements have testID/accessibilityLabel.
• Integrate Network Throttling: Add test cases for 3G, offline, and high-latency scenarios.
• Setup Performance Baselines: Configure CI to track Cold Start Time and FPS; set alert thresholds.
• Configure Crash Analytics Loop: Link test failures to crash reporting tools (Sentry/Firebase) for rapid triage.
• Schedule Fragmentation Regression: Run full device matrix tests weekly to catch OEM-specific drift.

Decision Matrix

Scenario	Recommended Approach	Why	Cost Impact
Startup MVP	Local Emulators + Manual Real Device Checks	Speed to market is priority; budget constrained.	Low
Enterprise App	Hybrid Cloud Automation (Maestro/Appium)	High reliability required; diverse user base; compliance needs.	Medium
Game/Heavy Graphics	Device Farm + Profiling Tools	GPU and thermal performance are critical; emulators insufficient.	High
Cross-Platform (Flutter/RN)	Shared E2E Suite + Native Unit Tests	Maximize code reuse; validate platform-specific bridges.	Medium
Regulated Industry	Full Matrix + Audit Trails	Compliance requires evidence of testing across configurations.	High

Configuration Template

GitHub Actions Workflow for Hybrid Mobile Testing

name: Mobile CI/CD Pipeline

on:
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]

jobs:
  unit-tests:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Setup JDK
        uses: actions/setup-java@v3
        with:
          java-version: '17'
          distribution: 'temurin'
      - name: Run Unit Tests
        run: ./gradlew testDebugUnitTest

  e2e-local:
    runs-on: macos-latest
    needs: unit-tests
    steps:
      - uses: actions/checkout@v4
      - name: Install Maestro
        run: curl -Ls "https://get.maestro.mobile.dev" | bash
      - name: Run Local E2E
        run: |
          # Run on local simulator/emulator
          maestro test flows/ --format xml

  e2e-cloud:
    runs-on: ubuntu-latest
    needs: e2e-local
    if: github.event_name == 'push'
    steps:
      - uses: actions/checkout@v4
      - name: Build APK
        run: ./gradlew assembleDebug
      - name: Run on Real Devices (Device Farm)
        uses: mobile-dev-inc/action-maestro-cloud@v1
        with:
          api-key: ${{ secrets.MAESTRO_CLOUD_API_KEY }}
          app-file: app/build/outputs/apk/debug/app-debug.apk
          flow-files: flows/
          include-tags: "smoke,critical"

Quick Start Guide

1. Install Maestro:

   curl -Ls "https://get.maestro.mobile.dev" | bash
   

2. Initialize Project:

   maestro init
   

   This creates a flows directory and a maestro.yaml config.
3. Write First Test: Create flows/01-login.yaml:

   appId: com.example.app
   ---
   - launchApp
   - tapOn: "Email"
   - inputText: "test@example.com"
   - tapOn: "Password"
   - inputText: "securepassword"
   - tapOn: "Login"
   - assertVisible: "Dashboard"
   

4. Run Locally: Ensure an emulator/simulator is running or a device is connected via USB.

   maestro test flows/01-login.yaml
   

5. Integrate to CI: Add the GitHub Actions template to .github/workflows/mobile-test.yml. Commit and push to trigger the first automated run.

Mobile app testing is a continuous engineering discipline. By adopting a hybrid strategy, enforcing strict selector hygiene, and integrating performance and network validation into the pipeline, teams can eliminate fragmentation-related defects and deliver stable, high-quality experiences across the entire device matrix.