tabatago/.maestro/README.md

Maestro UI Testing

This directory contains Maestro UI tests for TabataFit.

Prerequisites

1. Install Maestro CLI:

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

2. Build and install the app on your simulator/device:

# iOS
npx expo run:ios

# Android
npx expo run:android

Running Tests

Run All Tests

npm run test:maestro:all

Run Individual Tests

# Onboarding flow
npm run test:maestro:onboarding

# Program browsing
npm run test:maestro:programs

# Tab navigation
npm run test:maestro:tabs

# Paywall/subscription
npm run test:maestro:paywall

# Reset app state
npm run test:maestro:reset

Run with Maestro CLI directly

# Run specific flow
maestro test .maestro/flows/onboarding.yaml

# Run all flows
maestro test .maestro/flows

# Run with device selection
maestro test --device "iPhone 15" .maestro/flows/onboarding.yaml

Test Flows

Flow	Description	Prerequisites
onboarding.yaml	Complete 6-step onboarding	Fresh install
program-browse.yaml	Browse and select programs	Completed onboarding
tab-navigation.yaml	Navigate between tabs	Completed onboarding
subscription.yaml	Test paywall interactions	Fresh install
assessment.yaml	Start assessment workout	Completed onboarding, not assessment
reset-state.yaml	Reset app to fresh state	None
all-tests.yaml	Run all test flows	None

Test IDs

Key UI elements have testID props for reliable element selection:

Onboarding

• onboarding-problem-cta - Step 1 continue button
• barrier-{id} - Barrier selection cards (no-time, low-motivation, no-knowledge, no-gym)
• onboarding-empathy-continue - Step 2 continue button
• onboarding-solution-cta - Step 3 continue button
• onboarding-wow-cta - Step 4 continue button
• name-input - Name text input
• level-{level} - Fitness level buttons (beginner, intermediate, advanced)
• goal-{goal} - Goal buttons (weight-loss, cardio, strength, wellness)
• frequency-{n}x - Frequency buttons (2x, 3x, 5x)
• onboarding-personalization-continue - Step 5 continue button
• plan-yearly - Annual subscription card
• plan-monthly - Monthly subscription card
• subscribe-button - Subscribe CTA
• restore-purchases - Restore purchases link
• skip-paywall - Skip paywall link

Home Screen

• program-card-{id} - Program cards (upper-body, lower-body, full-body)
• program-{id}-cta - Program CTA buttons
• assessment-card - Assessment workout card

Writing New Tests

1. Add testID prop to interactive elements in your component:

<Pressable testID="my-button" onPress={handlePress}>
  <Text>Click me</Text>
</Pressable>

2. Create a new YAML file in .maestro/flows/:

appId: com.millianlmx.tabatafit
name: My Test

---
- assertVisible: "my-button"
- tapOn: "my-button"

3. Add npm script to package.json:

"test:maestro:mytest": "maestro test .maestro/flows/my-test.yaml"

CI/CD Integration

For GitHub Actions, add:

- name: Run Maestro Tests
  run: |
    brew tap mobile-dev-inc/tap
    brew install maestro
    npm run test:maestro:all

Tips

• Use assertVisible to wait for elements
• Use optional: true for elements that may not exist
• Use extendedWaitUntil for longer timeouts
• Use runFlow to compose tests from smaller flows
• Use env to parameterize tests

Debugging

# Verbose output
maestro test --verbose .maestro/flows/onboarding.yaml

# Take screenshot on failure
maestro test --screenshot .maestro/flows/onboarding.yaml

# Record video
maestro record .maestro/flows/onboarding.yaml

Resources

• Maestro Documentation
• Maestro CLI Reference
• Element Selectors