mcp-maestro-mobile-ai 1.3.1 → 1.6.0

package/src/mcp-server/tools/contextTools.js

@@ -20,7 +20,26 @@ import {
   TEST_PATTERNS,
   validateYamlStructure,
   getScreenAnalysisInstructions,
+  getInteractionPatternHints,
+  getYamlGenerationRules,
+  getBestPractices,
+  PatternCategory,
 } from "../utils/yamlTemplate.js";
+import {
+  INTERACTION_PATTERNS,
+  getPatternsByCategory,
+  getPatternCategories,
+} from "../utils/knownIssues.js";
+import {
+  analyzePrompt,
+  generateClarificationQuestions,
+  generateWarnings,
+  CompletenessLevel,
+} from "../utils/promptAnalyzer.js";
+import {
+  generateYamlFromAnalysis,
+  formatGenerationResponse,
+} from "../utils/yamlGenerator.js";
 
 /**
  * Format result as MCP response
@@ -259,6 +278,9 @@ export async function getTestPattern(patternName) {
     list: TEST_PATTERNS.list,
     settings: TEST_PATTERNS.settings,
     logout: TEST_PATTERNS.logout,
+    dropdown: TEST_PATTERNS.dropdown,
+    flutter_login_with_dropdown: TEST_PATTERNS.flutter_login_with_dropdown,
+    flutter_multi_dropdown: TEST_PATTERNS.flutter_multi_dropdown,
   };
 
   const pattern = patterns[patternName?.toLowerCase()];
@@ -268,7 +290,7 @@ export async function getTestPattern(patternName) {
       success: false,
       error: `Unknown pattern: ${patternName}`,
       availablePatterns: Object.keys(patterns),
-      hint: "Use: login, form, search, navigation, list, settings, or logout",
+      hint: "Use: login, form, search, navigation, list, settings, logout, dropdown, flutter_login_with_dropdown, or flutter_multi_dropdown",
     });
   }
 
@@ -276,7 +298,7 @@ export async function getTestPattern(patternName) {
     success: true,
     pattern: patternName,
     template: pattern,
-    message: "Replace placeholders in {} with actual values. REMEMBER: Always use tapOn before inputText!",
+    message: "Replace placeholders in {} with actual values. REMEMBER: Always use tapOn before inputText! For dropdowns: hideKeyboard -> tapCurrentValue -> waitForAnimationToEnd -> tapDesiredValue",
   });
 }
 
@@ -299,6 +321,284 @@ export async function getScreenAnalysis() {
   });
 }
 
+/**
+ * Get interaction patterns for reliable YAML generation
+ * These patterns are framework-agnostic and work across all mobile apps.
+ */
+export async function getKnownIssues(category = null) {
+  let patterns = INTERACTION_PATTERNS;
+  
+  if (category) {
+    patterns = getPatternsByCategory(category);
+  }
+  
+  // Format patterns for display
+  const formattedPatterns = Object.entries(patterns).map(([key, pattern]) => ({
+    name: key,
+    category: pattern.category,
+    situation: pattern.situation,
+    strategy: pattern.strategy,
+    rationale: pattern.rationale,
+  }));
+  
+  return formatResponse({
+    success: true,
+    count: formattedPatterns.length,
+    patterns: formattedPatterns,
+    availableCategories: getPatternCategories(),
+    message: "These patterns are automatically included in YAML generation. Apply them to create reliable tests.",
+  });
+}
+
+/**
+ * Get interaction patterns by category
+ */
+export async function getPlatformRules(category) {
+  const validCategories = getPatternCategories();
+  
+  if (!category || !validCategories.includes(category)) {
+    return formatResponse({
+      success: false,
+      error: `Invalid category: ${category}`,
+      validCategories,
+      hint: "Use: keyboard_handling, element_interaction, timing_synchronization, input_handling, dropdown_picker, navigation, scroll_visibility, or fallback_strategies",
+    });
+  }
+  
+  const patterns = getPatternsByCategory(category);
+  
+  return formatResponse({
+    success: true,
+    category,
+    patterns: Object.entries(patterns).map(([key, p]) => ({
+      name: key,
+      situation: p.situation,
+      strategy: p.strategy,
+      yamlPattern: p.yamlPattern,
+    })),
+    message: "Apply these patterns for the specified interaction type.",
+  });
+}
+
+/**
+ * Get all YAML generation rules and best practices
+ */
+export async function getGenerationRules() {
+  const rules = getYamlGenerationRules();
+  const hints = getInteractionPatternHints();
+  const bestPractices = getBestPractices();
+  
+  return formatResponse({
+    success: true,
+    rules,
+    hints,
+    bestPractices,
+    message: "These rules are automatically applied during YAML generation. They are framework-agnostic and improve test reliability.",
+  });
+}
+
+/**
+ * Validate and analyze user prompt for YAML generation
+ * Uses Action-Element-Verification model for generic prompt analysis
+ * 
+ * @param {string} userPrompt - The user's test description
+ * @param {object} options - Options: appId, forceGenerate
+ * @returns {object} Analysis result with YAML or clarification questions
+ */
+export async function validateAndGenerate(userPrompt, options = {}) {
+  const { appId = null, forceGenerate = false } = options;
+  
+  if (!userPrompt || typeof userPrompt !== 'string' || userPrompt.trim().length < 5) {
+    return formatResponse({
+      success: false,
+      error: "Prompt is too short or empty",
+      hint: "Provide a description of the test you want to create. Example: 'Test login with username abc and password 1234'",
+    });
+  }
+  
+  // Step 1: Analyze the prompt
+  const analysis = analyzePrompt(userPrompt, { appId });
+  
+  // Step 2: Check completeness level
+  const { assessment, extracted } = analysis;
+  
+  // INSUFFICIENT: Cannot proceed without critical info
+  if (assessment.level === CompletenessLevel.INSUFFICIENT) {
+    const questions = generateClarificationQuestions(analysis);
+    const criticalQuestions = questions.filter(q => q.priority === 'critical');
+    
+    return formatResponse({
+      success: false,
+      status: 'insufficient',
+      message: 'Cannot generate YAML: missing required information',
+      understood: {
+        appContext: extracted.appContext,
+        detectedActions: extracted.actions.map(a => a.type),
+        detectedElements: extracted.elements.map(e => e.type),
+        valuesFound: Object.keys(extracted.values),
+      },
+      requiredInfo: criticalQuestions.map(q => ({
+        field: q.field,
+        question: q.question,
+      })),
+      hint: 'Please provide at least the app ID (package name) to continue.',
+    });
+  }
+  
+  // NEEDS_CLARIFICATION: Should ask, but can force generate
+  if (assessment.level === CompletenessLevel.NEEDS_CLARIFICATION && !forceGenerate) {
+    const questions = generateClarificationQuestions(analysis);
+    
+    return formatResponse({
+      success: false,
+      status: 'needs_clarification',
+      message: 'Additional information recommended for reliable test generation',
+      completenessScore: assessment.score,
+      understood: {
+        appId: extracted.appContext.appId,
+        appName: extracted.appContext.appName,
+        detectedActions: extracted.actions.map(a => ({ type: a.type, context: a.context })),
+        detectedElements: extracted.elements.map(e => ({ type: e.type, label: e.label })),
+        valuesFound: extracted.values,
+        verifications: extracted.verifications.map(v => ({ type: v.type, target: v.target })),
+      },
+      questions: questions.map(q => ({
+        priority: q.priority,
+        field: q.field,
+        question: q.question,
+        required: q.required,
+        default: q.default,
+      })),
+      canForceGenerate: true,
+      hint: 'Answer the questions for better accuracy, or use forceGenerate: true to proceed with assumptions.',
+    });
+  }
+  
+  // GENERATABLE: Can generate with assumptions (if forceGenerate is true)
+  // or ask for clarification
+  if (assessment.level === CompletenessLevel.GENERATABLE && !forceGenerate) {
+    const questions = generateClarificationQuestions(analysis);
+    const recommendedQuestions = questions.filter(q => q.priority === 'recommended');
+    
+    return formatResponse({
+      success: false,
+      status: 'can_improve',
+      message: 'Prompt understood, but additional details would improve test reliability',
+      completenessScore: assessment.score,
+      understood: {
+        appId: extracted.appContext.appId,
+        detectedActions: extracted.actions.map(a => ({ type: a.type, context: a.context })),
+        detectedElements: extracted.elements.map(e => ({ type: e.type, label: e.label })),
+        valuesFound: extracted.values,
+      },
+      recommendations: recommendedQuestions.map(q => ({
+        field: q.field,
+        question: q.question,
+        default: q.default,
+      })),
+      assumptionsIfForced: assessment.assumptions,
+      canForceGenerate: true,
+      hint: 'Provide additional details or use forceGenerate: true to generate with assumptions.',
+    });
+  }
+  
+  // COMPLETE or forceGenerate: Generate YAML
+  const result = generateYamlFromAnalysis(analysis, {
+    forceGenerate,
+    includeComments: true,
+    appId: appId || extracted.appContext.appId,
+  });
+  
+  if (!result.success) {
+    return formatResponse({
+      success: false,
+      error: result.error,
+      missing: result.missing,
+    });
+  }
+  
+  // Generate warnings if force generated
+  const warnings = forceGenerate && assessment.level !== CompletenessLevel.COMPLETE
+    ? generateWarnings(analysis)
+    : [];
+  
+  return formatResponse({
+    success: true,
+    status: result.forceGenerated ? 'generated_with_warnings' : 'generated',
+    message: result.forceGenerated
+      ? 'YAML generated with assumptions. Review and update placeholders before running.'
+      : 'YAML generated successfully.',
+    yaml: result.yaml,
+    completenessScore: result.completenessScore,
+    forceGenerated: result.forceGenerated || false,
+    warnings: [
+      ...result.warnings,
+      ...warnings.map(w => w.message),
+    ],
+    assumptions: result.assumptions,
+    analysis: {
+      detectedActions: extracted.actions.length,
+      detectedElements: extracted.elements.length,
+      valuesFound: Object.keys(extracted.values).length,
+      verifications: extracted.verifications.length,
+    },
+  });
+}
+
+/**
+ * Analyze prompt without generating YAML
+ * Useful for understanding what the system detected
+ */
+export async function analyzeTestPrompt(userPrompt, appId = null) {
+  if (!userPrompt || typeof userPrompt !== 'string') {
+    return formatResponse({
+      success: false,
+      error: "Invalid prompt",
+    });
+  }
+  
+  const analysis = analyzePrompt(userPrompt, { appId });
+  const { extracted, assessment } = analysis;
+  const questions = generateClarificationQuestions(analysis);
+  
+  return formatResponse({
+    success: true,
+    analysis: {
+      appContext: extracted.appContext,
+      actions: extracted.actions.map(a => ({
+        type: a.type,
+        keyword: a.keyword,
+        context: a.context,
+      })),
+      elements: extracted.elements.map(e => ({
+        type: e.type,
+        label: e.label,
+        keyword: e.keyword,
+      })),
+      values: extracted.values,
+      verifications: extracted.verifications.map(v => ({
+        type: v.type,
+        target: v.target,
+      })),
+      sequence: extracted.sequence,
+    },
+    assessment: {
+      level: assessment.level,
+      score: assessment.score,
+      issues: assessment.issues,
+      missing: assessment.missing,
+      assumptions: assessment.assumptions,
+      canForceGenerate: assessment.canForceGenerate,
+    },
+    clarificationQuestions: questions.map(q => ({
+      priority: q.priority,
+      field: q.field,
+      question: q.question,
+      required: q.required,
+    })),
+  });
+}
+
 export default {
   registerAppElements,
   registerAppScreen,
@@ -313,5 +613,12 @@ export default {
   validateYamlBeforeRun,
   getTestPattern,
   getScreenAnalysis,
+  // Known Issues Tools
+  getKnownIssues,
+  getPlatformRules,
+  getGenerationRules,
+  // Prompt Analysis & Generation
+  validateAndGenerate,
+  analyzeTestPrompt,
 };