Testing with Maestro

This guide covers how to write, run, and maintain Maestro tests for the ticked-off Expo app.

Overview

Maestro is a mobile testing framework that allows us to write UI tests in YAML. All core functionality must be covered by Maestro tests (see AGENTS.md).

Installation

Install the Maestro CLI:

brew tap mobile-dev-inc/tap
brew install maestro

Or via npm:

npm install -g maestro-cli

Project Structure

Tests are located in the e2e/flows/ directory:

e2e/
├── flows/
│   ├── smoke.yaml          # Basic app launch and visibility tests
│   ├── navigation.yaml     # Navigation flow tests
│   └── features.yaml       # Feature-specific tests

Running Tests

Local Testing

1. Start the Expo dev server:

``bash expo start --ios # or --android ``

1. Run Maestro tests in another terminal:

``bash npm run test:maestro ``

Run Specific Flow

maestro test e2e/flows/smoke.yaml

Writing Tests

Basic Structure

Every Maestro test file starts with appId and ---:

appId: com.ticked-off
---
- launchApp
- assertVisible:
    text: "Expected text"

Common Commands

Best Practices

1. Use testIDs for reliable test targeting:

``tsx <Text testID="welcome-message">Welcome</Text> ``

Then in Maestro:

``yaml - tapOn: id: "welcome-message" ``

1. Keep flows focused - Each flow should test one feature
2. Use descriptive names - navigation.yaml, not test1.yaml
3. Minimize nested conditions - Align with project coding standards (AGENTS.md)
4. Early assertions - Check critical state early in tests

Example Test Flow

appId: com.ticked-off
---
- launchApp
- assertVisible:
    text: "Edit app/index.tsx to edit this screen."
- scroll
- scroll
- assertVisible:
    text: "Edit app/index.tsx to edit this screen."

Debugging

View test output

maestro test e2e/flows/smoke.yaml --verbose

Common Issues

• App not launching: Ensure app is built and simulator/emulator is running
• Element not found: Check testID spelling and app state
• Flaky tests: Add waitForAnimationToEnd before assertions on animated elements

CI/CD Integration

For GitHub Actions, add to .github/workflows/test.yml:

name: Maestro Tests

on: [push, pull_request]

jobs:
  maestro:
    runs-on: macos-latest
    steps:
      - uses: actions/checkout@v3
      - uses: maestrosecurity/[email protected]
        with:
          maestro-version: latest
          workspace: e2e

References

• Maestro Documentation
• Expo Testing Guide
• [Project Guidelines](AGENTS.md)