mcp-maestro-mobile-ai 1.3.1 → 1.6.0

package/src/mcp-server/utils/knownIssues.js

@@ -0,0 +1,564 @@
+/**
+ * Generic Mobile Interaction Patterns
+ * 
+ * Framework-agnostic patterns for reliable mobile test automation.
+ * These patterns are designed to reduce test failures across ANY mobile application
+ * regardless of whether it's built with Flutter, React Native, or native technologies.
+ * 
+ * NO app-specific values or hard-coded coordinates.
+ * NO framework-specific identifiers.
+ * Focus on STRATEGIES and PATTERNS that improve test resilience.
+ */
+
+/**
+ * Interaction pattern categories
+ */
+export const PatternCategory = {
+  KEYBOARD_HANDLING: 'keyboard_handling',
+  ELEMENT_INTERACTION: 'element_interaction',
+  TIMING_SYNC: 'timing_synchronization',
+  INPUT_HANDLING: 'input_handling',
+  DROPDOWN_PICKER: 'dropdown_picker',
+  NAVIGATION: 'navigation',
+  SCROLL_VISIBILITY: 'scroll_visibility',
+  FALLBACK_STRATEGIES: 'fallback_strategies',
+};
+
+/**
+ * Generic Interaction Patterns
+ * 
+ * Each pattern describes:
+ * - situation: When to apply this pattern
+ * - strategy: The generic approach
+ * - yamlPattern: Template YAML (with placeholders)
+ * - rationale: Why this pattern improves reliability
+ */
+export const INTERACTION_PATTERNS = {
+  // ============================================
+  // KEYBOARD HANDLING PATTERNS
+  // ============================================
+  
+  HIDE_KEYBOARD_BEFORE_TAP: {
+    category: PatternCategory.KEYBOARD_HANDLING,
+    situation: 'Before tapping any element that might be covered by the keyboard',
+    strategy: `After entering text in any input field, ALWAYS hide the keyboard before 
+interacting with other elements (buttons, dropdowns, links) that may be positioned 
+below or near the input fields.`,
+    yamlPattern: `# After text input, before tapping other elements
+- tapOn: "{input_field}"
+- inputText: "{value}"
+
+# ALWAYS hide keyboard before next interaction
+- hideKeyboard
+- waitForAnimationToEnd
+
+# Now safe to tap elements that may have been covered
+- tapOn: "{next_element}"`,
+    rationale: 'On-screen keyboards can cover 40-50% of the screen. Elements below text fields become untappable until keyboard is dismissed.',
+  },
+
+  DOUBLE_WAIT_AFTER_KEYBOARD: {
+    category: PatternCategory.KEYBOARD_HANDLING,
+    situation: 'When keyboard dismissal animation interferes with next action',
+    strategy: `Some apps have longer keyboard dismissal animations. Use double wait 
+when single wait is insufficient.`,
+    yamlPattern: `- hideKeyboard
+- waitForAnimationToEnd
+- waitForAnimationToEnd  # Extra wait for complete dismissal
+
+- tapOn: "{element}"`,
+    rationale: 'Keyboard dismissal can trigger layout reflows. Double wait ensures UI has fully settled.',
+  },
+
+  // ============================================
+  // INPUT HANDLING PATTERNS
+  // ============================================
+
+  TAP_BEFORE_INPUT: {
+    category: PatternCategory.INPUT_HANDLING,
+    situation: 'ALWAYS, before every inputText command',
+    strategy: `NEVER use inputText without a preceding tapOn. The inputText command 
+sends keystrokes to the currently focused element. Without tapOn, text may go to 
+the wrong field.`,
+    yamlPattern: `# CORRECT PATTERN
+- tapOn: "{field_name}"
+- inputText: "{value}"
+
+# WRONG - text may go to previously focused field
+# - inputText: "{value}"  # NO!`,
+    rationale: 'inputText sends keystrokes to whatever element has focus. Only tapOn guarantees the correct field is focused.',
+  },
+
+  CLEAR_BEFORE_RETRY: {
+    category: PatternCategory.INPUT_HANDLING,
+    situation: 'When re-entering data into a field that may contain previous input',
+    strategy: `Use eraseText before inputText when:
+- Retrying after a failed attempt
+- Editing existing values
+- Looping through multiple test iterations`,
+    yamlPattern: `# Clear existing content before new input
+- tapOn: "{field}"
+- eraseText: 50        # Erase up to 50 characters
+- inputText: "{new_value}"`,
+    rationale: 'Fields may retain previous values. eraseText ensures clean state before new input.',
+  },
+
+  WAIT_BETWEEN_INPUTS: {
+    category: PatternCategory.INPUT_HANDLING,
+    situation: 'When filling multiple fields in sequence',
+    strategy: `Add waitForAnimationToEnd between field inputs when tests fail due to 
+focus not shifting properly.`,
+    yamlPattern: `- tapOn: "{field_1}"
+- inputText: "{value_1}"
+
+- waitForAnimationToEnd  # Let focus settle
+
+- tapOn: "{field_2}"
+- inputText: "{value_2}"`,
+    rationale: 'Some apps have focus transition animations. Waiting prevents input going to wrong field.',
+  },
+
+  // ============================================
+  // ELEMENT INTERACTION PATTERNS
+  // ============================================
+
+  VERIFY_BEFORE_INTERACT: {
+    category: PatternCategory.ELEMENT_INTERACTION,
+    situation: 'Before interacting with critical elements',
+    strategy: `Use extendedWaitUntil to verify element visibility and readiness 
+before attempting interaction. This prevents failures due to loading states.`,
+    yamlPattern: `# Wait for element to be ready
+- extendedWaitUntil:
+    visible: "{element_identifier}"
+    timeout: 10000
+
+# Now interact with confidence
+- tapOn: "{element_identifier}"`,
+    rationale: 'Elements may exist in DOM but not be interactive yet. Explicit wait ensures readiness.',
+  },
+
+  MULTIPLE_SELECTOR_FALLBACK: {
+    category: PatternCategory.ELEMENT_INTERACTION,
+    situation: 'When primary selector may not work in all scenarios',
+    strategy: `Use runFlow with conditional checks to try multiple selectors:
+1. Try primary selector
+2. If not visible, try alternative selector
+3. Use index-based selection as last resort`,
+    yamlPattern: `# Try primary selector
+- runFlow:
+    when:
+      visible: "{primary_selector}"
+    commands:
+      - tapOn: "{primary_selector}"
+
+# Fallback to alternative
+- runFlow:
+    when:
+      notVisible: "{primary_selector}"
+    commands:
+      - tapOn: "{alternative_selector}"`,
+    rationale: 'Element identifiers may vary across app versions or device configurations.',
+  },
+
+  // ============================================
+  // DROPDOWN/PICKER PATTERNS
+  // ============================================
+
+  DROPDOWN_INTERACTION: {
+    category: PatternCategory.DROPDOWN_PICKER,
+    situation: 'When interacting with dropdown menus, pickers, or select elements',
+    strategy: `Standard dropdown interaction flow:
+1. Hide keyboard (if any text field was previously focused)
+2. Wait for any pending animations
+3. Tap the dropdown trigger element (current value or dropdown button)
+4. Wait for dropdown/overlay to appear
+5. Tap the desired option
+6. Wait for dropdown to close`,
+    yamlPattern: `# Step 1: Ensure keyboard is hidden
+- hideKeyboard
+- waitForAnimationToEnd
+
+# Step 2: Open dropdown (tap current value or trigger)
+- tapOn: "{dropdown_trigger}"
+- waitForAnimationToEnd
+
+# Step 3: Select option
+- tapOn: "{desired_option}"
+- waitForAnimationToEnd`,
+    rationale: 'Dropdowns render as overlays. Proper timing between steps prevents missed taps.',
+  },
+
+  SCROLLABLE_DROPDOWN: {
+    category: PatternCategory.DROPDOWN_PICKER,
+    situation: 'When dropdown options may require scrolling',
+    strategy: `If the desired option is not immediately visible in the dropdown:
+1. Open dropdown
+2. Scroll within dropdown to find option
+3. Then tap the option`,
+    yamlPattern: `- tapOn: "{dropdown_trigger}"
+- waitForAnimationToEnd
+
+# Scroll if option might be below visible area
+- scroll
+
+- tapOn: "{desired_option}"
+- waitForAnimationToEnd`,
+    rationale: 'Long option lists may require scrolling. Option must be visible before tapping.',
+  },
+
+  // ============================================
+  // TIMING & SYNCHRONIZATION PATTERNS
+  // ============================================
+
+  WAIT_FOR_SCREEN_TRANSITION: {
+    category: PatternCategory.TIMING_SYNC,
+    situation: 'After actions that trigger navigation (login, submit, next)',
+    strategy: `After triggering navigation:
+1. Wait for a unique element on the DESTINATION screen
+2. Use longer timeout for network-dependent transitions
+3. Assert destination reached before proceeding`,
+    yamlPattern: `# Trigger navigation
+- tapOn: "{submit_button}"
+
+# Wait for destination screen element
+- extendedWaitUntil:
+    visible: "{destination_screen_element}"
+    timeout: 30000
+
+# Verify we're on correct screen
+- assertVisible: "{destination_screen_element}"`,
+    rationale: 'Navigation may involve network calls, animations, or complex transitions.',
+  },
+
+  WAIT_FOR_LOADING_COMPLETE: {
+    category: PatternCategory.TIMING_SYNC,
+    situation: 'When screen has loading indicators',
+    strategy: `Wait for loading to complete by:
+1. Waiting for loading indicator to disappear, OR
+2. Waiting for content elements to appear`,
+    yamlPattern: `# Option 1: Wait for loading to disappear
+- extendedWaitUntil:
+    notVisible: "{loading_indicator}"
+    timeout: 15000
+
+# Option 2: Wait for content to appear
+- extendedWaitUntil:
+    visible: "{content_element}"
+    timeout: 15000`,
+    rationale: 'Interacting during loading state causes unpredictable failures.',
+  },
+
+  ANIMATION_BUFFER: {
+    category: PatternCategory.TIMING_SYNC,
+    situation: 'After any action that triggers UI animation',
+    strategy: `Use waitForAnimationToEnd after:
+- Opening/closing modals
+- Expanding/collapsing sections
+- Tab switches
+- Any visual transition`,
+    yamlPattern: `- tapOn: "{element_that_triggers_animation}"
+- waitForAnimationToEnd
+
+# Proceed after animation completes
+- tapOn: "{next_element}"`,
+    rationale: 'Tapping during animation often fails or taps wrong element.',
+  },
+
+  // ============================================
+  // SCROLL & VISIBILITY PATTERNS
+  // ============================================
+
+  SCROLL_TO_ELEMENT: {
+    category: PatternCategory.SCROLL_VISIBILITY,
+    situation: 'When element may be below the visible fold',
+    strategy: `Scroll before attempting to tap elements that might not be visible:
+- Form fields at bottom of long forms
+- List items below the fold
+- Buttons at page bottom`,
+    yamlPattern: `# Scroll to bring element into view
+- scroll
+
+# Then interact
+- tapOn: "{element_below_fold}"`,
+    rationale: 'Elements must be visible on screen to be tappable.',
+  },
+
+  SCROLL_AND_VERIFY: {
+    category: PatternCategory.SCROLL_VISIBILITY,
+    situation: 'When you need to confirm element is visible after scroll',
+    strategy: `Combine scroll with visibility assertion for reliability.`,
+    yamlPattern: `- scroll
+- waitForAnimationToEnd
+
+- assertVisible: "{target_element}"
+- tapOn: "{target_element}"`,
+    rationale: 'Verifying visibility after scroll ensures element is in tappable area.',
+  },
+
+  // ============================================
+  // NAVIGATION PATTERNS
+  // ============================================
+
+  BACK_NAVIGATION: {
+    category: PatternCategory.NAVIGATION,
+    situation: 'When navigating back to previous screen',
+    strategy: `Use pressKey: back for system back navigation. Wait for 
+previous screen element to confirm navigation succeeded.`,
+    yamlPattern: `- pressKey: back
+- waitForAnimationToEnd
+
+- assertVisible: "{previous_screen_element}"`,
+    rationale: 'Back navigation varies by platform. pressKey: back is most reliable.',
+  },
+
+  // ============================================
+  // FALLBACK STRATEGIES
+  // ============================================
+
+  ELEMENT_NOT_FOUND_STRATEGY: {
+    category: PatternCategory.FALLBACK_STRATEGIES,
+    situation: 'When element selector is not finding the element',
+    strategy: `Progressive fallback approach:
+1. Verify correct screen (add assertVisible for screen identifier)
+2. Add scroll in case element is below fold
+3. Try alternative text/label that might match
+4. Check if keyboard is covering element
+5. As last resort, capture hierarchy for analysis`,
+    yamlPattern: `# Step 1: Confirm we're on right screen
+- assertVisible: "{screen_identifier}"
+
+# Step 2: Hide keyboard if it might be covering
+- hideKeyboard
+- waitForAnimationToEnd
+
+# Step 3: Scroll in case element is below fold
+- scroll
+- waitForAnimationToEnd
+
+# Step 4: Try to interact
+- tapOn: "{element}"`,
+    rationale: 'Systematic fallback identifies root cause without blind retries.',
+  },
+
+  TAP_NOT_WORKING_STRATEGY: {
+    category: PatternCategory.FALLBACK_STRATEGIES,
+    situation: 'When tap is found but action does not trigger',
+    strategy: `Element may not be interactive yet:
+1. Add explicit wait before tap
+2. Hide keyboard if near text fields
+3. Wait for any loading to complete
+4. Ensure element is fully visible (not partially off-screen)`,
+    yamlPattern: `# Ensure element is ready
+- extendedWaitUntil:
+    visible: "{element}"
+    timeout: 10000
+
+# Clear any overlays
+- hideKeyboard
+- waitForAnimationToEnd
+
+# Now tap
+- tapOn: "{element}"`,
+    rationale: 'Element visibility does not guarantee interactivity. Explicit waits help.',
+  },
+};
+
+/**
+ * Get interaction patterns by category
+ */
+export function getPatternsByCategory(category) {
+  return Object.entries(INTERACTION_PATTERNS)
+    .filter(([_, pattern]) => pattern.category === category)
+    .reduce((acc, [key, pattern]) => ({ ...acc, [key]: pattern }), {});
+}
+
+/**
+ * Get all pattern categories
+ */
+export function getPatternCategories() {
+  return Object.values(PatternCategory);
+}
+
+/**
+ * Generate YAML generation hints from patterns
+ * This is embedded into YAML generation context
+ */
+export function getInteractionPatternHints() {
+  return `
+## GENERIC INTERACTION PATTERNS FOR RELIABLE TESTS
+
+Apply these patterns to reduce test failures across any mobile application.
+
+### 🔴 CRITICAL: Keyboard Handling
+
+**ALWAYS hide keyboard before interacting with elements that might be covered:**
+\`\`\`yaml
+# After ANY text input
+- tapOn: "{field}"
+- inputText: "{value}"
+
+# Before ANY button, dropdown, or link below text fields
+- hideKeyboard
+- waitForAnimationToEnd
+
+- tapOn: "{button_or_dropdown}"
+\`\`\`
+
+### 🔴 CRITICAL: Input Field Pattern
+
+**ALWAYS tap before inputText:**
+\`\`\`yaml
+# CORRECT - ensures correct field is focused
+- tapOn: "{field_name}"
+- inputText: "{value}"
+
+# WRONG - may input to previously focused field
+- inputText: "{value}"
+\`\`\`
+
+### 🟡 IMPORTANT: Dropdown/Picker Interaction
+
+\`\`\`yaml
+# Standard dropdown pattern
+- hideKeyboard
+- waitForAnimationToEnd
+
+- tapOn: "{dropdown_trigger}"      # Current value or dropdown button
+- waitForAnimationToEnd            # Wait for options to appear
+
+- tapOn: "{option_to_select}"      # Select desired option
+- waitForAnimationToEnd            # Wait for dropdown to close
+\`\`\`
+
+### 🟡 IMPORTANT: Screen Transitions
+
+**After navigation actions, wait for destination screen:**
+\`\`\`yaml
+- tapOn: "{submit_or_navigate_button}"
+
+- extendedWaitUntil:
+    visible: "{element_on_next_screen}"
+    timeout: 30000
+
+- assertVisible: "{element_on_next_screen}"
+\`\`\`
+
+### 🟢 RECOMMENDED: Before Critical Interactions
+
+**Verify element is ready before interaction:**
+\`\`\`yaml
+- extendedWaitUntil:
+    visible: "{important_element}"
+    timeout: 10000
+
+- tapOn: "{important_element}"
+\`\`\`
+
+### 🟢 RECOMMENDED: After Animations
+
+**Wait after any action that triggers visual change:**
+\`\`\`yaml
+- tapOn: "{element_causing_animation}"
+- waitForAnimationToEnd
+
+- tapOn: "{next_element}"
+\`\`\`
+
+### 🟢 RECOMMENDED: Elements Below Fold
+
+**Scroll before interacting with elements that may not be visible:**
+\`\`\`yaml
+- scroll
+- waitForAnimationToEnd
+
+- tapOn: "{element_below_fold}"
+\`\`\`
+
+### 🟢 RECOMMENDED: Retry Scenarios
+
+**Clear field before re-entering data:**
+\`\`\`yaml
+- tapOn: "{field}"
+- eraseText: 50
+- inputText: "{new_value}"
+\`\`\`
+`;
+}
+
+/**
+ * Get YAML generation rules derived from patterns
+ * These are the core rules that should be applied during generation
+ */
+export function getYamlGenerationRules() {
+  return {
+    // Mandatory rules (apply always)
+    mandatory: {
+      tapBeforeInput: true,
+      hideKeyboardBeforeDropdown: true,
+      hideKeyboardBeforeButtonsBelowFields: true,
+      waitAfterNavigation: true,
+      startWithClearStateAndLaunch: true,
+    },
+    
+    // Recommended rules (apply for better reliability)
+    recommended: {
+      waitAfterAnimations: true,
+      verifyBeforeCriticalInteractions: true,
+      scrollBeforeElementsBelowFold: true,
+      eraseBeforeRetryInput: true,
+      doubleWaitAfterKeyboardHide: false, // Only when needed
+    },
+    
+    // Timing defaults
+    timing: {
+      defaultTimeout: 10000,
+      navigationTimeout: 30000,
+      loadingTimeout: 15000,
+    },
+  };
+}
+
+/**
+ * Get platform-agnostic best practices
+ * These apply regardless of the app's framework
+ */
+export function getBestPractices() {
+  return `
+## BEST PRACTICES FOR RELIABLE MOBILE TESTS
+
+### Test Structure
+1. ALWAYS start with \`clearState\` then \`launchApp\`
+2. Wait for initial screen to fully load before first interaction
+3. End with assertions that verify expected outcome
+
+### Element Interaction
+1. Use visible text/labels as primary selectors
+2. Add explicit waits for elements that may load asynchronously
+3. Hide keyboard before interacting with elements below text fields
+
+### Form Filling
+1. Tap each field before entering text
+2. Hide keyboard before tapping submit buttons
+3. Wait for form submission response
+
+### Navigation
+1. Wait for destination screen elements after navigation
+2. Use longer timeouts for network-dependent screens
+3. Verify you're on correct screen before proceeding
+
+### Error Handling
+1. Add waits at failure-prone steps
+2. Scroll if elements might be below visible area
+3. Hide keyboard if elements might be covered
+`;
+}
+
+export default {
+  PatternCategory,
+  INTERACTION_PATTERNS,
+  getPatternsByCategory,
+  getPatternCategories,
+  getInteractionPatternHints,
+  getYamlGenerationRules,
+  getBestPractices,
+};