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

package/dist/maestro-ai/README.md

@@ -0,0 +1,341 @@
+# 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_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
+
+## 🎯 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()`
+
+## 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`   |
+
+## 📊 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: "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)