chrometools-mcp 1.9.1 → 2.2.0

package/CHANGELOG.md

@@ -2,6 +2,231 @@
 
 All notable changes to this project will be documented in this file.
 
+## [2.2.0] - 2025-12-21
+
+### Added
+- **Page Object Model (POM) Generator** - New `generatePageObject` MCP tool for automated Page Object creation
+  - Analyzes current page and extracts interactive elements (inputs, buttons, links, etc.)
+  - Smart selector generation: prioritizes id > name > data-testid > unique class > CSS path
+  - Auto-generates meaningful element names from labels, placeholders, text content
+  - Groups elements by semantic sections (header, nav, form, footer, etc.)
+  - Supports 4 frameworks: Playwright TypeScript/Python, Selenium Python/Java
+  - Generates helper methods automatically (fill/click methods for common actions)
+  - Example: `generatePageObject({ framework: 'playwright-typescript' })`
+  - Location: `recorder/page-object-generator.js`, `index.js:46,2098-2136`
+
+- **Page Object Integration in exportScenarioAsCode** - Optional Page Object generation when exporting scenarios
+  - New parameter `generatePageObject` (default: false) to generate both test code and Page Object class
+  - New parameter `pageObjectClassName` for custom Page Object class names
+  - Opens scenario's entry URL and analyzes page structure automatically
+  - Returns JSON with both `testCode` and `pageObjectCode` when enabled
+  - Example: `exportScenarioAsCode({ scenarioName: "login", language: "playwright-typescript", generatePageObject: true })`
+  - Location: `index.js:2090-2186`, `server/tool-schemas.js:281-282`, `server/tool-definitions.js:565-572`
+
+- **Append Mode for exportScenarioAsCode** - Ability to append generated tests to existing test files
+  - New parameter `appendToFile`: Path to existing test file to append to (enables append mode)
+  - New parameter `testName`: Override test name (default: from scenario name)
+  - New parameter `insertPosition`: Where to insert test - 'end' (default), 'before', or 'after' a reference test
+  - New parameter `referenceTestName`: Reference test name for 'before'/'after' insertion
+  - Supports all 4 frameworks: Playwright TypeScript/Python, Selenium Python/Java
+  - Automatic file validation (extension must match language)
+  - Automatic backup before file modification (.backup extension)
+  - Smart test name conversion (camelCase for Java, snake_case for Python, kebab-case for TypeScript)
+  - Framework-specific parsing: brace counting for TypeScript/Java, indentation-based for Python
+  - PEP 8 compliance: 2 blank lines between Python functions
+  - Example: `exportScenarioAsCode({ scenarioName: "new_test", language: "playwright-typescript", appendToFile: "./tests/suite.spec.ts" })`
+  - Location: `utils/code-generators/file-appender.js` (new 177 lines), `index.js:2044-2116`, `server/tool-schemas.js:283-286`, `utils/code-generators/*.js`
+
+### Fixed
+- **Dependency Resolution with projectId** - Fixed collision errors when executing scenarios with dependencies
+  - Dependencies now correctly inherit parent scenario's projectId when not explicitly specified
+  - Explicit dependency projectId in metadata takes precedence over inherited value
+  - Fixes error: "Dependency 'test': Multiple scenarios named 'test' found"
+  - Location: `recorder/scenario-executor.js:63-119`
+
+## [2.1.1] - 2025-12-21
+
+### Fixed
+- **executeScenario Timeout Fix** - Prevents hanging when no browser tab is attached
+  - Auto-opens browser at scenario's entryUrl if no page is open
+  - Added timeout protection (1s) for page state checks to prevent hanging on `isClosed()`
+  - Added 30s timeout for browser opening operation
+  - Added 5min timeout for scenario execution with clear error messages
+  - Location: `browser/page-manager.js:255-290`, `index.js:1875-1955`
+
+- **URL Validation Fix** - Fixed false negative in scenario exit URL validation
+  - Added 500ms wait before URL check to allow navigation/redirects to complete
+  - Changed from `page.url()` to `page.evaluate(() => window.location.href)` for more reliable current URL
+  - Fixes issue where correct URL was reported as wrong due to timing
+  - Location: `recorder/scenario-executor.js:186-191`
+
+- **Global Timeout Protection** - All MCP tools now protected from hanging
+  - Added `executeToolWithTimeout()` wrapper for all tool calls
+  - Default timeout: 2 minutes for regular tools, 6 minutes for executeScenario
+  - Tools return clear error messages instead of hanging indefinitely
+  - Location: `index.js:183-217`
+
+### Changed
+- **Code Refactoring** - Reduced index.js from 3761 to 2093 lines (-44%)
+  - Extracted tool schemas to `server/tool-schemas.js` (34 schemas, 282 lines)
+  - Extracted tool definitions to `server/tool-definitions.js` (41 tools, 569 lines)
+  - Extracted browser management to `browser/browser-manager.js` (207 lines)
+  - Extracted page management to `browser/page-manager.js` (268 lines)
+  - Extracted image processing to `utils/image-processing.js` (254 lines)
+  - Extracted CSS utilities to `utils/css-utils.js` (163 lines)
+  - Extracted platform utilities to `utils/platform-utils.js` (63 lines)
+  - Better code organization and maintainability
+
+## [2.1.0] - 2025-12-21
+
+### Added
+- **Name Collision Detection** - Smart handling of scenarios with same name across different projects
+  - `executeScenario` now detects when multiple scenarios share the same name
+  - Returns helpful error with list of available `projectId` values
+  - Optional `projectId` parameter to disambiguate: `executeScenario({ name: "login", projectId: "google" })`
+  - Location: `recorder/scenario-storage.js:111-163`, `recorder/scenario-executor.js:33,49-61,86-90`, `index.js:1677,3558-3571,3597-3600`
+
+### Changed
+- **URL-Based Scenario Organization** - Scenarios now organized by website domain instead of file system project
+  - Project ID automatically extracted from URL where recording starts: `https://google.com` → `google`
+  - Main domain only (subdomains stripped): `mail.google.com` → `google`
+  - Ports included for ALL domains: `localhost:3000` → `localhost-3000`, `example.com:8080` → `example-8080`
+  - Protocol ignored: `http` and `https` both map to same projectId
+  - File URLs: `file:///` → `local`
+  - Location: `utils/url-to-project.js`, `recorder/recorder-script.js:30-78`
+
+- **Global Scenario Access** - All tools now return scenarios from ALL websites
+  - `listScenarios()` returns ALL scenarios with `projectId`, `entryUrl`, `exitUrl` metadata
+  - `searchScenarios()` searches ALL scenarios across all websites
+  - Agent can filter results by `projectId`, `entryUrl`, or `exitUrl` as needed
+  - Removed `allProjects` parameter (no longer needed, always returns all)
+  - Location: `index.js:3586-3610`
+
+- **Simplified API** - Recorder no longer depends on file system project detection
+  - `injectRecorder()` signature changed from `(page, projectDir, projectId, projectPath)` to `(page)`
+  - Project ID determined automatically from page URL in browser context
+  - Removed dependency on `utils/project-detector.js`
+  - Location: `recorder/recorder-script.js:1710-1763`, `index.js:3512-3533`
+
+### Added
+- **URL Normalization Utilities** - New module for extracting project ID from URLs
+  - `urlToProjectId(url)` - Extract and sanitize domain-based project ID
+  - `sanitizeProjectId(id)` - Clean project IDs (lowercase, alphanumeric, hyphens)
+  - Browser-compatible version injected into recorder widget
+  - Location: `utils/url-to-project.js`
+
+### Migration
+- **Automatic v2.1.0 Migration** - Old project-based scenarios removed on first run
+  - Deletes `~/.config/chrometools-mcp/projects/` directory from v2.0
+  - Deletes old global index
+  - Creates `.migration-v2.1.0-done` flag file
+  - One-time migration, starts fresh with URL-based organization
+  - Location: `index.js:780-811`
+
+### Removed
+- **Removed `utils/project-detector.js`** - No longer needed for URL-based organization
+- **Removed helper functions** - `getProjectId()`, `getProjectDir()`, `getCurrentProjectDir()`
+- **Removed old scenarios** - All v2.0 scenarios deleted during migration
+
+### Documentation
+- **Updated README.md** - Complete rewrite of Recorder Tools section
+  - Explained URL-based storage approach with examples
+  - Updated all tool descriptions and examples
+  - Documented domain extraction rules
+  - Added filtering examples for agents
+  - Location: `README.md:507-618`
+
+## [2.0.2] - 2025-12-21
+
+### Fixed
+- **Project Detection for VS Code** - Improved project root detection for IDE environments
+  - Added support for `INIT_CWD` and `npm_config_local_prefix` environment variables
+  - Added `findProjectRootByMarkers()` to detect project by package.json, pom.xml, etc.
+  - Walks up parent directories to find Git root when cwd is IDE installation
+  - Now correctly detects `C:\prj\automation` instead of `Microsoft VS Code` when running in VS Code
+  - Location: `utils/project-detector.js:38-68`, `utils/project-detector.js:85-140`
+
+### Added
+- **Enhanced Project Detection Strategy** - Multiple fallback mechanisms for project root detection
+  - Priority: CLAUDE_PROJECT_DIR → PROJECT_DIR → INIT_CWD → npm prefix → Git root → markers → parent Git → cwd
+  - Supports 8+ project markers: package.json, pom.xml, build.gradle, Cargo.toml, go.mod, etc.
+  - Better logging with `console.error` for debugging project detection
+
+### Documentation
+- **VS Code Setup Guide** - Add instructions for setting PROJECT_DIR in MCP config for VS Code users
+
+## [2.0.1] - 2025-12-21
+
+### Fixed
+- **Recorder Auto-Reinjection** - Fixed critical bug where recorder widget didn't reinject after page navigation
+  - Updated `setupRecorderAutoReinjection()` to use new v2.0 API signature
+  - Fixed both navigation (`framenavigated`) and reload (`load`) event handlers
+  - Recorder now correctly passes `projectDir`, `projectId`, and `projectPath` instead of deprecated `baseDir`
+  - Location: `index.js:483-486`, `index.js:499-502`
+
+## [2.0.0] - 2025-12-21
+
+### Breaking Changes
+- **Project-Based Scenario Storage** - Complete restructuring of scenario storage system
+  - Scenarios now stored in `~/.config/chrometools-mcp/projects/{projectName}/scenarios/`
+  - Each project has its own isolated scenario storage
+  - Automatic project detection via `detectProjectRoot()` (CLAUDE_PROJECT_DIR → PROJECT_DIR → git root → cwd)
+  - Global index file at `~/.config/chrometools-mcp/index.json` for fast scenario discovery
+  - Scenarios include `projectId` and `projectPath` in metadata
+  - Old scenarios in `~/.config/chrometools-mcp/scenarios/` will no longer be accessible
+  - Location: `index.js:66-159`, `recorder/scenario-storage.js`
+
+- **Removed `directory` parameter** - All scenario tools no longer accept explicit directory parameter
+  - Removed from: `enableRecorder`, `executeScenario`, `listScenarios`, `searchScenarios`, `getScenarioInfo`, `deleteScenario`, `exportScenarioAsCode`
+  - Project directory is now automatically determined
+  - Simplifies API and improves consistency
+  - Location: `index.js:1659-1750` (tool definitions)
+
+### Added
+- **Global Scenario Index** - Fast O(1) scenario lookups without filesystem scanning
+  - Location: `~/.config/chrometools-mcp/index.json`
+  - Contains all projects and their scenarios
+  - Enables quick discovery of scenarios across all projects
+  - AI-friendly: agents can read global index to understand all available scenarios
+  - Location: `index.js:103-159`, `recorder/scenario-storage.js:23-136`
+
+- **Multi-Project Filtering** - New `allProjects` parameter for `listScenarios` and `searchScenarios`
+  - `allProjects: false` (default) - shows only current project's scenarios
+  - `allProjects: true` - shows scenarios from all projects
+  - Enables cross-project scenario discovery and reuse
+  - Location: `index.js:1685`, `index.js:1697`, `recorder/scenario-storage.js:385-453`
+
+- **Cross-Project Dependency Support** - Scenarios can depend on scenarios from other projects
+  - Dependencies automatically resolved across projects via global index
+  - Enables scenario reuse between projects
+  - Location: `recorder/scenario-executor.js:27-121`
+
+- **Storage Path in Tool Descriptions** - All scenario tools now document storage location
+  - Every tool description includes: "Scenarios are stored in ~/.config/chrometools-mcp/projects/{projectName}/scenarios/"
+  - Helps AI agents understand where to find scenarios
+  - Includes reference to global index location
+  - Location: `index.js:1660`, `index.js:1668`, `index.js:1681`, etc.
+
+### Changed
+- **Scenario Storage Functions** - Updated all storage functions for new architecture
+  - `saveScenario(scenario, projectId, projectPath)` - now requires project info instead of baseDir
+  - `loadScenario(name, includeSecrets, projectId)` - searches globally, optional project filter
+  - `listScenarios(projectId, allProjects)` - reads from global index
+  - `searchScenarios(query, projectId, allProjects)` - searches global index
+  - `deleteScenario(name, projectId)` - finds and deletes from correct project
+  - Location: `recorder/scenario-storage.js:191-500`
+
+- **Recorder Injection** - Updated to pass project information
+  - `injectRecorder(page, projectDir, projectId, projectPath)` - now accepts project details
+  - Scenarios saved with project context automatically
+  - Location: `recorder/recorder-script.js:1659`
+
+### Migration Guide
+- **Old scenarios are inaccessible** - Scenarios in `~/.config/chrometools-mcp/scenarios/` will no longer be found
+  - To migrate: Manually move scenarios to new structure or re-record them
+  - New structure: `~/.config/chrometools-mcp/projects/{projectName}/scenarios/`
+- **No code changes needed** - All changes are internal, MCP tool interface remains compatible (except removed `directory` parameter)
+
 ## [1.9.1] - 2025-12-19
 
 ### Fixed

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,56 +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.
+**URL-Based Storage (v2.1+)**: Scenarios are automatically organized by website domain in `~/.config/chrometools-mcp/projects/{domain}/scenarios/`.
 
-**Default Location**: `~/.config/chrometools-mcp` (consistent, predictable location in user's home folder)
+**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`
 
-You can override the default by:
-- Passing explicit `directory` parameter to any recorder tool
-- Setting environment variable: `CLAUDE_PROJECT_DIR` or `PROJECT_DIR`
+**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
 
-Once a directory is set (explicitly or via environment), it's remembered for the entire MCP server session.
+**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
 
 **Example**:
 ```javascript
-// Use default location (recommended)
-enableRecorder()  // Saves to ~/.config/chrometools-mcp
-
-// Or specify explicitly
-enableRecorder({ directory: "/path/to/project" })
-
-// Later calls reuse the same directory automatically
-executeScenario({ name: "test" })  // Uses remembered directory
+// 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 (defaults to `~/.config/chrometools-mcp`)
+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 (defaults to `~/.config/chrometools-mcp`)
-- **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)
@@ -563,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 (defaults to `~/.config/chrometools-mcp`)
-- **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 (defaults to `~/.config/chrometools-mcp`)
-- **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 (defaults to `~/.config/chrometools-mcp`)
 - **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 (defaults to `~/.config/chrometools-mcp`)
 - **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 (defaults to `~/.config/chrometools-mcp`)
+  - `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({
@@ -632,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
@@ -639,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