mcp-maestro-mobile-ai 1.1.0

package/docs/REACT_NATIVE_AUTOMATION_GUIDELINES.md

@@ -0,0 +1,584 @@
+# React Native Automation Guidelines
+
+## For Maestro-Based Mobile Testing
+
+This document provides comprehensive guidelines for preparing React Native applications for automated testing with Maestro.
+
+---
+
+## Table of Contents
+
+1. [Overview](#overview)
+2. [Accessibility Identifiers](#accessibility-identifiers)
+3. [Naming Conventions](#naming-conventions)
+4. [Component Guidelines](#component-guidelines)
+5. [Screen Guidelines](#screen-guidelines)
+6. [Form Guidelines](#form-guidelines)
+7. [Navigation Guidelines](#navigation-guidelines)
+8. [Common Patterns](#common-patterns)
+9. [Anti-Patterns to Avoid](#anti-patterns-to-avoid)
+10. [Testing Checklist](#testing-checklist)
+11. [Troubleshooting](#troubleshooting)
+
+---
+
+## Overview
+
+Maestro automation relies on Android Accessibility services to interact with UI elements. For reliable and maintainable automated tests, every interactive element must have proper accessibility identifiers.
+
+### Key Principles
+
+- **Every interactive element needs a unique identifier**
+- **Identifiers must be static (not dynamic)**
+- **Use semantic naming that reflects purpose**
+- **Maintain identifiers in a central constants file**
+
+---
+
+## Accessibility Identifiers
+
+### Required Props for Every Interactive Element
+
+```tsx
+<TouchableOpacity
+  testID="login_button"
+  accessibilityLabel="login_button"
+  accessible={true}
+>
+  <Text>Login</Text>
+</TouchableOpacity>
+```
+
+### Why Both `testID` and `accessibilityLabel`?
+
+| Prop | Purpose | Platform |
+|------|---------|----------|
+| `testID` | Primary identifier for testing | iOS & Android (partial) |
+| `accessibilityLabel` | Accessibility services & Maestro | iOS & Android |
+| `accessible` | Marks element as accessible | iOS & Android |
+
+**Important:** Maestro primarily uses `accessibilityLabel` on Android, so always include it.
+
+---
+
+## Naming Conventions
+
+### Standard Suffixes
+
+| Element Type | Suffix | Example |
+|--------------|--------|---------|
+| Screen/View | `_screen` | `login_screen`, `dashboard_screen` |
+| Button | `_button` | `submit_button`, `cancel_button` |
+| Input/TextField | `_input` | `email_input`, `password_input` |
+| Toggle/Switch | `_toggle` | `notifications_toggle` |
+| Checkbox | `_checkbox` | `terms_checkbox` |
+| Tab | `tab_` (prefix) | `tab_home`, `tab_settings` |
+| Link | `_link` | `forgot_password_link` |
+| Icon | `_icon` | `search_icon`, `menu_icon` |
+| Card | `_card` | `user_profile_card` |
+| List Item | `_item` | `contact_item` |
+| Modal/Dialog | `_dialog` or `_modal` | `confirm_dialog` |
+| Section | `_section` | `profile_section` |
+
+### Naming Rules
+
+1. **Use lowercase with underscores** (snake_case)
+2. **Be descriptive but concise**
+3. **Include context when needed** (e.g., `login_email_input` vs just `email_input`)
+4. **Avoid generic names** like `button1`, `input2`
+
+### Good Examples
+
+```tsx
+// ✅ Good - Clear, descriptive, follows convention
+testID="login_email_input"
+testID="forgot_password_link"
+testID="tab_settings"
+testID="save_profile_button"
+testID="dark_mode_toggle"
+```
+
+### Bad Examples
+
+```tsx
+// ❌ Bad - Generic, unclear, or wrong format
+testID="btn1"
+testID="TextField"
+testID="loginButton"  // Should be login_button
+testID={`item_${id}`}  // Dynamic - don't do this
+```
+
+---
+
+## Component Guidelines
+
+### Buttons
+
+```tsx
+// Standard button
+<TouchableOpacity
+  testID="submit_form_button"
+  accessibilityLabel="submit_form_button"
+  accessibilityRole="button"
+  accessible={true}
+  onPress={handleSubmit}
+>
+  <Text>Submit</Text>
+</TouchableOpacity>
+
+// Icon button
+<TouchableOpacity
+  testID="search_icon_button"
+  accessibilityLabel="search_icon_button"
+  accessibilityRole="button"
+  accessibilityHint="Opens search screen"
+  accessible={true}
+  onPress={openSearch}
+>
+  <Icon name="search" />
+</TouchableOpacity>
+```
+
+### Text Inputs
+
+```tsx
+<TextInput
+  testID="email_input"
+  accessibilityLabel="email_input"
+  accessible={true}
+  placeholder="Enter your email"
+  value={email}
+  onChangeText={setEmail}
+  keyboardType="email-address"
+  autoCapitalize="none"
+/>
+```
+
+### Toggles/Switches
+
+```tsx
+<Switch
+  testID="notifications_toggle"
+  accessibilityLabel="notifications_toggle"
+  accessible={true}
+  value={notificationsEnabled}
+  onValueChange={setNotificationsEnabled}
+/>
+```
+
+### Lists
+
+```tsx
+// List container
+<FlatList
+  testID="contacts_list"
+  accessibilityLabel="contacts_list"
+  data={contacts}
+  renderItem={({ item, index }) => (
+    // For list items, use static prefix + position if needed for specific item testing
+    // But prefer testing by visible text content instead
+    <View
+      testID="contact_item"
+      accessibilityLabel={item.name}
+      accessible={true}
+    >
+      <Text>{item.name}</Text>
+    </View>
+  )}
+/>
+```
+
+---
+
+## Screen Guidelines
+
+### Screen Container
+
+Every screen must have a wrapper with a unique screen identifier:
+
+```tsx
+const LoginScreen = () => {
+  return (
+    <SafeAreaView
+      testID="login_screen"
+      accessibilityLabel="login_screen"
+      accessible={false}  // Container not directly accessible
+      style={styles.container}
+    >
+      {/* Screen content */}
+    </SafeAreaView>
+  );
+};
+```
+
+### Screen Wrapper Component (Recommended)
+
+Create a reusable screen wrapper:
+
+```tsx
+// components/ScreenWrapper.tsx
+interface ScreenWrapperProps {
+  screenId: string;
+  children: React.ReactNode;
+}
+
+export const ScreenWrapper: React.FC<ScreenWrapperProps> = ({ 
+  screenId, 
+  children 
+}) => {
+  return (
+    <SafeAreaView
+      testID={screenId}
+      accessibilityLabel={screenId}
+      accessible={false}
+      style={styles.container}
+    >
+      {children}
+    </SafeAreaView>
+  );
+};
+
+// Usage
+const DashboardScreen = () => (
+  <ScreenWrapper screenId="dashboard_screen">
+    {/* Screen content */}
+  </ScreenWrapper>
+);
+```
+
+---
+
+## Form Guidelines
+
+### Complete Form Example
+
+```tsx
+const RegistrationForm = () => {
+  return (
+    <View testID="registration_form" accessibilityLabel="registration_form">
+      <TextInput
+        testID="first_name_input"
+        accessibilityLabel="first_name_input"
+        placeholder="First Name"
+      />
+      
+      <TextInput
+        testID="last_name_input"
+        accessibilityLabel="last_name_input"
+        placeholder="Last Name"
+      />
+      
+      <TextInput
+        testID="email_input"
+        accessibilityLabel="email_input"
+        placeholder="Email"
+        keyboardType="email-address"
+      />
+      
+      <TextInput
+        testID="password_input"
+        accessibilityLabel="password_input"
+        placeholder="Password"
+        secureTextEntry
+      />
+      
+      <TouchableOpacity
+        testID="terms_checkbox"
+        accessibilityLabel="terms_checkbox"
+        accessibilityRole="checkbox"
+      >
+        <Text>I agree to terms</Text>
+      </TouchableOpacity>
+      
+      <TouchableOpacity
+        testID="register_button"
+        accessibilityLabel="register_button"
+        accessibilityRole="button"
+      >
+        <Text>Register</Text>
+      </TouchableOpacity>
+    </View>
+  );
+};
+```
+
+---
+
+## Navigation Guidelines
+
+### Bottom Tab Navigator
+
+```tsx
+<Tab.Navigator>
+  <Tab.Screen 
+    name="Home"
+    component={HomeScreen}
+    options={{
+      tabBarTestID: 'tab_home',
+      tabBarAccessibilityLabel: 'tab_home',
+    }}
+  />
+  <Tab.Screen 
+    name="Safety"
+    component={SafetyScreen}
+    options={{
+      tabBarTestID: 'tab_safety',
+      tabBarAccessibilityLabel: 'tab_safety',
+    }}
+  />
+  <Tab.Screen 
+    name="Settings"
+    component={SettingsScreen}
+    options={{
+      tabBarTestID: 'tab_settings',
+      tabBarAccessibilityLabel: 'tab_settings',
+    }}
+  />
+</Tab.Navigator>
+```
+
+### Header Buttons
+
+```tsx
+<Stack.Screen
+  name="Profile"
+  component={ProfileScreen}
+  options={{
+    headerRight: () => (
+      <TouchableOpacity
+        testID="edit_profile_header_button"
+        accessibilityLabel="edit_profile_header_button"
+      >
+        <Text>Edit</Text>
+      </TouchableOpacity>
+    ),
+  }}
+/>
+```
+
+---
+
+## Common Patterns
+
+### Modal/Dialog
+
+```tsx
+<Modal
+  testID="confirm_dialog"
+  accessibilityLabel="confirm_dialog"
+  visible={visible}
+>
+  <View testID="confirm_dialog_content">
+    <Text>Are you sure?</Text>
+    
+    <TouchableOpacity
+      testID="confirm_yes_button"
+      accessibilityLabel="confirm_yes_button"
+    >
+      <Text>Yes</Text>
+    </TouchableOpacity>
+    
+    <TouchableOpacity
+      testID="confirm_no_button"
+      accessibilityLabel="confirm_no_button"
+    >
+      <Text>No</Text>
+    </TouchableOpacity>
+  </View>
+</Modal>
+```
+
+### Loading States
+
+```tsx
+{isLoading ? (
+  <View testID="loading_indicator" accessibilityLabel="loading_indicator">
+    <ActivityIndicator />
+  </View>
+) : (
+  <View testID="content_loaded" accessibilityLabel="content_loaded">
+    {/* Content */}
+  </View>
+)}
+```
+
+### Error States
+
+```tsx
+{error && (
+  <View testID="error_message" accessibilityLabel="error_message">
+    <Text>{error.message}</Text>
+    <TouchableOpacity
+      testID="retry_button"
+      accessibilityLabel="retry_button"
+    >
+      <Text>Retry</Text>
+    </TouchableOpacity>
+  </View>
+)}
+```
+
+---
+
+## Anti-Patterns to Avoid
+
+### ❌ Dynamic IDs
+
+```tsx
+// DON'T - Dynamic IDs break automation
+testID={`item_${item.id}`}
+testID={`button_${index}`}
+testID={`${screenName}_input`}
+```
+
+### ❌ Text-Based Selectors
+
+```tsx
+// DON'T - Text can change with translations
+// Maestro: tapOn: "Login"  <- Fragile!
+
+// DO - Use IDs
+testID="login_button"
+```
+
+### ❌ Missing Identifiers on Interactive Elements
+
+```tsx
+// DON'T - No testID
+<TouchableOpacity onPress={handlePress}>
+  <Text>Click Me</Text>
+</TouchableOpacity>
+
+// DO - Always add testID and accessibilityLabel
+<TouchableOpacity
+  testID="action_button"
+  accessibilityLabel="action_button"
+  onPress={handlePress}
+>
+  <Text>Click Me</Text>
+</TouchableOpacity>
+```
+
+### ❌ Inconsistent Naming
+
+```tsx
+// DON'T - Mixed conventions
+testID="loginBtn"
+testID="SUBMIT_BUTTON"
+testID="userEmail"
+
+// DO - Consistent snake_case with proper suffixes
+testID="login_button"
+testID="submit_button"
+testID="user_email_input"
+```
+
+---
+
+## Testing Checklist
+
+### Pre-PR Checklist
+
+- [ ] All interactive elements have `testID`
+- [ ] All interactive elements have `accessibilityLabel`
+- [ ] Screen containers have unique `_screen` identifiers
+- [ ] IDs follow naming conventions
+- [ ] No dynamic IDs used
+- [ ] Constants file updated (if using centralized constants)
+- [ ] New screens documented
+
+### Centralized Constants File
+
+Maintain all testIDs in a central file:
+
+```tsx
+// constants/testIds.ts
+export const TEST_IDS = {
+  // Screens
+  LOGIN_SCREEN: 'login_screen',
+  DASHBOARD_SCREEN: 'dashboard_screen',
+  SETTINGS_SCREEN: 'settings_screen',
+  
+  // Login Screen
+  EMAIL_INPUT: 'email_input',
+  PASSWORD_INPUT: 'password_input',
+  LOGIN_BUTTON: 'login_button',
+  FORGOT_PASSWORD_LINK: 'forgot_password_link',
+  
+  // Navigation
+  TAB_HOME: 'tab_home',
+  TAB_SAFETY: 'tab_safety',
+  TAB_SECURITY: 'tab_security',
+  TAB_CONTACTS: 'tab_contacts',
+  TAB_SETTINGS: 'tab_settings',
+  
+  // ... more IDs
+} as const;
+
+// Usage
+import { TEST_IDS } from '@/constants/testIds';
+
+<TouchableOpacity testID={TEST_IDS.LOGIN_BUTTON}>
+```
+
+---
+
+## Troubleshooting
+
+### Element Not Found
+
+1. **Check if `accessibilityLabel` is set** (Maestro uses this on Android)
+2. **Verify element is visible** (not hidden by scroll or z-index)
+3. **Check for typos** in the ID
+4. **Use Maestro Studio** to inspect the element tree
+
+### Flaky Tests
+
+1. **Add explicit waits** using `extendedWaitUntil`
+2. **Check for animations** that might delay element visibility
+3. **Verify network calls complete** before assertions
+
+### Maestro Studio Inspection
+
+```bash
+# Launch Maestro Studio to inspect element tree
+maestro studio
+```
+
+### Debug Mode
+
+```yaml
+# Add to flow for debugging
+- takeScreenshot: "debug-screenshot"
+- evalScript: |
+    console.log(JSON.stringify(maestro.tree(), null, 2))
+```
+
+---
+
+## Quick Reference Card
+
+| Element | testID Format | Example |
+|---------|---------------|---------|
+| Screen | `{name}_screen` | `login_screen` |
+| Button | `{action}_button` | `submit_button` |
+| Input | `{field}_input` | `email_input` |
+| Tab | `tab_{name}` | `tab_home` |
+| Toggle | `{feature}_toggle` | `dark_mode_toggle` |
+| Link | `{action}_link` | `forgot_password_link` |
+| Modal | `{name}_dialog` | `confirm_dialog` |
+| Icon | `{action}_icon` | `search_icon` |
+
+---
+
+## Resources
+
+- [Maestro Documentation](https://maestro.mobile.dev/)
+- [React Native Accessibility](https://reactnative.dev/docs/accessibility)
+- [Android Accessibility](https://developer.android.com/guide/topics/ui/accessibility)
+
+---
+
+**Document Version:** 1.0  
+**Last Updated:** December 2024
+