@deriv-com/fe-mcp-servers 0.0.11 → 0.0.13

package/dist/maestro-ai/README.md

@@ -31,12 +31,30 @@ Add to your MCP client configuration (e.g., in Cursor settings):
       "command": "node",
       "args": [
         "/Users/user/.nvm/versions/node/v20.17.0/lib/node_modules/@deriv-com/fe-mcp-servers/dist/maestro-ai/mcp-server.js"
-      ]
+      ],
+      "env": {
+        "CLICKUP_API_TOKEN": "${env:CLICKUP_API_TOKEN}",
+        "CLICKUP_AC_SOURCE": "${env:CLICKUP_AC_SOURCE}"
+      }
     }
   }
 }
 ```
 
+### Environment Variables (Optional - for ClickUp Integration)
+
+Set these in your shell profile (`.bashrc`, `.zshrc`, etc.):
+
+```bash
+# ClickUp API token for fetching task acceptance criteria
+export CLICKUP_API_TOKEN="pk_your_api_token_here"
+
+# Source for acceptance criteria (default: "checklist:Acceptance Criteria")
+# Supports: checklist:Name, custom_field:Name, description
+# Multiple sources: "checklist:Acceptance Criteria,custom_field:AC,description"
+export CLICKUP_AC_SOURCE="checklist:Acceptance Criteria"
+```
+
 ## 🛠️ Development Structure
 
 ### Source Code (Development)
@@ -147,6 +165,37 @@ Returns common Maestro patterns with "when to use" guidance.
 - Pattern YAML code
 - Usage guidance for each pattern
 
+### `maestro_ensure_installed` Tool
+
+⚠️ **PREREQUISITE**: Call this FIRST before using `maestro_write_test` or `maestro_run_all_tests`!
+
+Checks if Maestro CLI is installed and automatically installs it if missing.
+
+**When to Call:**
+
+- ALWAYS before `maestro_write_test` (when execute=true)
+- ALWAYS before `maestro_run_all_tests`
+- When setting up a new development environment
+
+**Parameters:**
+
+- `autoInstall` (boolean, optional): Whether to automatically install if not found (default: true)
+- `forceReinstall` (boolean, optional): Whether to force reinstall even if already installed (default: false)
+
+**Returns:**
+
+- `installed`: boolean - Whether Maestro is now installed
+- `version`: string - Installed version (if available)
+- `wasInstalled`: boolean - Whether this call performed the installation
+- `message`: string - Status message
+- `details`: object - Additional info (path, install method)
+
+**Installation Method:**
+
+```bash
+curl -fsSL "https://get.maestro.mobile.dev" | bash
+```
+
 ### `maestro_analyze_changes` Tool
 
 Automatically analyzes actual git changes in a repository and provides test recommendations.
@@ -164,6 +213,224 @@ Automatically analyzes actual git changes in a repository and provides test reco
 - Interactive elements detected (onClick, Button, Form, etc.)
 - Suggested flow type and whether to create tests
 
+---
+
+## 🔗 ClickUp Integration Tools
+
+These tools enable test generation based on ClickUp task acceptance criteria.
+
+### `clickup_fetch_task` Tool
+
+Fetches a ClickUp task by URL to extract acceptance criteria for test generation.
+
+**ASK FIRST Pattern:**
+When called WITHOUT a `taskUrl`, this tool returns a prompt asking the user:
+
+> "Do you have a ClickUp task URL for this feature? Paste the URL to generate tests based on acceptance criteria, or type 'skip' to continue with git-based analysis only."
+
+**Parameters:**
+
+- `taskUrl` (string, optional): ClickUp task URL. If omitted, returns a prompt. Use "skip" to bypass.
+
+**URL Formats Supported:**
+
+- `https://app.clickup.com/t/abc123`
+- `https://app.clickup.com/t/86abc123`
+- `https://app.clickup.com/{workspace}/v/...?p=abc123`
+
+**Returns:**
+
+- If no URL: `{ needsInput: true, prompt: "..." }` - asking for URL
+- If URL provided: Full task object with checklists, custom fields, description
+- If "skip": `{ skipped: true }` - continue without ClickUp
+
+**Environment Variable Required:** `CLICKUP_API_TOKEN`
+
+### `validate_acceptance_criteria` Tool
+
+Parses and validates acceptance criteria from a ClickUp task for testability.
+
+**Parameters:**
+
+- `task` (object, required): ClickUp task object from `clickup_fetch_task`
+- `acSource` (string, optional): AC source specification (uses `CLICKUP_AC_SOURCE` env var if not provided)
+
+**AC Source Formats:**
+
+- `checklist:Checklist Name` - Parse from a specific checklist
+- `custom_field:Field Name` - Parse from a custom field
+- `description` - Parse from task description
+- Multiple: `"checklist:Acceptance Criteria,custom_field:AC,description"`
+
+**Returns:**
+
+- `validatedItems`: Array of AC items with testability analysis
+- `testableCount`: Number of items that can be tested via Maestro
+- `suggestedFlowTypes`: Recommended flow types based on AC content
+
+### `map_AC_to_UI` Tool
+
+⚠️ **HARD VALIDATION** - Maps acceptance criteria items to UI elements and **FAILS on mismatches**.
+
+This tool performs strict validation of AC against actual UI implementation. If the AC specifies one value but the UI has a different value, this tool will:
+
+1. **FAIL** (`success: false`)
+2. **Report** the exact mismatch
+3. **Block** test generation until resolved
+
+**Example:** If AC says "20 days option" but the UI has "Last 30 days", this is a **validation error** - the test should NOT be generated until the discrepancy is resolved.
+
+**Parameters:**
+
+- `acItems` (array, optional): Validated AC items. If omitted, uses git-only analysis (soft mode).
+- `repoPath` (string, optional): Path to git repository (default: current directory)
+- `changedFiles` (array, optional): List of changed files (auto-detected if omitted)
+
+**Returns:**
+
+- `success`: **false** if any AC doesn't match UI, **true** if all validated
+- `validationErrors`: Array of mismatches with AC expected vs UI actual
+- `validationWarnings`: Items that couldn't be fully verified
+- `actualUITexts`: Sample of UI text strings extracted from source code
+- `mappings`: Array of AC items with validation status
+- `matchedCount`: Number of fully validated items
+- `failedCount`: Number of items that failed validation
+- `recommendations`: Action items if validation fails
+
+**When Validation Fails (success: false):**
+
+🛑 **STOP THE WORKFLOW** - Output recommendation and END.
+
+```
+❌ Validation Failed - Cannot generate tests.
+
+Mismatches found:
+- "Yearly" - Not found in UI
+- "20 days" - Not found. Available: "Last 7 days", "Last 30 days", "Last 90 days"
+
+Recommendation: Update the ClickUp AC to match actual UI, OR fix the implementation.
+
+Workflow stopped. Re-run after resolving mismatches.
+```
+
+❌ **FORBIDDEN:** Continuing to generate tests, asking questions, or modifying tests to match UI.
+
+---
+
+## 🚀 Test Execution Tools
+
+### `maestro_write_test` Tool
+
+Writes a Maestro test YAML file to disk.
+
+**Parameters:**
+
+- `yaml` (string, required): The YAML content to write
+- `fileName` (string, required): Name of the file (e.g., "login_test.yaml")
+- `directory` (string, optional): Target directory (default: "maestro")
+- `basePath` (string, optional): Project base path (default: current directory)
+
+**Returns:**
+
+- `success`: boolean
+- `filePath`: Path where file was written
+- `message`: Status message
+
+### `maestro_execute_test` Tool
+
+Executes a single Maestro test file using the Maestro CLI.
+
+**Prerequisites:**
+
+- Maestro CLI must be installed (`curl -fsSL https://get.maestro.dev | bash`)
+- A device/simulator must be running
+
+**Parameters:**
+
+- `flowFile` (string, required): Path to the .yaml flow file
+- `deviceId` (string, optional): Target device ID
+- `env` (object, optional): Environment variables to pass
+- `timeout` (number, optional): Execution timeout in ms (default: 120000)
+
+**Returns:**
+
+- `success`: boolean
+- `output`: Test output/logs
+- `exitCode`: Process exit code
+- `duration`: Execution time in ms
+
+### `maestro_execute_tests_sequential` Tool
+
+Executes multiple Maestro test files sequentially with aggregated results.
+
+**Parameters:**
+
+- `flowFiles` (array, required): Array of flow file paths to execute
+- `deviceId` (string, optional): Target device ID
+- `env` (object, optional): Environment variables to pass
+- `stopOnFailure` (boolean, optional): Stop on first failure (default: false)
+
+**Returns:**
+
+- `success`: boolean (true if all tests passed)
+- `results`: Array of individual test results
+- `summary`: Aggregated statistics (passed, failed, skipped, duration)
+
+### `maestro_generate_and_run` Tool
+
+All-in-one workflow: Generate, write, and execute a Maestro test.
+
+**Parameters:**
+
+- `feature` (string, required): Feature being tested
+- `action` (string, required): Action being tested
+- `flowType` (string, required): Flow type (auth, form, sidebar, modal, navigation, extended)
+- `basePath` (string, optional): Project base path
+- `deviceId` (string, optional): Target device ID
+- `env` (object, optional): Environment variables
+- `execute` (boolean, optional): Execute after writing (default: true)
+- `changedElements` (array, optional): List of changed UI elements
+- `existingTests` (array, optional): List of existing related test files
+
+**Returns:**
+
+- `generation`: Generated template and guidelines
+- `write`: File write result
+- `execution`: Test execution results (if execute=true)
+- `summary`: Human-readable summary
+
+### `maestro_discover_tests` Tool
+
+Discovers all Maestro test files in a directory.
+
+**Parameters:**
+
+- `directory` (string, optional): Directory to search (default: "maestro")
+- `basePath` (string, optional): Project base path
+
+**Returns:**
+
+- `files`: Array of file paths
+- `count`: Number of files found
+
+### `maestro_run_all_tests` Tool
+
+Runs all Maestro tests in a directory sequentially.
+
+**Parameters:**
+
+- `directory` (string, optional): Directory containing tests (default: "maestro")
+- `basePath` (string, optional): Project base path
+- `deviceId` (string, optional): Target device ID
+- `env` (object, optional): Environment variables
+- `stopOnFailure` (boolean, optional): Stop on first failure (default: false)
+
+**Returns:**
+
+- `discovery`: List of discovered test files
+- `execution`: Results with pass/fail status for each test
+- `summary`: Aggregated statistics
+
 ## 🎯 Usage Examples
 
 Once configured in your MCP client, you can use the tools in your conversations:
@@ -237,6 +504,58 @@ env:
 3. **Quick Reference**: `maestro_cheat_sheet()`
 4. **Pattern Lookup**: `maestro_pattern(patternType: "login")`
 5. **UI Discovery**: `maestro_ui_inspection()`
+6. **Pre-check Installation**: `maestro_ensure_installed()` - Verifies Maestro CLI is ready
+
+### Test Execution Use Cases
+
+6. **Generate & Run Test**:
+
+```
+maestro_generate_and_run(
+  feature: "Login",
+  action: "OAuth flow",
+  flowType: "auth",
+  basePath: "/path/to/project"
+)
+```
+
+7. **Run All Tests in Directory**:
+
+```
+maestro_run_all_tests(
+  directory: "maestro",
+  basePath: "/path/to/project",
+  stopOnFailure: false
+)
+```
+
+8. **Execute Specific Tests Sequentially**:
+
+```
+maestro_execute_tests_sequential(
+  flowFiles: ["maestro/login.yaml", "maestro/checkout.yaml"],
+  env: { "BASE_URL": "https://staging.example.com" }
+)
+```
+
+9. **Write Test File Only (No Execution)**:
+
+```
+maestro_write_test(
+  yaml: "<generated yaml content>",
+  fileName: "user_settings_reset.yaml",
+  basePath: "/path/to/project"
+)
+```
+
+10. **Discover Available Tests**:
+
+```
+maestro_discover_tests(
+  directory: "maestro",
+  basePath: "/path/to/project"
+)
+```
 
 ## Flow Types
 
@@ -259,6 +578,133 @@ env:
 | `lastCommit` | Most recent commit             | `git diff HEAD~1`                |
 | `branch`     | Compare to base branch         | `git diff {baseBranch}...HEAD`   |
 
+## 🔄 Complete Workflow Examples
+
+### ⚠️ IMPORTANT: Standard Workflow Order
+
+When a user asks to "generate and run test cases" or use Maestro, follow this exact sequence:
+
+```bash
+# Step 1: ALWAYS check Maestro installation first!
+maestro_ensure_installed()
+
+# Step 2: ALWAYS ask for ClickUp URL (this is mandatory!)
+clickup_fetch_task()
+# This prompts the user: "Do you have a ClickUp task URL?"
+
+# Step 3+: Based on user response, continue workflow
+```
+
+### Workflow with ClickUp Integration (ASK FIRST)
+
+When user prompts: "use maestro-ai to generate and run tests"
+
+```bash
+# Step 1: ALWAYS check Maestro installation first!
+maestro_ensure_installed()
+
+# Step 2: ASK for ClickUp task URL
+clickup_fetch_task()
+# Returns: "Do you have a ClickUp task URL for this feature?
+#           Paste the URL or type 'skip' to continue."
+
+# If user provides URL (e.g., "https://app.clickup.com/t/abc123"):
+clickup_fetch_task(taskUrl: "https://app.clickup.com/t/abc123")
+# Extracts task ID, fetches task data
+
+# Step 3: Parse acceptance criteria
+validate_acceptance_criteria(task: <task_from_step_2>)
+# Returns: validatedItems with testability scores
+
+# Step 4: Analyze git changes
+maestro_analyze_changes(repoPath: ".")
+
+# Step 5: Map AC to UI elements
+map_AC_to_UI(
+  acItems: <validated_items>,
+  repoPath: ".",
+  changedFiles: <from_git_analysis>
+)
+
+# Step 6-7: Generate and write test
+maestro_generate_test(...)
+maestro_write_test(...)
+```
+
+### Workflow without ClickUp (Skip)
+
+```bash
+# Step 1: ALWAYS check Maestro installation first!
+maestro_ensure_installed()
+
+# Step 2: ASK for ClickUp task URL
+clickup_fetch_task()
+# User responds: "skip"
+
+# Step 3: Analyze git changes (normal flow)
+maestro_analyze_changes(repoPath: ".")
+
+# Step 4: Map based on git analysis only
+map_AC_to_UI(repoPath: ".")
+
+# Step 5-6: Generate and write test
+maestro_generate_test(...)
+maestro_write_test(...)
+```
+
+### End-to-End: Analyze Changes → Generate → Execute
+
+```bash
+# Step 0: Ensure Maestro is installed (REQUIRED)
+maestro_ensure_installed()
+
+# Step 1: Analyze git changes to see what needs testing
+maestro_analyze_changes(repoPath: "/path/to/project", changeType: "staged")
+
+# Output shows: Settings.tsx changed with onClick handler
+# Suggested flow type: form
+
+# Step 2: Generate and run the test in one call
+maestro_generate_and_run(
+  feature: "User Settings",
+  action: "Reset defaults",
+  flowType: "form",
+  basePath: "/path/to/project",
+  env: { "BASE_URL": "https://localhost:8443" }
+)
+
+# Output:
+# - File written to: /path/to/project/maestro/user_settings_reset_defaults.yaml
+# - Test executed: ✅ Passed (duration: 12.5s)
+```
+
+### Sequential Test Suite Execution
+
+```bash
+# Step 0: Ensure Maestro is installed (REQUIRED)
+maestro_ensure_installed()
+
+# Discover all tests
+maestro_discover_tests(basePath: "/path/to/project")
+# Output: Found 5 test files
+
+# Run all tests with stop-on-failure
+maestro_run_all_tests(
+  basePath: "/path/to/project",
+  stopOnFailure: true,
+  env: { "BASE_URL": "https://staging.example.com" }
+)
+
+# Output:
+# ✅ login_basic.yaml (8.2s)
+# ✅ user_settings_open.yaml (5.1s)
+# ❌ checkout_submit.yaml (12.3s) - FAILED
+# ⏭️ payment_confirm.yaml - SKIPPED
+# ⏭️ logout.yaml - SKIPPED
+#
+# Summary: 2 passed, 1 failed, 2 skipped
+```
+
 ## 📊 Examples
 
 ### Auth Flow Template
@@ -280,6 +726,9 @@ env:
 - tapOn:
     text: "Next"
     repeat: 3
+- tapOn:
+    text: "Got it"
+    repeat: 3
 - tapOn:
     text: "Log in"
 - inputText: ${USER_EMAIL}