What is Mcp Pw Pom Generator

MCP POM Generator is an experimental tool designed to scan websites and automatically generate optimized Page Object Model (POM) files for Playwright, highlighting the status of web elements.

Use cases

Use cases include generating POM files for web applications, validating web elements during automated testing, and ensuring the accuracy of locators in UI testing.

How to use

To use MCP POM Generator, clone the repository, install dependencies, and run commands to generate POM files for single or multiple pages. You can also compare generated POMs with actual web pages for validation.

Key features

Key features include automatic scanning of multiple pages, generation of TypeScript POM classes, prioritization of accessible attributes, interactive visual overlays for element mapping, and clean CLI reporting for debugging.

Where to use

MCP POM Generator is primarily used in web development and testing environments, particularly for end-to-end (E2E) automation with Playwright.

🧠 MCP POM Generator

Welcome to MCP POM Generator, an experimental and powerful tool to scan websites, auto-generate optimized Page Object Model (POM) files for Playwright, and visually highlight which elements are correctly mapped, missing, or broken. 🔍💥

⚡️ Built to accelerate E2E automation like never before.

🚀 Features

• 🔎 Scans public and private (post-authentication) pages from a site automatically.
• 🔐 Supports sites with complex authentication via integration with Playwright Global Setup.
• 🧬 Generates POM classes in TypeScript, ready for Playwright.
• ✅ Prioritizes data-testid, roles (getByRole), labels (getByLabel), placeholders (getByPlaceholder), and other accessible attributes.
• 🟩 Interactive visual overlay (compare.ts) with:
  • 🟩 Green: found elements defined in the POM.
  • 🟥 Red: POM locators not found on the page (logged in console).
  • 🟦 Blue: interactive elements found on the page but not mapped in the POM.
• 📂 Outputs saved in src/output/.
• 💻 Visual validation in the browser.
• 📋 Clean CLI reporting for debugging.

🛠 Installation

git clone https://github.com/juantor16/mcp-pom-generator.git
cd mcp-pom-generator
npm install

🚀 Usage with Aegis GUI (Recommended)

The easiest way to use the tool is through the Aegis QA Toolkit web interface.

Prerequisites:

• Node.js and npm installed
• Run npm install in the root directory to install all dependencies (backend and frontend)
• If analyzing authenticated sites, complete the one-time authentication setup described in docs/authentication.md (which generates storageState.json)

Running the Application:

1. Open your terminal in the project’s root directory
2. Run the combined start command:

   npm run start:dev
   

3. This will launch both:
   • Backend API server (port 3001)
   • Frontend GUI development server (port 5173)
4. Open your web browser and navigate to http://localhost:5173
5. Use the interface to enter a target URL and start analysis or crawling
6. For each analyzed page, the tool will generate:

   src/output/
   └── page-name/           # Directory for each analyzed page
       ├── page-name.ts     # Page Object Model
       └── page-name.png    # Full-page screenshot
   

Alternative Usage Methods

While the GUI is recommended for most users, the tool can also be used through other interfaces:

CLI Usage

For automation scripts or command-line preference:

# Analyze a single page
npx ts-node src/cli.ts analyze <url>

# Crawl and analyze multiple pages
npx ts-node src/cli.ts crawl <url>

Server API Usage

The server API (started automatically with npm run start:dev) can be used directly:

# Start only the backend server
npm run start:backend

# Then make API calls to:
POST http://localhost:3001/analyze
POST http://localhost:3001/crawl

Output Structure

For each analyzed page, the tool creates a dedicated directory under src/output/ containing:

src/output/
├── home/                 # Example: Homepage
│   ├── home.ts          # POM with element selectors and methods
│   └── home.png         # Full-page screenshot for reference
├── login/               # Example: Login page
│   ├── login.ts         # POM for login page
│   └── login.png        # Screenshot of login page
└── dashboard/           # Example: Dashboard
    ├── dashboard.ts     # POM for dashboard
    └── dashboard.png    # Screenshot of dashboard

This structure helps maintain organization and provides visual references alongside the generated POMs.

2. Compare a POM with the Live Page:

Use compare.ts to visually validate a generated POM against the live page. It shows which locators match, which are broken, and which elements might be missing from the POM.

Important: For pages that require authentication, you must use the --use-session flag and ensure the storageState.json file (generated by your Global Setup) exists.

# Example for a public page (no session needed)
npx ts-node src/compare.ts --url=https://your-site.com/public --pom=src/output/public.ts

# Example for an authenticated page (requires session state)
# Make sure storageState.json exists first!
npx ts-node src/compare.ts --url=https://your-site.com/dashboard --pom=src/output/dashboard.ts --use-session

• 🟩 Green: POM locator found.
• 🟥 Red: POM locator NOT found (logged in console).
• 🟦 Blue: interactive element on the page but missing in the POM.

✨ Visual Example

(Optional image here showing the comparison on an authenticated page)
Add it like this:
![Comparison Example](https://raw.githubusercontent.com/juantor16/mcp-pw-pom-generator/master/docs/example-compare.png)

🧪 Roadmap

• [x] Auto-generate POMs per page
• [x] Visual validation of locators (compare.ts)
• [x] Authentication handling via Global Setup
• [ ] DevTools-like visual mode for interactive exploration
• [ ] CLI to compare POM versions
• [ ] Auto-push updated POMs to a remote repo
• [ ] Web UI to manage and visualize POMs

🧠 Why MCP?

“Because a POM is useless if you don’t know if it works.”

👨‍💻 Author

Juan Torres
🔗 linkedin.com/in/juantor16
QA Engineer | Automation Lover | 🇦🇷

⚠️ License

MIT – Use it, improve it, and share it 🚀

⭐ Was it useful?

Please consider starring the repo! 🌟