Maestro explicit wait example

hat integrates unit, integration, and end-to-end (E2E) testing into a continuous delivery pipeline.

1. Architecture: The Mobile Test Pyramid Adaptation

The traditional test pyramid must be adapted for mobile. E2E tests are inherently slower and more brittle due to UI rendering times and OS interactions. The architecture should prioritize:

• Unit Tests (70%): Isolated logic testing using native frameworks (XCTest, JUnit) or shared logic testing (Dart, Kotlin Multiplatform).
• Integration Tests (20%): API mocking, database interactions, and component communication. Tools like MockK or Mockito.
• E2E Tests (10%): Critical user journeys validated on real devices. Tools like Maestro, Appium, or Detox.

2. Tooling Selection and Implementation

E2E Framework: Maestro Maestro has emerged as the standard for modern mobile E2E testing due to its speed, low flakiness, and YAML/TypeScript hybrid interface. It uses an accessibility-based element identification strategy, making tests resilient to UI changes.

TypeScript Implementation Example: For complex flows requiring programmatic logic, Maestro supports TypeScript flows.

// 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');
};

Appium for Cross-Platform Automation: When deep driver control or cross-platform code sharing is required, Appium remains the industry standard.

// test/e2e/appium.driver.ts
import { 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.

# 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.