Mobile Tester

This skill runs AFTER mobile-engineer (app is built) and alongside qa-engineer (complementary):

• Input: Built and installed app on device, test requirements from BRD/PRD
• Output: Test results, visual replay reports, device test summary

Relationship to Other Skills

Config

Read .production-grade.yaml for overrides:

• paths.mobile_tests — default: tests/e2e/mobile/
• mobile_testing.model — default: gemini-2.5-flash
• mobile_testing.platform — default: both (options: android, ios, both)

Packages

Output Structure

tests/e2e/mobile/
├── android/
│   ├── demo.test.ts                 # Demo test (auto-generated by setup)
│   ├── flows/
│   │   ├── auth.test.ts             # Login/register/logout flows
│   │   ├── onboarding.test.ts       # First-time user experience
│   │   ├── core-workflow.test.ts    # Main business flow
│   │   └── settings.test.ts        # Settings and preferences
│   └── smoke.test.ts               # Quick smoke test (critical path only)
├── ios/
│   ├── demo.test.ts                 # Demo test (auto-generated by setup)
│   ├── flows/
│   │   └── (same structure as android)
│   └── smoke.test.ts
├── shared/
│   ├── test-data.ts                 # Shared test data and credentials
│   ├── helpers.ts                   # Shared helper functions
│   └── assertions.ts               # Reusable AI assertion templates
├── reports/                         # Auto-generated visual replay reports
├── tsconfig.json
└── README.md                        # Auto-generated test documentation

Phases

Phase 1 — Environment Verification

Goal: Ensure everything is set up correctly before writing tests.

Actions:

1. Check if @midscene/android and/or @midscene/ios are installed
2. If not installed, run scripts/mobile-test-setup.sh automatically
3. Verify .env.midscene has a valid API key (not placeholder)
4. Detect connected devices:
   • Android: getConnectedDevices() from @midscene/android
   • iOS: Check for running simulator or connected device
5. Verify the target app is installed on the device

Output: Device connection status, app detection result

If setup fails: Guide user through /setup-mobile-test workflow step by step.

Phase 2 — Test Generation

Goal: Read app code/requirements and generate vision-based test scripts.

Actions:

1. Read BRD/PRD for user stories and acceptance criteria
2. Read app code structure to understand screens and navigation:
   • Android: android/app/src/main/ → Activities, Fragments
   • React Native: app/ → Screen components, navigation config
   • Flutter: lib/ → Widgets, routes
3. For each critical user flow, generate a test file using Midscene API:

import { AndroidAgent, AndroidDevice, getConnectedDevices } from '@midscene/android';

async function testLoginFlow() {
  const devices = await getConnectedDevices();
  const device = new AndroidDevice(devices[0].udid);
  const agent = new AndroidAgent(device, {
    aiActionContext: 'App under test: [AppName]. Dismiss popups automatically.',
  });
  await device.connect();

  // Launch the app
  await agent.aiAction('open [AppName] app');
  await agent.aiWaitFor('the login screen is displayed');

  // Test login flow
  await agent.aiAction('tap the email input field and type "[email protected]"');
  await agent.aiAction('tap the password field and type "Test123!"');
  await agent.aiAction('tap the "Sign In" button');

  // Assert success
  await agent.aiWaitFor('the home screen or dashboard is displayed', { timeoutMs: 15000 });
  await agent.aiAssert('a welcome message or user profile is visible');

  // Extract and verify data
  const screenData = await agent.aiQuery(
    '{ welcomeText: string, hasNavigationBar: boolean }',
    'get the welcome text and check if bottom navigation bar exists'
  );
  console.log('Screen data:', screenData);
}

4. Generate smoke test covering critical path only (login → main screen → key action → logout)
5. Generate flow tests for each major user story from BRD

Rules:

• Use aiAction() for interactions — always describe in plain English
• Use aiWaitFor() instead of sleep() — AI waits for visual condition
• Use aiAssert() for verifications — natural language assertions
• Use aiQuery() to extract structured data from screen
• Set appropriate timeouts for slow operations (network calls, animations)
• Include aiActionContext to help AI understand what app it's testing

Phase 3 — Test Execution

Goal: Run all test scripts on connected device(s) and collect results.

Actions:

1. Load environment variables from .env.midscene
2. Verify device is still connected and screen is unlocked
3. Run tests sequentially (each test controls the device):

   source .env.midscene
   npx tsx tests/e2e/mobile/android/smoke.test.ts
   npx tsx tests/e2e/mobile/android/flows/auth.test.ts
   npx tsx tests/e2e/mobile/android/flows/core-workflow.test.ts
   

4. Capture pass/fail status for each test
5. Screenshots are automatically captured by Midscene at each step

Rules:

• Run smoke test FIRST — if smoke fails, skip detailed tests
• Ensure device screen stays ON during testing (prevent auto-lock)
• If a test fails, capture the failure screenshot and continue with next test
• Collect all results for the report phase

Phase 4 — Reporting

Goal: Generate comprehensive test report with visual replays.

Actions:

1. Midscene automatically generates visual replay at ./midscene_run/report/
2. Create summary report at tests/e2e/mobile/reports/:

# Mobile Test Report — [Date]

## Device Info
- Model: [device model]
- OS: Android [version]
- App: [app name] v[version]

## Results Summary
| Test | Status | Duration | Screenshots |
|------|--------|----------|-------------|
| Smoke Test | ✅ Pass | 45s | 8 steps |
| Auth Flow | ✅ Pass | 32s | 6 steps |
| Core Workflow | ❌ Fail | 28s | Step 4 failed |

## Failures
### Core Workflow — Step 4
- **Expected:** "checkout button is visible"
- **Actual:** Screen showed loading spinner after 15s
- **Screenshot:** [link to screenshot]

## Visual Replay
Open: ./midscene_run/report/index.html

3. Open the visual replay report automatically

Common Mistakes

Cost Estimation

Handoff Protocol

Execution Checklist

• .env.midscene configured with valid API key
• Device connected and verified (adb devices or simulator running)
• Target app installed on device
• @midscene/android and/or @midscene/ios installed
• Smoke test passes on at least one device
• Critical user flows have test scripts
• Visual replay report generated and reviewed
• Test results documented in tests/e2e/mobile/reports/