Content
# 🧠 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
```bash
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:
```bash
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:
```bash
# 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:
```bash
# 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.
```bash
# 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:_
> ``
---
## 🧪 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](https://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! 🌟
