@deriv-com/fe-mcp-servers 0.0.10 → 0.0.12

package/dist/maestro-ai/README.md

@@ -0,0 +1,610 @@
+# Maestro AI MCP Server
+
+A Model Context Protocol (MCP) server that provides automated Maestro test generation for web applications with best practices, templates, and guidelines baked in.
+
+## 🚀 Installation & Setup
+
+### Step 1: Install the Package
+
+```bash
+npm install -g @deriv-com/fe-mcp-servers
+```
+
+### Step 2: Get Configuration Path
+
+Get the exact path for your MCP configuration:
+
+```bash
+echo "$(npm root -g)/@deriv-com/fe-mcp-servers/dist/maestro-ai/mcp-server.js"
+```
+
+**Important**: Use the **bundled executable path** (without `src/`) for MCP configuration.
+
+### Step 3: Configure MCP Client
+
+Add to your MCP client configuration (e.g., in Cursor settings):
+
+```json
+{
+  "mcpServers": {
+    "maestro-ai": {
+      "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"
+      ]
+    }
+  }
+}
+```
+
+## 🛠️ Development Structure
+
+### Source Code (Development)
+
+```
+maestro-ai/
+├── src/
+│   ├── mcp-server.js    # Main MCP server implementation
+│   ├── mcp.js           # Core Maestro test generation functionality
+│   └── test-mcp.js      # Test suite
+└── README.md            # This documentation
+```
+
+### Built Output (Distribution)
+
+After building, the package creates:
+
+```
+dist/
+└── maestro-ai/
+    ├── mcp-server.js   # Bundled executable (all dependencies included)
+    └── README.md       # Documentation
+```
+
+## 🔧 Build Process
+
+The build process uses esbuild to:
+
+1. Bundle all dependencies into a single file
+2. Create a standalone executable
+3. Include proper Node.js shebang for direct execution
+4. No external dependency resolution needed at runtime
+
+## ⚡ Available Tools
+
+### `maestro_generate_test` Tool
+
+Generates comprehensive Maestro test YAML with templates, guidelines, and checklists.
+
+**Parameters:**
+
+- `feature` (string, required): The feature being tested (e.g., "User Settings")
+- `action` (string, required): The action being tested (e.g., "Reset defaults")
+- `flowType` (string, optional): Type of flow - `auth`, `sidebar`, `form`, `modal`, `navigation`, `extended`
+- `changedElements` (array, optional): List of UI elements that were changed
+- `existingTests` (array, optional): List of existing related test files
+
+**Returns:**
+
+- Generated YAML template with proper structure
+- Change verification checklist
+- Quality guidelines and suggested filename
+
+### `maestro_cheat_sheet` Tool
+
+Returns Maestro commands quick reference including selector strategy, waiting strategy, and file naming conventions.
+
+**Parameters:**
+
+- None required
+
+**Returns:**
+
+- Complete command reference table
+- Selector priority order (text → id → index → repeat)
+- Environment variable setup examples
+
+### `maestro_flow_template` Tool
+
+Returns a specific Maestro flow template by type.
+
+**Parameters:**
+
+- `flowType` (string, required): `auth`, `sidebar`, `form`, `modal`, `navigation`, `extended`
+- `name` (string, optional): Custom flow name
+- `baseUrl` (string, optional): Override default URL
+- `waitForElement` (string, optional): Initial element to wait for
+- `baseFlow` (string, optional): For extended type, base flow to extend
+
+**Returns:**
+
+- Ready-to-use YAML template for the specified flow type
+
+### `maestro_ui_inspection` Tool
+
+Returns UI inspection guidelines and checklist for proper element discovery.
+
+**Parameters:**
+
+- None required
+
+**Returns:**
+
+- MCP tool usage instructions
+- Source code grep patterns
+- ID vs data-testid distinction guide
+
+### `maestro_pattern` Tool
+
+Returns common Maestro patterns with "when to use" guidance.
+
+**Parameters:**
+
+- `patternType` (string, optional): `login`, `form`, `onboarding`, `slider`, `waitVisible`, `waitNotVisible`, `runFlow`
+
+**Returns:**
+
+- 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.
+
+**Parameters:**
+
+- `repoPath` (string, required): Path to the git repository
+- `changeType` (string, optional): `all`, `unstaged`, `staged`, `lastCommit`, `branch`
+- `baseBranch` (string, optional): Base branch for comparison (default: "main")
+- `fileFilter` (string, optional): Comma-separated patterns to filter files
+
+**Returns:**
+
+- List of changed files (unstaged, staged, UI files)
+- Interactive elements detected (onClick, Button, Form, etc.)
+- Suggested flow type and whether to create tests
+
+---
+
+## 🚀 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:
+
+### Generate Test for New Feature
+
+**Input:**
+
+```
+Use maestro_generate_test to create a test for the new Reset button in User Settings
+```
+
+**What happens:**
+The AI will receive a complete YAML template with guidelines for testing the feature.
+
+### Analyze Git Changes Before Testing
+
+**Input:**
+
+```
+maestro_analyze_changes(repoPath: "/path/to/project", changeType: "all")
+```
+
+**Expected Output:**
+
+```
+## 📁 Changed Files Summary
+### Unstaged Changes: 2 files
+- src/components/Settings/ResetButton.tsx
+- src/components/Settings/Settings.tsx
+
+## 🔍 Analysis
+### Should Create Test: ✅ Yes
+### Interactive Elements Found:
+- onClick
+- Button
+### Suggested Flow Type: form
+```
+
+### Get Flow Template
+
+**Input:**
+
+```
+maestro_flow_template(flowType: "auth", name: "Login - OAuth flow")
+```
+
+**Expected Output:**
+
+```yaml
+appId: web
+name: "Login - OAuth flow"
+url: ${BASE_URL}
+
+env:
+  BASE_URL: ${MAESTRO_BASE_URL || "https://localhost:8443"}
+  USER_EMAIL: ${MAESTRO_USER_EMAIL || "user@example.com"}
+---
+- launchApp
+- extendedWaitUntil:
+    visible: "Log in"
+    timeout: 20000
+- tapOn:
+    text: "Log in"
+```
+
+### Common Use Cases
+
+1. **New Feature Testing**: `maestro_generate_test(feature: "Checkout", action: "Submit order")`
+2. **Git Analysis**: `maestro_analyze_changes(repoPath: ".", changeType: "staged")`
+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
+
+| Flow Type    | Description                   | Includes Onboarding? |
+| ------------ | ----------------------------- | -------------------- |
+| `auth`       | Login, signup, password reset | Yes                  |
+| `sidebar`    | Sidebar panel interactions    | No                   |
+| `form`       | Form fill and submit          | No                   |
+| `modal`      | Modal/dialog interactions     | No                   |
+| `navigation` | Page-to-page navigation       | No                   |
+| `extended`   | Build on existing flow        | No                   |
+
+## Git Change Types
+
+| Type         | Description                    | Git Command                      |
+| ------------ | ------------------------------ | -------------------------------- |
+| `all`        | Unstaged + staged (default)    | `git diff` + `git diff --staged` |
+| `unstaged`   | Only working directory changes | `git diff`                       |
+| `staged`     | Only staged changes            | `git diff --staged`              |
+| `lastCommit` | Most recent commit             | `git diff HEAD~1`                |
+| `branch`     | Compare to base branch         | `git diff {baseBranch}...HEAD`   |
+
+## 🔄 Complete Workflow Example
+
+### ⚠️ IMPORTANT: Always Check Installation First!
+
+When a user asks to "generate and run test cases" or use Maestro, follow this order:
+
+```bash
+# Step 0: ALWAYS check Maestro installation first!
+maestro_ensure_installed()
+
+# If not installed, the tool will automatically install it via:
+# curl -fsSL "https://get.maestro.mobile.dev" | bash
+```
+
+### 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
+
+```yaml
+appId: web
+name: "Login - Basic authentication"
+url: ${BASE_URL}
+
+env:
+  BASE_URL: ${MAESTRO_BASE_URL || "https://localhost:8443"}
+  USER_EMAIL: ${MAESTRO_USER_EMAIL || "user@example.com"}
+  USER_PASSWORD: ${MAESTRO_USER_PASSWORD || "password"}
+---
+- launchApp
+- extendedWaitUntil:
+    visible: "Log in"
+    timeout: 20000
+- tapOn:
+    text: "Next"
+    repeat: 3
+- tapOn:
+    text: "Got it"
+    repeat: 3
+- tapOn:
+    text: "Log in"
+- inputText: ${USER_EMAIL}
+- tapOn:
+    text: "Log in"
+- extendedWaitUntil:
+    visible: "Dashboard"
+    timeout: 30000
+```
+
+### Form Flow Template
+
+```yaml
+appId: web
+name: "User Settings - Reset defaults"
+url: ${BASE_URL}
+
+env:
+  BASE_URL: ${MAESTRO_BASE_URL || "https://localhost:8443"}
+---
+- launchApp
+- extendedWaitUntil:
+    visible: "Settings"
+    timeout: 20000
+- tapOn:
+    text: "Reset to defaults"
+- extendedWaitUntil:
+    visible: "Settings reset successfully"
+    timeout: 10000
+```
+
+### Sidebar Flow Template
+
+```yaml
+appId: web
+name: "Positions - Open panel"
+url: ${BASE_URL}
+
+env:
+  BASE_URL: ${MAESTRO_BASE_URL || "https://localhost:8443"}
+---
+- launchApp
+- extendedWaitUntil:
+    visible: "Portfolio"
+    timeout: 20000
+- tapOn:
+    id: "dt_sidebar_positions"
+- extendedWaitUntil:
+    visible: "Open Positions"
+    timeout: 10000
+- assertVisible: "No open positions"
+```
+
+## 📚 Resources
+
+- [Maestro Docs](https://docs.maestro.dev/)
+- [Selectors Reference](https://docs.maestro.dev/api-reference/selectors)
+- [Commands Reference](https://docs.maestro.dev/api-reference/)
+- [Maestro MCP](https://docs.maestro.dev/getting-started/maestro-mcp)