chrometools-mcp 1.8.2 → 2.2.0

package/README.md

@@ -14,7 +14,7 @@ MCP server for Chrome automation using Puppeteer with persistent browser session
   - [Interaction Tools](#2-interaction-tools) - click, type, scrollTo
   - [Inspection Tools](#3-inspection-tools) - getElement, getComputedCss, getBoxModel, screenshot
   - [Advanced Tools](#4-advanced-tools) - executeScript, getConsoleLogs, listNetworkRequests, getNetworkRequest, filterNetworkRequests, hover, setStyles, setViewport, getViewport, navigateTo
-  - [Recorder Tools](#6-recorder-tools) ⭐ **NEW** - enableRecorder, executeScenario, listScenarios, searchScenarios, getScenarioInfo, deleteScenario, exportScenarioAsCode
+  - [Recorder Tools](#6-recorder-tools) ⭐ **NEW** - enableRecorder, executeScenario, listScenarios, searchScenarios, getScenarioInfo, deleteScenario, exportScenarioAsCode, generatePageObject
 - [Typical Workflow Example](#typical-workflow-example)
 - [Tool Usage Tips](#tool-usage-tips)
 - [Configuration](#configuration)
@@ -506,54 +506,74 @@ Extract detailed design specifications from Figma including text content, colors
 
 ### 6. Recorder Tools ⭐ NEW
 
-**Directory Management**: All recorder tools support an optional `directory` parameter to specify where scenarios are stored. If not provided, the directory is auto-detected using this cascade:
-1. `CLAUDE_PROJECT_DIR` environment variable (set by Claude Code)
-2. `PROJECT_DIR` environment variable (custom)
-3. Git repository root (detected via `git rev-parse --show-toplevel`)
-4. Current working directory (fallback)
+**URL-Based Storage (v2.1+)**: Scenarios are automatically organized by website domain in `~/.config/chrometools-mcp/projects/{domain}/scenarios/`.
 
-Once a directory is set (explicitly or auto-detected), it's remembered for the entire MCP server session.
+**Automatic Domain Detection**: Project ID is extracted from the URL where recording starts:
+- `https://www.google.com` → `google`
+- `https://dev.example.com:8080` → `example-8080`
+- `http://localhost:3000` → `localhost-3000`
+- `file:///test.html` → `local`
 
-**Example**:
-```javascript
-// Let it auto-detect (recommended)
-enableRecorder()
+**Domain Organization Rules**:
+1. Main domain only (subdomains stripped): `mail.google.com` → `google`
+2. Ports included for ALL domains: `example.com:8080` → `example-8080`
+3. Protocol ignored: `http` and `https` both → same project
 
-// Or specify explicitly
-enableRecorder({ directory: "/path/to/project" })
+**Global Scenario Access**: All tools (`listScenarios`, `searchScenarios`) return scenarios from **all projects**. Agent can filter by:
+- `projectId`: Domain-based identifier (e.g., "google", "localhost-3000")
+- `entryUrl`: URL where recording started
+- `exitUrl`: URL where recording ended
 
-// Later calls reuse the same directory automatically
-executeScenario({ name: "test" })  // Uses remembered directory
+**Example**:
+```javascript
+// Record scenario on google.com
+enableRecorder()  // Saves to ~/.config/chrometools-mcp/projects/google/scenarios/
+
+// List ALL scenarios from all websites
+listScenarios()
+// Returns: [
+//   { name: "search", projectId: "google", entryUrl: "https://google.com" },
+//   { name: "login", projectId: "localhost-3000", entryUrl: "http://localhost:3000" }
+// ]
+
+// Agent filters by projectId or URL
+scenarios.filter(s => s.projectId === "google")
+scenarios.filter(s => s.entryUrl.includes("localhost"))
+
+// Execute scenario (searches all projects automatically)
+executeScenario({ name: "login" })  // Finds scenario in any project
 ```
 
 ---
 
 #### enableRecorder
-Inject visual recorder UI widget into the current page.
-- **Parameters**:
-  - `directory` (optional): Directory to save scenarios (auto-detected if not provided)
+Inject visual recorder UI widget into the current page. Scenarios are automatically saved to `~/.config/chrometools-mcp/projects/{domain}/scenarios/` based on the website URL.
+- **Parameters**: None
 - **Use case**: Start recording user interactions visually
-- **Returns**: Success status
+- **Returns**: Success status with storage location
 - **Features**:
   - Floating widget with compact mode (minimize to 50x50px)
   - Visual recording indicator (red pulsing border)
   - Start/Pause/Stop/Stop & Save/Clear controls
   - Real-time action list display
   - Metadata fields (name, description, tags)
+  - Automatic domain-based project detection from URL
 
 #### executeScenario
-Execute a previously recorded scenario by name.
+Execute a previously recorded scenario by name. Searches all projects automatically via global index.
 - **Parameters**:
   - `name` (required): Scenario name
+  - `projectId` (optional): Project ID (domain) to disambiguate when multiple scenarios have the same name. Examples: `"google"`, `"localhost-3000"`
   - `parameters` (optional): Runtime parameters (e.g., { email: "user@test.com" })
   - `executeDependencies` (optional): Execute dependencies before running scenario (default: true)
-  - `directory` (optional): Directory where scenarios are stored (auto-detected if not provided)
-- **Use case**: Run automated test scenarios
+- **Use case**: Run automated test scenarios across projects
 - **Returns**: Execution result with success/failure status
 - **Features**:
   - Automatic dependency resolution (enabled by default)
+  - Cross-project dependency support
   - Secret parameter injection
   - Fallback selector retry logic
+  - Name collision detection with helpful error messages
 - **Example**:
   ```javascript
   // Execute with dependencies (default)
@@ -561,56 +581,96 @@ Execute a previously recorded scenario by name.
 
   // Execute without dependencies
   executeScenario({ name: "create_post", executeDependencies: false })
+
+  // Disambiguate when multiple scenarios have same name
+  executeScenario({ name: "login", projectId: "google" })
+  executeScenario({ name: "login", projectId: "localhost-3000" })
+  ```
+
+- **Name Collision Handling**:
+  If multiple scenarios with the same name exist across different projects, you'll get an error:
+  ```json
+  {
+    "success": false,
+    "error": "Multiple scenarios named 'login' found. Please specify projectId.",
+    "availableProjectIds": ["google", "localhost-3000"],
+    "hint": "Use: executeScenario({ name: \"login\", projectId: \"one-of-the-above\" })"
+  }
   ```
 
 #### listScenarios
-Get all available scenarios with metadata.
-- **Parameters**:
-  - `directory` (optional): Directory where scenarios are stored (auto-detected if not provided)
-- **Use case**: Browse recorded scenarios
-- **Returns**: Array of scenarios with names, descriptions, tags, timestamps
+Get all available scenarios with metadata from **all websites**. Agent can filter by `projectId`, `entryUrl`, or `exitUrl`.
+- **Parameters**: None
+- **Use case**: Browse recorded scenarios across all websites
+- **Returns**: Array of scenarios with names, descriptions, tags, timestamps, `projectId`, `entryUrl`, `exitUrl`
+- **Example**:
+  ```javascript
+  // List all scenarios from all websites
+  const scenarios = await listScenarios()
+
+  // Agent filters by projectId
+  const googleScenarios = scenarios.filter(s => s.projectId === "google")
+
+  // Agent filters by URL
+  const localhostScenarios = scenarios.filter(s => s.entryUrl.includes("localhost"))
+  ```
 
 #### searchScenarios
-Search scenarios by text or tags.
+Search scenarios by text or tags across **all websites**. Agent can further filter results by `projectId` or URLs.
 - **Parameters**:
   - `text` (optional): Search in name/description
   - `tags` (optional): Array of tags to filter
-  - `directory` (optional): Directory where scenarios are stored (auto-detected if not provided)
-- **Use case**: Find specific scenarios
-- **Returns**: Matching scenarios
+- **Use case**: Find specific scenarios across all websites
+- **Returns**: Matching scenarios with `projectId`, `entryUrl`, `exitUrl` metadata
+- **Example**:
+  ```javascript
+  // Search across all websites
+  const results = await searchScenarios({ text: "login" })
+
+  // Search by tags
+  const authScenarios = await searchScenarios({ tags: ["auth"] })
+
+  // Agent filters results by domain
+  const googleLogins = results.filter(s => s.projectId === "google")
+  ```
 
 #### getScenarioInfo
-Get detailed information about a scenario.
+Get detailed information about a scenario. Searches all projects automatically.
 - **Parameters**:
   - `name` (required): Scenario name
   - `includeSecrets` (optional): Include secret values (default: false)
-  - `directory` (optional): Directory where scenarios are stored (auto-detected if not provided)
 - **Use case**: Inspect scenario actions and dependencies
-- **Returns**: Full scenario details (actions, metadata, dependencies)
+- **Returns**: Full scenario details (actions, metadata, dependencies, project info)
 
 #### deleteScenario
-Delete a scenario and its associated secrets.
+Delete a scenario and its associated secrets. Searches all projects to find the scenario.
 - **Parameters**:
   - `name` (required): Scenario name
-  - `directory` (optional): Directory where scenarios are stored (auto-detected if not provided)
 - **Use case**: Clean up unused scenarios
 - **Returns**: Success confirmation
 
 #### exportScenarioAsCode ⭐ **NEW**
-Export recorded scenario as executable test code for various frameworks. Automatically cleans unstable selectors (CSS Modules, styled-components, Emotion).
+Export recorded scenario as executable test code for various frameworks. Automatically cleans unstable selectors (CSS Modules, styled-components, Emotion). Optionally generates Page Object class for the page. Can append tests to existing files. Searches all projects to find the scenario.
 
 - **Parameters**:
   - `scenarioName` (required): Name of scenario to export
   - `language` (required): Target framework - `"playwright-typescript"`, `"playwright-python"`, `"selenium-python"`, `"selenium-java"`
   - `cleanSelectors` (optional): Remove unstable CSS classes (default: true)
   - `includeComments` (optional): Include descriptive comments (default: true)
-  - `directory` (optional): Directory where scenarios are stored (auto-detected if not provided)
+  - `generatePageObject` (optional): Also generate Page Object class for the page (default: false)
+  - `pageObjectClassName` (optional): Custom Page Object class name (auto-generated if not provided)
+  - `appendToFile` (optional): Path to existing test file to append to (enables **append mode**) ⭐ **NEW**
+  - `testName` (optional): Override test name (default: from scenario name) ⭐ **NEW**
+  - `insertPosition` (optional): Where to insert: `'end'` (default), `'before'`, `'after'` ⭐ **NEW**
+  - `referenceTestName` (optional): Reference test name for before/after insertion ⭐ **NEW**
 
-- **Use case**: Convert recorded scenarios into maintainable test code
+- **Use case**: Convert recorded scenarios into maintainable test code with optional Page Objects, or append to existing test suites
 
-- **Returns**: Generated test code as string
+- **Returns**:
+  - **Without `appendToFile`**: Test code as string (or JSON with Page Object)
+  - **With `appendToFile`**: JSON with `{success, mode: "append", file, testName, message}`
 
-- **Example**:
+- **Example 1 - Test only** (default behavior):
   ```javascript
   // Export scenario as Playwright TypeScript
   exportScenarioAsCode({
@@ -630,6 +690,69 @@ Export recorded scenario as executable test code for various frameworks. Automat
   // });
   ```
 
+- **Example 2 - Test + Page Object** ⭐ **NEW**:
+  ```javascript
+  // Export with Page Object class
+  exportScenarioAsCode({
+    scenarioName: "login_test",
+    language: "playwright-typescript",
+    generatePageObject: true,
+    pageObjectClassName: "LoginPage"
+  })
+
+  // Returns JSON with both files:
+  {
+    "success": true,
+    "testCode": "import { test } from '@playwright/test';\nimport { LoginPage } from './LoginPage';\n\ntest('login_test', async ({ page }) => {\n  const loginPage = new LoginPage(page);\n  await loginPage.goto();\n  await loginPage.fillEmailInput('user@test.com');\n  await loginPage.clickLoginButton();\n});",
+    "pageObjectCode": "import { Page, Locator } from '@playwright/test';\n\nexport class LoginPage {\n  readonly page: Page;\n  readonly emailInput: Locator;\n  readonly loginButton: Locator;\n  \n  constructor(page: Page) {\n    this.page = page;\n    this.emailInput = page.locator('#email');\n    this.loginButton = page.locator('button[type=\"submit\"]');\n  }\n  \n  async goto() {\n    await this.page.goto('https://example.com/login');\n  }\n  \n  async fillEmailInput(text: string) {\n    await this.emailInput.fill(text);\n  }\n  \n  async clickLoginButton() {\n    await this.loginButton.click();\n  }\n}",
+    "pageObjectClassName": "LoginPage",
+    "framework": "playwright-typescript",
+    "elementCount": 12
+  }
+  ```
+
+- **Example 3 - Append Mode** ⭐ **NEW**:
+  ```javascript
+  // Append test to end of existing file
+  exportScenarioAsCode({
+    scenarioName: "new_feature_test",
+    language: "playwright-typescript",
+    appendToFile: "./tests/features.spec.ts"
+  })
+
+  // Returns:
+  {
+    "success": true,
+    "mode": "append",
+    "file": "./tests/features.spec.ts",
+    "testName": "new_feature_test",
+    "insertPosition": "end",
+    "message": "Test 'new_feature_test' successfully appended to ./tests/features.spec.ts"
+  }
+  ```
+
+- **Example 4 - Append with Position Control** ⭐ **NEW**:
+  ```javascript
+  // Insert test before specific test
+  exportScenarioAsCode({
+    scenarioName: "setup_test",
+    language: "selenium-python",
+    appendToFile: "./tests/test_suite.py",
+    insertPosition: "before",
+    referenceTestName: "main_test",
+    testName: "test_setup_data"  // Override name
+  })
+
+  // Or insert after specific test
+  exportScenarioAsCode({
+    scenarioName: "cleanup",
+    language: "playwright-python",
+    appendToFile: "./tests/test_flow.py",
+    insertPosition: "after",
+    referenceTestName: "test_main_flow"
+  })
+  ```
+
 - **Selector Cleaning**: Automatically removes unstable patterns:
   - CSS Modules: `Button_primary__2x3yZ` → removed
   - Styled-components: `sc-AbCdEf-0` → removed
@@ -637,6 +760,61 @@ Export recorded scenario as executable test code for various frameworks. Automat
   - Hash suffixes: `component_a1b2c3d` → removed
   - Prefers stable selectors: `data-testid`, `role`, `aria-label`, semantic attributes
 
+#### generatePageObject ⭐ **NEW**
+Generate Page Object Model (POM) class from current page structure. Analyzes page, extracts interactive elements, and generates framework-specific code with smart naming and helper methods.
+
+- **Parameters**:
+  - `className` (optional): Page Object class name (auto-generated from page title/URL if not provided)
+  - `framework` (optional): Target framework - `"playwright-typescript"` (default), `"playwright-python"`, `"selenium-python"`, `"selenium-java"`
+  - `includeComments` (optional): Include descriptive comments (default: true)
+  - `groupElements` (optional): Group elements by page sections (default: true)
+
+- **Features**:
+  - **Smart Selector Generation**: Prioritizes id > name > data-testid > unique class > CSS path
+  - **Intelligent Naming**: Auto-generates element names from labels, placeholders, text, attributes
+  - **Section Grouping**: Groups elements by semantic sections (header, nav, form, footer, main, etc.)
+  - **Helper Methods**: Auto-generates fill() and click() methods for common actions
+  - **Multi-Framework**: Supports Playwright (TS/Python) and Selenium (Python/Java)
+
+- **Use cases**:
+  - Generate POM classes for test automation
+  - Create maintainable test structure from existing pages
+  - Bootstrap test framework setup quickly
+  - Extract page structure for documentation
+
+- **Returns**: Page Object code with metadata (className, url, title, elementCount, framework)
+
+- **Example**:
+  ```javascript
+  // 1. Navigate to page
+  openBrowser({ url: "https://example.com/login" })
+
+  // 2. Generate Page Object
+  generatePageObject({
+    className: "LoginPage",
+    framework: "playwright-typescript",
+    includeComments: true,
+    groupElements: true
+  })
+
+  // Returns:
+  {
+    "success": true,
+    "className": "LoginPage",
+    "url": "https://example.com/login",
+    "title": "Login - Example Site",
+    "elementCount": 12,
+    "framework": "playwright-typescript",
+    "code": "import { Page, Locator } from '@playwright/test';\n\nexport class LoginPage {\n  readonly page: Page;\n  \n  /** Email input field */\n  readonly emailInput: Locator;\n  /** Password input field */\n  readonly passwordInput: Locator;\n  /** Login button */\n  readonly loginButton: Locator;\n  \n  constructor(page: Page) {\n    this.page = page;\n    this.emailInput = page.locator('#email');\n    this.passwordInput = page.locator('#password');\n    this.loginButton = page.locator('button[type=\"submit\"]');\n  }\n  \n  async goto() {\n    await this.page.goto('https://example.com/login');\n  }\n  \n  async fillEmailInput(text: string) {\n    await this.emailInput.fill(text);\n  }\n  \n  async fillPasswordInput(text: string) {\n    await this.passwordInput.fill(text);\n  }\n  \n  async clickLoginButton() {\n    await this.loginButton.click();\n  }\n}"
+  }
+  ```
+
+- **Supported Frameworks**:
+  - `playwright-typescript`: Playwright with TypeScript (locators, async/await, Page Object pattern)
+  - `playwright-python`: Playwright with Python (sync API, snake_case naming)
+  - `selenium-python`: Selenium with Python (WebDriver, explicit waits, By locators)
+  - `selenium-java`: Selenium with Java (WebDriver, Page Factory compatible)
+
 ---
 
 ## Typical Workflow Example

package/browser/browser-manager.js

@@ -0,0 +1,206 @@
+/**
+ * browser/browser-manager.js
+ *
+ * Browser lifecycle management
+ */
+
+import puppeteer from 'puppeteer';
+import { spawn } from 'child_process';
+import http from 'http';
+import { getChromePath, getTempDir, isWSL, CHROME_DEBUG_PORT } from '../utils/platform-utils.js';
+
+// Global browser instance (persists between requests)
+let browserPromise = null;
+let chromeProcess = null;
+
+/**
+ * Debug log helper (only logs to stderr when DEBUG=1)
+ * @param {...any} args - Arguments to log
+ */
+function debugLog(...args) {
+  if (process.env.DEBUG === '1') {
+    console.error('[browser-manager]', ...args);
+  }
+}
+
+/**
+ * Get WebSocket endpoint from Chrome remote debugging
+ * @param {number} port - Chrome debugging port
+ * @param {number} maxRetries - Maximum retry attempts
+ * @returns {Promise<string>} - WebSocket debugger URL
+ */
+async function getChromeWebSocketEndpoint(port = CHROME_DEBUG_PORT, maxRetries = 10) {
+  for (let i = 0; i < maxRetries; i++) {
+    try {
+      const response = await new Promise((resolve, reject) => {
+        const req = http.get(`http://localhost:${port}/json/version`, (res) => {
+          let data = '';
+          res.on('data', chunk => data += chunk);
+          res.on('end', () => resolve(data));
+        });
+        req.on('error', reject);
+        req.setTimeout(1000);
+      });
+
+      const info = JSON.parse(response);
+      if (info.webSocketDebuggerUrl) {
+        return info.webSocketDebuggerUrl;
+      }
+    } catch (err) {
+      // Chrome might not be ready yet, wait and retry
+      await new Promise(resolve => setTimeout(resolve, 500));
+    }
+  }
+  throw new Error('Could not get Chrome WebSocket endpoint after multiple retries');
+}
+
+/**
+ * Initialize browser (singleton)
+ * @returns {Promise<Browser>} - Puppeteer browser instance
+ */
+export async function getBrowser() {
+  // Check if we have a cached browser and if it's still connected
+  if (browserPromise) {
+    try {
+      const cachedBrowser = await browserPromise;
+      if (cachedBrowser && cachedBrowser.isConnected()) {
+        return cachedBrowser;
+      }
+      // Browser disconnected, reset the promise
+      debugLog("Browser disconnected, will reconnect...");
+      browserPromise = null;
+    } catch (error) {
+      debugLog("Error checking cached browser:", error.message);
+      browserPromise = null;
+    }
+  }
+
+  if (!browserPromise) {
+    browserPromise = (async () => {
+      try {
+        let browser;
+        let endpoint;
+
+        // Try to connect to existing Chrome with remote debugging
+        try {
+          endpoint = await getChromeWebSocketEndpoint(CHROME_DEBUG_PORT, 2);
+          browser = await puppeteer.connect({
+            browserWSEndpoint: endpoint,
+            defaultViewport: null,
+          });
+          debugLog("Connected to existing Chrome instance");
+          debugLog("WebSocket endpoint:", endpoint);
+
+          // Set up disconnect handler to reset browserPromise
+          browser.on('disconnected', () => {
+            debugLog("Browser disconnected");
+            browserPromise = null;
+          });
+
+          return browser;
+        } catch (connectError) {
+          debugLog("No existing Chrome found, launching new instance...");
+        }
+
+        // Launch new Chrome with remote debugging enabled
+        const chromePath = getChromePath();
+        const userDataDir = `${getTempDir()}/chrome-mcp-profile`;
+
+        debugLog("Chrome path:", chromePath);
+        debugLog("User data dir:", userDataDir);
+
+        chromeProcess = spawn(chromePath, [
+          `--remote-debugging-port=${CHROME_DEBUG_PORT}`,
+          '--no-first-run',
+          '--no-default-browser-check',
+          `--user-data-dir=${userDataDir}`,
+        ], {
+          detached: true,
+          stdio: 'ignore',
+        });
+
+        chromeProcess.unref(); // Allow Node to exit even if Chrome is running
+
+        debugLog("Chrome launched with remote debugging on port", CHROME_DEBUG_PORT);
+
+        // Wait for Chrome to start and get the endpoint
+        endpoint = await getChromeWebSocketEndpoint(CHROME_DEBUG_PORT, 20);
+
+        // Connect to the Chrome instance
+        browser = await puppeteer.connect({
+          browserWSEndpoint: endpoint,
+          defaultViewport: null,
+        });
+
+        debugLog("Connected to Chrome instance");
+        debugLog("WebSocket endpoint:", endpoint);
+
+        // Set up disconnect handler to reset browserPromise
+        browser.on('disconnected', () => {
+          debugLog("Browser disconnected");
+          browserPromise = null;
+        });
+
+        return browser;
+      } catch (error) {
+        // Check if it's a display-related error in WSL
+        if (isWSL && (
+          error.message.includes('DISPLAY') ||
+          error.message.includes('connect ECONNREFUSED') ||
+          error.message.includes('cannot open display')
+        )) {
+          const helpMessage = `
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+❌ WSL X Server Error Detected
+
+You are running in WSL environment with headless:false mode.
+This requires an X server to display the browser GUI.
+
+🔧 Solution:
+   1. Start X server on Windows (e.g., VcXsrv, X410)
+   2. Set DISPLAY in your MCP config:
+
+      {
+        "mcpServers": {
+          "chrometools": {
+            "env": {
+              "DISPLAY": "172.25.96.1:0"
+            }
+          }
+        }
+      }
+
+📚 For detailed setup instructions, see:
+   WSL_SETUP.md in chrometools-mcp package
+
+💡 Alternative: Run in headless mode (modify index.js)
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+`;
+          console.error(helpMessage);
+          throw new Error(`WSL X Server not available. ${error.message}\n\nSee above for setup instructions.`);
+        }
+
+        // Re-throw other errors as-is
+        throw error;
+      }
+    })();
+  }
+
+  return await browserPromise;
+}
+
+/**
+ * Close browser and cleanup
+ * @returns {Promise<void>}
+ */
+export async function closeBrowser() {
+  if (browserPromise) {
+    try {
+      const browser = await browserPromise;
+      await browser.close();
+    } catch (error) {
+      debugLog("Error closing browser:", error.message);
+    }
+    browserPromise = null;
+  }
+}