mcp-maestro-mobile-ai 1.1.1 → 1.3.1

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

@@ -0,0 +1,559 @@
+/**
+ * YAML Generation Template System
+ *
+ * Provides comprehensive, GENERIC instructions for AI to generate valid Maestro YAML.
+ * Works for ANY test scenario - login, forms, navigation, search, etc.
+ */
+
+/**
+ * COMPREHENSIVE YAML generation instructions for AI
+ * These are GENERIC rules that apply to ALL test scenarios
+ */
+export const YAML_GENERATION_INSTRUCTIONS = `
+## MAESTRO YAML GENERATION RULES (GENERIC - FOR ALL SCENARIOS)
+
+⚠️ CRITICAL: Follow these rules EXACTLY for ALL test types.
+
+---
+
+### 1. YAML STRUCTURE (ALWAYS REQUIRED)
+
+Every YAML file MUST have this structure:
+
+\`\`\`yaml
+appId: {APP_ID}
+---
+# Description of what this test does
+- clearState           # ALWAYS first - clears app data
+- launchApp            # ALWAYS second - opens the app
+# ... your test steps here ...
+\`\`\`
+
+---
+
+### 2. TEXT INPUT PATTERN (⚠️ MOST CRITICAL RULE)
+
+**RULE: You MUST ALWAYS tap on a field BEFORE entering text.**
+
+✅ CORRECT - Always use this pattern:
+\`\`\`yaml
+- tapOn: "Field Name"      # Step 1: Tap to focus the field
+- inputText: "your value"  # Step 2: Then type the text
+\`\`\`
+
+❌ WRONG - This will put text in the WRONG field:
+\`\`\`yaml
+- inputText: "your value"  # NO! Missing tapOn - text goes to currently focused field!
+\`\`\`
+
+**Example for ANY form with multiple fields:**
+\`\`\`yaml
+# First field
+- tapOn: "First Field Label"
+- inputText: "first value"
+
+# Second field  
+- tapOn: "Second Field Label"
+- inputText: "second value"
+
+# Third field
+- tapOn: "Third Field Label"  
+- inputText: "third value"
+
+# Submit
+- tapOn: "Submit Button"
+\`\`\`
+
+---
+
+### 3. ELEMENT SELECTION (How to identify UI elements)
+
+Use these selectors IN ORDER of preference:
+
+| Priority | Selector Type | YAML Syntax | When to Use |
+|----------|--------------|-------------|-------------|
+| 1 (Best) | testID | \`- tapOn: id: "element-id"\` | When you know the testID |
+| 2 | accessibilityLabel | \`- tapOn: "Label Text"\` | For accessibility labels |
+| 3 | Visible Text | \`- tapOn: "Button Text"\` | For visible button/link text |
+| 4 | Contains Text | \`- tapOn: text: "partial"\` | When text partially matches |
+| 5 (Last) | Index | \`- tapOn: index: 0\` | Only if nothing else works |
+
+**NEVER use coordinates unless absolutely necessary.**
+
+---
+
+### 4. COMMON ACTIONS REFERENCE
+
+| What You Want | YAML Command | Example |
+|---------------|--------------|---------|
+| Tap a button/element | \`- tapOn:\` | \`- tapOn: "Submit"\` |
+| Tap by testID | \`- tapOn: id:\` | \`- tapOn: id: "submit-btn"\` |
+| Enter text (after tapOn) | \`- inputText:\` | \`- inputText: "hello"\` |
+| Clear text field | \`- eraseText: 50\` | Erases 50 characters |
+| Assert element visible | \`- assertVisible:\` | \`- assertVisible: "Success"\` |
+| Assert NOT visible | \`- assertNotVisible:\` | \`- assertNotVisible: "Error"\` |
+| Wait for element | \`- extendedWaitUntil:\` | See below |
+| Scroll down | \`- scroll\` | \`- scroll\` |
+| Scroll in direction | \`- scroll:\` | \`- scroll: DOWN\` |
+| Swipe | \`- swipe:\` | \`- swipe: LEFT\` |
+| Press back button | \`- pressKey: back\` | \`- pressKey: back\` |
+| Press enter/done | \`- pressKey: enter\` | \`- pressKey: enter\` |
+| Hide keyboard | \`- hideKeyboard\` | \`- hideKeyboard\` |
+| Wait (seconds) | \`- waitForAnimationToEnd\` | \`- waitForAnimationToEnd\` |
+| Long press | \`- longPressOn:\` | \`- longPressOn: "Element"\` |
+| Double tap | \`- doubleTapOn:\` | \`- doubleTapOn: "Element"\` |
+
+---
+
+### 5. WAITING FOR ELEMENTS
+
+When an element might take time to appear:
+
+\`\`\`yaml
+# Wait up to 10 seconds for element
+- extendedWaitUntil:
+    visible: "Element Text or ID"
+    timeout: 10000
+
+# Or use assertVisible with implicit wait
+- assertVisible: "Element"
+\`\`\`
+
+---
+
+### 6. CONDITIONAL CHECKS
+
+\`\`\`yaml
+# Run steps only if element is visible
+- runFlow:
+    when:
+      visible: "Optional Element"
+    commands:
+      - tapOn: "Optional Element"
+\`\`\`
+
+---
+
+### 7. GENERIC TEST PATTERNS
+
+#### Pattern A: Any Form Submission
+\`\`\`yaml
+appId: {APP_ID}
+---
+# Fill out form
+- clearState
+- launchApp
+
+# Navigate to form if needed
+- tapOn: "Menu or Tab Name"
+
+# Fill each field (ALWAYS tapOn first!)
+- tapOn: "Field 1 Label"
+- inputText: "Value 1"
+
+- tapOn: "Field 2 Label"
+- inputText: "Value 2"
+
+- tapOn: "Field 3 Label"
+- inputText: "Value 3"
+
+# Submit
+- tapOn: "Submit Button Text"
+
+# Verify success
+- assertVisible: "Success Indicator"
+\`\`\`
+
+#### Pattern B: Navigation Test
+\`\`\`yaml
+appId: {APP_ID}
+---
+- clearState
+- launchApp
+- tapOn: "Menu Item or Tab"
+- assertVisible: "Expected Screen Element"
+\`\`\`
+
+#### Pattern C: Search Test
+\`\`\`yaml
+appId: {APP_ID}
+---
+- clearState
+- launchApp
+- tapOn: "Search Field or Icon"
+- inputText: "search query"
+- pressKey: enter
+- assertVisible: "Expected Result"
+\`\`\`
+
+#### Pattern D: List Interaction
+\`\`\`yaml
+appId: {APP_ID}
+---
+- clearState
+- launchApp
+- scroll  # Scroll to find item
+- tapOn: "List Item Text"
+- assertVisible: "Detail View Element"
+\`\`\`
+
+#### Pattern E: Settings/Toggle Test
+\`\`\`yaml
+appId: {APP_ID}
+---
+- clearState
+- launchApp
+- tapOn: "Settings"
+- tapOn: "Toggle or Switch Label"
+- assertVisible: "Changed State Indicator"
+\`\`\`
+
+---
+
+### 8. ❌ NEVER DO THESE
+
+1. ❌ **NEVER** use \`inputText\` without \`tapOn\` first
+2. ❌ **NEVER** skip \`clearState\` and \`launchApp\`
+3. ❌ **NEVER** assume testIDs - use visible text if unsure
+4. ❌ **NEVER** use coordinates (x,y) unless absolutely necessary
+5. ❌ **NEVER** use hardcoded waits (\`sleep\`) - use \`extendedWaitUntil\`
+6. ❌ **NEVER** forget to hide keyboard after text input if it blocks elements
+
+---
+
+### 9. ✅ ALWAYS DO THESE
+
+1. ✅ **ALWAYS** start with \`clearState\` then \`launchApp\`
+2. ✅ **ALWAYS** use \`tapOn\` before \`inputText\`
+3. ✅ **ALWAYS** use visible text/labels when testIDs are unknown
+4. ✅ **ALWAYS** add \`assertVisible\` to verify expected results
+5. ✅ **ALWAYS** use waits for elements that may take time to load
+6. ✅ **ALWAYS** hide keyboard if it might block buttons: \`- hideKeyboard\`
+
+---
+
+### 10. DEBUGGING TIPS
+
+If a test fails:
+1. Add \`- assertVisible: "Expected Element"\` before the failing step
+2. Add waits with \`extendedWaitUntil\` for slow-loading elements
+3. Add \`- hideKeyboard\` before tapping buttons that might be covered
+4. Check if the element text matches exactly (case-sensitive)
+`;
+
+/**
+ * Get YAML generation context for a specific app
+ */
+export function getYamlGenerationContext(appId, appContext = null) {
+  let context = YAML_GENERATION_INSTRUCTIONS.replace(/{APP_ID}/g, appId);
+
+  // Add app-specific context if available
+  if (
+    appContext &&
+    appContext.elements &&
+    Object.keys(appContext.elements).length > 0
+  ) {
+    context += `\n---\n\n## APP-SPECIFIC ELEMENTS FOR ${appId}\n\n`;
+    context += `Use these EXACT element identifiers:\n\n`;
+    context += `| Element Name | Selector | Type |\n`;
+    context += `|--------------|----------|------|\n`;
+
+    for (const [name, element] of Object.entries(appContext.elements)) {
+      let selector = "";
+      if (element.testId) {
+        selector = `id: "${element.testId}"`;
+      } else if (element.accessibilityLabel) {
+        selector = `"${element.accessibilityLabel}"`;
+      } else if (element.text) {
+        selector = `"${element.text}"`;
+      }
+      const type = element.type || "unknown";
+      context += `| ${name} | \`${selector}\` | ${type} |\n`;
+    }
+    context += `\n`;
+  }
+
+  // Add screen information if available
+  if (
+    appContext &&
+    appContext.screens &&
+    Object.keys(appContext.screens).length > 0
+  ) {
+    context += `\n## SCREEN STRUCTURE\n\n`;
+    for (const [screenName, screen] of Object.entries(appContext.screens)) {
+      context += `### ${screenName}\n`;
+      if (screen.description) context += `${screen.description}\n\n`;
+      if (screen.elements && screen.elements.length > 0) {
+        context += `**Elements on this screen:** ${screen.elements.join(
+          ", "
+        )}\n\n`;
+      }
+    }
+  }
+
+  // Add example flows if available
+  if (appContext && appContext.flows && appContext.flows.length > 0) {
+    context += `\n## REFERENCE FLOWS (Copy these patterns)\n\n`;
+
+    // Show last 5 successful flows
+    const recentFlows = appContext.flows.slice(-5);
+    for (const flow of recentFlows) {
+      context += `### ${flow.name}\n`;
+      if (flow.description) context += `${flow.description}\n`;
+      context += `\`\`\`yaml\n${flow.yaml}\n\`\`\`\n\n`;
+    }
+  }
+
+  return context;
+}
+
+/**
+ * Common test patterns for standard scenarios
+ */
+export const TEST_PATTERNS = {
+  login: `# Login Test Pattern
+appId: {APP_ID}
+---
+# Login with credentials
+- clearState
+- launchApp
+- tapOn: "{username_field}"    # Username field - MUST tap first!
+- inputText: "{username}"
+- tapOn: "{password_field}"    # Password field - MUST tap first!
+- inputText: "{password}"
+- hideKeyboard                  # Hide keyboard before tapping button
+- tapOn: "{login_button}"
+- assertVisible: "{success_indicator}"
+`,
+
+  form: `# Generic Form Pattern
+appId: {APP_ID}
+---
+# Fill and submit any form
+- clearState
+- launchApp
+
+# For EACH field - always tapOn then inputText:
+- tapOn: "{field_1_label}"
+- inputText: "{field_1_value}"
+
+- tapOn: "{field_2_label}"
+- inputText: "{field_2_value}"
+
+- tapOn: "{field_3_label}"
+- inputText: "{field_3_value}"
+
+# Hide keyboard if needed
+- hideKeyboard
+
+# Submit
+- tapOn: "{submit_button}"
+- assertVisible: "{success_message}"
+`,
+
+  search: `# Search Pattern
+appId: {APP_ID}
+---
+- clearState
+- launchApp
+- tapOn: "{search_field}"
+- inputText: "{search_term}"
+- pressKey: enter
+- assertVisible: "{result_indicator}"
+`,
+
+  navigation: `# Navigation Pattern
+appId: {APP_ID}
+---
+- clearState
+- launchApp
+- tapOn: "{menu_or_tab}"
+- assertVisible: "{expected_screen_element}"
+`,
+
+  list: `# List Interaction Pattern
+appId: {APP_ID}
+---
+- clearState
+- launchApp
+- scroll  # Scroll to find item if needed
+- tapOn: "{list_item}"
+- assertVisible: "{detail_element}"
+`,
+
+  settings: `# Settings/Toggle Pattern
+appId: {APP_ID}
+---
+- clearState
+- launchApp
+- tapOn: "Settings"  # or settings icon
+- scroll  # Scroll to find setting if needed
+- tapOn: "{setting_name}"
+- assertVisible: "{changed_state}"
+`,
+
+  logout: `# Logout Pattern
+appId: {APP_ID}
+---
+- clearState
+- launchApp
+# Assuming already logged in
+- tapOn: "{menu_or_profile}"
+- scroll  # If logout is below fold
+- tapOn: "{logout_button}"
+- assertVisible: "{login_screen_element}"
+`,
+};
+
+/**
+ * Validate YAML structure for common issues
+ */
+export function validateYamlStructure(yamlContent) {
+  const issues = [];
+  const lines = yamlContent.split("\n");
+
+  let hasAppId = false;
+  let hasClearState = false;
+  let hasLaunchApp = false;
+  let lastWasTapOn = false;
+  let lastWasEraseText = false;
+  let lineNum = 0;
+
+  for (const line of lines) {
+    lineNum++;
+    const trimmed = line.trim();
+
+    // Skip comments and empty lines
+    if (trimmed.startsWith("#") || trimmed === "" || trimmed === "---") {
+      continue;
+    }
+
+    // Check for appId
+    if (trimmed.startsWith("appId:")) {
+      hasAppId = true;
+    }
+
+    // Check for clearState
+    if (trimmed === "- clearState") {
+      hasClearState = true;
+    }
+
+    // Check for launchApp
+    if (trimmed === "- launchApp") {
+      hasLaunchApp = true;
+    }
+
+    // Check for inputText without preceding tapOn or eraseText
+    if (
+      trimmed.startsWith("- inputText:") &&
+      !lastWasTapOn &&
+      !lastWasEraseText
+    ) {
+      issues.push({
+        line: lineNum,
+        severity: "error",
+        issue:
+          "inputText without preceding tapOn - TEXT WILL GO TO WRONG FIELD!",
+        suggestion: 'Add "- tapOn: \\"FieldName\\"" BEFORE this inputText',
+        code: trimmed,
+      });
+    }
+
+    // Track last action
+    lastWasTapOn = trimmed.startsWith("- tapOn:");
+    lastWasEraseText = trimmed.startsWith("- eraseText");
+  }
+
+  // Structure checks
+  if (!hasAppId) {
+    issues.push({
+      line: 1,
+      severity: "error",
+      issue: "Missing appId at the beginning",
+      suggestion: 'Add "appId: com.your.app" at the top of the YAML',
+    });
+  }
+
+  if (!hasClearState) {
+    issues.push({
+      line: 1,
+      severity: "warning",
+      issue: "Missing clearState - app may have stale data from previous runs",
+      suggestion: 'Add "- clearState" as the first command after ---',
+    });
+  }
+
+  if (!hasLaunchApp) {
+    issues.push({
+      line: 1,
+      severity: "error",
+      issue: "Missing launchApp - app will not start!",
+      suggestion: 'Add "- launchApp" after clearState',
+    });
+  }
+
+  const errors = issues.filter((i) => i.severity === "error");
+  const warnings = issues.filter((i) => i.severity === "warning");
+
+  return {
+    valid: errors.length === 0,
+    hasWarnings: warnings.length > 0,
+    errors,
+    warnings,
+    issues,
+    summary:
+      errors.length > 0
+        ? `❌ ${errors.length} error(s) found - YAML will likely fail!`
+        : warnings.length > 0
+        ? `⚠️ ${warnings.length} warning(s) - YAML may work but has issues`
+        : "✅ YAML structure looks valid",
+  };
+}
+
+/**
+ * Get UI hierarchy from device (for understanding current screen)
+ */
+export function getScreenAnalysisInstructions() {
+  return `
+## How to Analyze the Current Screen
+
+Before generating YAML, you should understand what's on the screen:
+
+1. **Ask the user for element names/labels visible on screen**
+2. **Use the take_screenshot tool** to capture current state
+3. **Check if app context is registered** with get_ai_context
+
+### Questions to Ask User:
+
+For a LOGIN screen:
+- "What is the label/placeholder of the username field?"
+- "What is the label/placeholder of the password field?"  
+- "What is the text on the login button?"
+
+For ANY form:
+- "What are the labels of each input field?"
+- "What is the text on the submit/save button?"
+- "What should appear after successful submission?"
+
+### If User Provides Element Info, Register It:
+
+Use register_elements to save for future use:
+\`\`\`
+{
+  "usernameField": { "text": "Username", "type": "textfield" },
+  "passwordField": { "text": "Password", "type": "textfield" },
+  "loginButton": { "text": "SIGN IN", "type": "button" }
+}
+\`\`\`
+
+This ensures consistent YAML generation next time!
+`;
+}
+
+export default {
+  YAML_GENERATION_INSTRUCTIONS,
+  getYamlGenerationContext,
+  TEST_PATTERNS,
+  validateYamlStructure,
+  getScreenAnalysisInstructions,
+};