chrometools-mcp 1.7.0 → 1.8.2

package/CHANGELOG.md

@@ -2,6 +2,117 @@
 
 All notable changes to this project will be documented in this file.
 
+## [1.8.2] - 2025-12-19
+
+### Fixed
+- **Code Generator Bugs** - Fixed multiple issues in test code generators
+  - **Python generators**: Fixed comment syntax - now use `#` instead of `//`
+  - **Python generators**: Moved `import re` to top of file instead of inline
+  - **Java generator**: Fixed variable name conflicts - now uses unique names (`typeElement`, `hoverElement`, etc.) instead of reusing `element`
+  - **Java generator**: Added missing imports (`JavascriptExecutor`, `Select`)
+  - **All generators**: Implemented language-specific comment generation via `generateComment()` method
+  - Location: `utils/code-generators/code-generator-base.js`, `playwright-python.js`, `selenium-python.js`, `selenium-java.js`
+
+## [1.8.1] - 2025-12-19
+
+### Added
+- **Smart Project Directory Detection** - Scenarios now automatically save to the correct project directory
+  - Auto-detection cascade: `CLAUDE_PROJECT_DIR` env var → `PROJECT_DIR` env var → Git root → current working directory
+  - Optional `directory` parameter on all recorder tools (`enableRecorder`, `executeScenario`, `listScenarios`, `searchScenarios`, `getScenarioInfo`, `deleteScenario`, `exportScenarioAsCode`)
+  - Session memory: once directory is set (explicitly or auto-detected), it's remembered for the entire MCP server session
+  - Solves issue where scenarios were saved to unpredictable locations based on where MCP process was launched
+  - Location: `utils/project-detector.js`, `index.js:97-115`
+
+### Changed
+- **All recorder storage functions now accept `baseDir` parameter** - Breaking change for direct API usage
+  - Updated: `saveScenario()`, `loadScenario()`, `listScenarios()`, `searchScenarios()`, `deleteScenario()`, `loadIndex()`, and all other storage functions
+  - MCP tool users: no breaking changes, just new optional `directory` parameter
+  - Location: `recorder/scenario-storage.js`, `recorder/scenario-executor.js`, `recorder/recorder-script.js`
+
+## [1.8.0] - 2025-12-19
+
+### Added
+- **Test Code Generation** - New MCP tool `exportScenarioAsCode` for generating executable test code from recorded scenarios
+  - Supports 4 test frameworks: Playwright (TypeScript/Python), Selenium (Python/Java)
+  - Automatic selector cleaning - removes unstable CSS classes (CSS Modules, styled-components, Emotion, hashed classes)
+  - Generates clean, readable test code with comments
+  - Smart selector stability analysis with pattern-based detection
+  - Fallback selector selection - chooses most stable selector from fallbacks
+  - Location: `utils/code-generators/`, `utils/selector-cleaner.js`
+
+  **Unstable patterns detected:**
+  - CSS Modules: `Button_primary__2x3yZ`
+  - Styled-components: `sc-AbCdEf-0`
+  - Emotion: `css-1a2b3c4d`
+  - Hash suffixes: `component_a1b2c3d`
+  - Random hashes: `_1a2b3c4d`
+
+  **Usage:**
+  ```javascript
+  exportScenarioAsCode('checkout', {
+    language: 'playwright-typescript',
+    cleanSelectors: true,
+    includeComments: true
+  })
+  ```
+
+## [1.7.4] - 2025-12-19
+
+### Changed
+- **executeScenario auto-opens browser** - No longer throws error when no page is open
+  - Automatically opens browser at scenario's `entryUrl` if no page is currently open
+  - Eliminates need to manually call `openBrowser` before executing scenarios
+  - Improves user experience by treating browser opening as a side effect
+  - Falls back gracefully: shows error only if scenario has no `entryUrl`
+  - Location: `index.js:3417-3469`
+
+## [1.7.3] - 2025-12-19
+
+### Fixed
+- **Fixed CSS selector generation crash** - `analyzePage` now handles attribute values with special characters
+  - Added `isSafeSelectorValue()` function to validate attribute values before using in selectors
+  - Filters out attributes containing problematic characters: `["'\\[]{}()]`
+  - Added try-catch blocks to prevent selector syntax errors
+  - Example: `button[data-counter="["b"]"]` (invalid) is now skipped
+  - Location: `element-finder-utils.js:302-360`
+
+### Improved
+- **Recorder now skips hidden elements** - Prevents recording actions on invisible elements
+  - Added `isElementVisible()` function to check element visibility before recording
+  - Checks: offsetWidth/Height, display, visibility, opacity
+  - Applies to all event types: click, type, select, upload, hover, drag
+  - Prevents scenarios with duplicate/invisible element actions (e.g., Yandex search with hidden input)
+  - Console logs when skipping hidden elements for debugging
+  - Location: `recorder/recorder-script.js:1173-1188`
+
+## [1.7.2] - 2025-12-16
+
+### Added
+- **Figma API Token Setup documentation** - Added comprehensive guide on how to obtain and configure Figma Personal Access Token
+  - Step-by-step instructions for getting token from Figma account settings
+  - Configuration examples for both Claude Desktop and Claude Code
+  - Environment variable setup (`FIGMA_TOKEN`)
+  - Note about alternative parameter-based token passing
+
+## [1.7.1] - 2025-12-15
+
+### Performance
+- **Optimized tool descriptions** - Reduced token usage by 35-45% (~1,500-2,000 tokens)
+  - Shortened main tool descriptions from verbose to concise format
+  - Reduced parameter descriptions (e.g., "CSS selector for element to click" → "CSS selector")
+  - Standardized Figma tool parameters (7 tools optimized)
+  - Pattern-based reductions across all 41 tools
+  - Impact: Saves 1,500-2,000 tokens in every request to Claude
+  - Examples:
+    - `analyzePage`: 95 tokens → 30 tokens (68% reduction)
+    - `screenshot`: 75 tokens → 25 tokens (66% reduction)
+    - `listNetworkRequests`: 50 tokens → 20 tokens (60% reduction)
+
+### Changed
+- All tool descriptions now use imperative voice and remove redundancy
+- Figma tools: "Figma API token (optional if FIGMA_TOKEN env var is set)" → "API token (optional)"
+- Common patterns: "Milliseconds to wait" → "Wait ms", "Maximum" → "Max", etc.
+
 ## [1.7.0] - 2025-12-14
 
 ### Removed

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
+  - [Recorder Tools](#6-recorder-tools) ⭐ **NEW** - enableRecorder, executeScenario, listScenarios, searchScenarios, getScenarioInfo, deleteScenario, exportScenarioAsCode
 - [Typical Workflow Example](#typical-workflow-example)
 - [Tool Usage Tips](#tool-usage-tips)
 - [Configuration](#configuration)
@@ -506,9 +506,32 @@ 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)
+
+Once a directory is set (explicitly or auto-detected), it's remembered for the entire MCP server session.
+
+**Example**:
+```javascript
+// Let it auto-detect (recommended)
+enableRecorder()
+
+// Or specify explicitly
+enableRecorder({ directory: "/path/to/project" })
+
+// Later calls reuse the same directory automatically
+executeScenario({ name: "test" })  // Uses remembered directory
+```
+
+---
+
 #### enableRecorder
 Inject visual recorder UI widget into the current page.
-- **Parameters**: None
+- **Parameters**:
+  - `directory` (optional): Directory to save scenarios (auto-detected if not provided)
 - **Use case**: Start recording user interactions visually
 - **Returns**: Success status
 - **Features**:
@@ -524,6 +547,7 @@ Execute a previously recorded scenario by name.
   - `name` (required): Scenario name
   - `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
 - **Returns**: Execution result with success/failure status
 - **Features**:
@@ -541,7 +565,8 @@ Execute a previously recorded scenario by name.
 
 #### listScenarios
 Get all available scenarios with metadata.
-- **Parameters**: None
+- **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
 
@@ -550,6 +575,7 @@ Search scenarios by text or tags.
 - **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
 
@@ -558,15 +584,59 @@ Get detailed information about a scenario.
 - **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)
 
 #### deleteScenario
 Delete a scenario and its associated secrets.
-- **Parameters**: `name` (required)
+- **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).
+
+- **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)
+
+- **Use case**: Convert recorded scenarios into maintainable test code
+
+- **Returns**: Generated test code as string
+
+- **Example**:
+  ```javascript
+  // Export scenario as Playwright TypeScript
+  exportScenarioAsCode({
+    scenarioName: "checkout_flow",
+    language: "playwright-typescript",
+    cleanSelectors: true,
+    includeComments: true
+  })
+
+  // Returns clean test code:
+  // import { test, expect } from '@playwright/test';
+  //
+  // test('checkout_flow', async ({ page }) => {
+  //   await page.goto('https://example.com');
+  //   await page.locator('button[data-testid="add-to-cart"]').click();
+  //   await expect(page).toHaveURL(/checkout/);
+  // });
+  ```
+
+- **Selector Cleaning**: Automatically removes unstable patterns:
+  - CSS Modules: `Button_primary__2x3yZ` → removed
+  - Styled-components: `sc-AbCdEf-0` → removed
+  - Emotion: `css-1a2b3c4d` → removed
+  - Hash suffixes: `component_a1b2c3d` → removed
+  - Prefers stable selectors: `data-testid`, `role`, `aria-label`, semantic attributes
+
 ---
 
 ## Typical Workflow Example
@@ -667,6 +737,54 @@ If you don't need to see the browser window, you can use xvfb (virtual X server)
 
 This runs Chrome in GUI mode but on a virtual display (window is not visible).
 
+### Figma API Token Setup
+
+To use Figma tools, you need to configure your Figma Personal Access Token.
+
+**How to get your Figma token:**
+1. Go to your Figma account settings: https://www.figma.com/settings
+2. Scroll down to "Personal access tokens"
+3. Click "Create a new personal access token"
+4. Give it a name (e.g., "chrometools-mcp")
+5. Copy the generated token
+
+**Add token to MCP configuration:**
+
+**Claude Desktop** (`~/.claude/mcp_config.json` or `~/AppData/Roaming/Claude/mcp_config.json` on Windows):
+
+```json
+{
+  "mcpServers": {
+    "chrometools": {
+      "command": "npx",
+      "args": ["-y", "chrometools-mcp"],
+      "env": {
+        "FIGMA_TOKEN": "your-figma-token-here"
+      }
+    }
+  }
+}
+```
+
+**Claude Code** (`~/.claude.json`):
+
+```json
+{
+  "mcpServers": {
+    "chrometools": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "chrometools-mcp"],
+      "env": {
+        "FIGMA_TOKEN": "your-figma-token-here"
+      }
+    }
+  }
+}
+```
+
+**Note:** Alternatively, you can pass the token directly in each Figma tool call using the `figmaToken` parameter, but using the environment variable is more convenient.
+
 ---
 
 ## WSL Setup Guide

package/element-finder-utils.js

@@ -295,6 +295,16 @@ function scoreInputField(element, context, description) {
   return score;
 }
 
+/**
+ * Check if attribute value is safe to use in CSS selector
+ * Returns false if value contains characters that could break selector syntax
+ */
+function isSafeSelectorValue(value) {
+  if (!value || typeof value !== 'string') return false;
+  // Check for problematic characters: quotes, brackets, backslashes
+  return !/["'\\[\]{}()]/.test(value);
+}
+
 /**
  * Generate unique CSS selector for an element
  */
@@ -320,23 +330,32 @@ function getUniqueSelectorInPage(element) {
     }
   }
 
-  // Try name attribute
-  if (element.name) {
+  // Try name attribute (only if value is safe)
+  if (element.name && isSafeSelectorValue(element.name)) {
     const selector = `${element.tagName.toLowerCase()}[name="${element.name}"]`;
-    if (document.querySelectorAll(selector).length === 1) {
-      return selector;
+    try {
+      if (document.querySelectorAll(selector).length === 1) {
+        return selector;
+      }
+    } catch (e) {
+      // Invalid selector, skip
     }
   }
 
-  // Try data attributes
+  // Try data attributes (only if values are safe)
   const dataAttrs = Array.from(element.attributes)
-    .filter(attr => attr.name.startsWith('data-'))
+    .filter(attr => attr.name.startsWith('data-') && isSafeSelectorValue(attr.value))
     .slice(0, 2);
 
   for (const attr of dataAttrs) {
     const selector = `${element.tagName.toLowerCase()}[${attr.name}="${attr.value}"]`;
-    if (document.querySelectorAll(selector).length === 1) {
-      return selector;
+    try {
+      if (document.querySelectorAll(selector).length === 1) {
+        return selector;
+      }
+    } catch (e) {
+      // Invalid selector, skip
+      continue;
     }
   }