@pomgo/cli/README.md

Pomgo - Test Automation CLI - Interactive picker, page parser, and POM generator

# 🔧 Test Automation Tools

**Modular, self-contained tools** for test automation using **Chrome DevTools Protocol (CDP)**.

## 📦 Modules

### 🎯 Interactive Element Picker
Pick elements visually like Playwright's Pick Locator - **without Playwright!**

```bash
npm run pick https://github.com/login
```

**[→ Full Documentation](./picker/README.md)**

---

### 🔍 CDP Page Parser
Extract all interactive elements from a page as structured JSON.

```bash
npm run parse https://github.com/login
```

**[→ Full Documentation](./parser/README.md)**

---

### 🏗️ POM Generator
Generate clean Page Object Model classes from JSON - **with LLM support!**

```bash
npm run generate output/picked/picked-elements-latest.json
npm run generate output/picked/picked-elements-latest.json --llm
```

**[→ Full Documentation](./pom-generator/README.md)**

---

## 🚀 Quick Start

### Install Dependencies

```bash
npm install
```

### Use Picker

```bash
npm run pick https://example.com
```

- Hover to highlight elements
- Click to pick and see locators
- Press Ctrl+C to exit
- Results saved to `output/picked/picked-elements-latest.json`

### Use Parser

```bash
npm run parse https://example.com
```

- Extracts all interactive elements
- Results saved to `output/{domain}-{timestamp}.json`

### Generate POM

```bash
npm run generate output/picked/picked-elements-latest.json
```

- Generates Page Object Model from JSON
- With LLM: `npm run generate <file> --llm`
- Results saved to `output/pom/{ClassName}.ts`

---

## 🧩 Modular Architecture

Each module is **completely independent**:

```
/picker/               ← Interactive Element Picker
  ├── package.json
  ├── tsconfig.json
  ├── README.md
  ├── InteractivePicker.ts
  ├── types/
  ├── utils/
  └── cli/

/parser/               ← CDP Page Parser
  ├── package.json
  ├── tsconfig.json
  ├── README.md
  ├── CDPParser.ts
  ├── types/
  ├── utils/
  └── cli/

/pom-generator/        ← POM Generator
  ├── package.json
  ├── tsconfig.json
  ├── README.md
  ├── POMGenerator.ts
  ├── LLMPOMGenerator.ts
  ├── types/
  ├── utils/
  └── cli/
```

**Copy any module to another project - it just works!** ✅

---

## 🔧 Programmatic Usage

### Picker

```typescript
import { InteractivePicker } from './picker';

const picker = new InteractivePicker();
await picker.start('https://example.com');
```

### Parser

```typescript
import { CDPParser } from './parser';

const parser = new CDPParser();
const pageModel = await parser.parse('https://example.com');
console.log(pageModel);
```

---

## 🎯 Features

### Picker
- ✅ Visual element highlighting
- ✅ Click to pick elements
- ✅ Multiple locator strategies
- ✅ Auto-save on every pick
- ✅ No Playwright dependency

### Parser
- ✅ Extract all interactive elements
- ✅ Multiple locator strategies
- ✅ Confidence scoring
- ✅ Element classification
- ✅ Pure CDP implementation

### POM Generator
- ✅ Generate Page Object Model classes
- ✅ LLM-powered (GPT-4) generation
- ✅ Smart naming and grouping
- ✅ Auto-generate action methods
- ✅ Playwright/Selenium/Cypress support

---

## 📊 Output Examples

### Picker Output
```json
{
  "pickedAt": "2025-10-28T18:00:00.000Z",
  "totalElements": 3,
  "elements": [...]
}
```

### Parser Output
```json
{
  "pageName": "GitHub Login",
  "url": "https://github.com/login",
  "elements": [...]
}
```

---

## 🤝 Using Modules Together

```bash
npm run parse https://example.com
npm run pick https://example.com
```

Each module saves its results to `output/`:
- Picker → `output/picked/`
- Parser → `output/`

---

## 📚 Documentation

- **Three Modules Complete:** [THREE_MODULES_COMPLETE.md](./THREE_MODULES_COMPLETE.md) - Complete guide
- **Modular Architecture:** [MODULAR_ARCHITECTURE.md](./MODULAR_ARCHITECTURE.md) - How the modular structure works
- **Example Usage:** [example-usage.md](./example-usage.md) - How to use modules together
- **Picker:** [picker/README.md](./picker/README.md)
- **Parser:** [parser/README.md](./parser/README.md)
- **POM Generator:** [pom-generator/README.md](./pom-generator/README.md)
- **Interactive Picker Guide:** [picker/INTERACTIVE_PICKER.md](./picker/INTERACTIVE_PICKER.md)
- **Locator Strategies:** [picker/LOCATOR_STRATEGIES.md](./picker/LOCATOR_STRATEGIES.md)

---

## 🛠️ Tech Stack

- **TypeScript**
- **Chrome DevTools Protocol (CDP)**
- **Node.js**
- **ES Modules**

No Playwright, Puppeteer, or Selenium required!

---

## 📦 Add Your Own Module

Create a new module:

```bash
mkdir my-module
cd my-module
npm init -y
```

Add to root `package.json`:

```json
{
  "scripts": {
    "my-module": "cd my-module && npm start"
  }
}
```

**Each module is independent - no shared dependencies!**

---

## 📄 License

MIT