# 🤖 MCP Test Automation Framework

> **SQA Test Automation** powered by **Claude/Deepseek AI** with **self-healing locators** and **auto GitHub checkin**

---

## 🏗️ Architecture

```
mcp-automation/
├── src/
│   ├── mcp/                  # MCP Server (connects AI to browser)
│   │   ├── mcp-server.ts     # MCP tool definitions & handlers
│   │   └── index.ts
│   ├── core/                 # Core modules
│   │   ├── browser-manager.ts  # Playwright browser lifecycle
│   │   ├── config.ts           # Settings loader
│   │   └── logger.ts           # Logging utility
│   ├── healing/              # Self-Healing Engine
│   │   └── locator-healer.ts   # Alternative locator strategies
│   ├── scripts/              # Utility scripts
│   │   └── git-auto-checkin.ts # Auto commit & push to GitHub
│   ├── tests/                # Test definitions
│   │   ├── types.ts
│   │   └── google-search.ts
│   ├── mcp-server-entry.ts   # MCP server entry point
│   └── runner.ts             # Direct test runner
├── config/
│   └── settings.json         # Framework configuration
├── logs/                     # Run logs & screenshots
├── .github/workflows/        # CI/CD pipeline
├── package.json
├── tsconfig.json
└── README.md
```

---

## 🔄 How It Works

```
  1. AI (Claude/Deepseek) calls MCP tool
          │
          ▼
  2. Playwright executes browser action
          │
          ▼
  3. Element not found? 
          │
          ▼
  4. Self-Healing Engine kicks in
     ┌─────────────────────────────┐
     │ Tries: role → text →        │
     │ placeholder → label → testId│
     │ → CSS → XPath → aria-label  │
     └─────────────────────────────┘
          │
          ▼
  5. Found? → Logs healing action, proceeds
     Not found? → Screenshot, reports failure
          │
          ▼
  6. GitHub Auto Checkin
     ┌─────────────────────────────┐
     │ Creates branch              │
     │ test-run/<name>-<timestamp> │
     │ Stages & commits all files  │
     │ Pushes to remote            │
     └─────────────────────────────┘
```

---

## 🚀 Quick Start

### 1. Install dependencies

```bash
npm install
npx playwright install chromium
```

### 2. Configure

Edit `config/settings.json`:
- Set AI provider and API keys (via env vars)
- Configure browser options
- Set GitHub remote URL

### 3. Set API Keys (optional — for AI features)

```bash
set ANTHROPIC_API_KEY=sk-ant-...    # For Claude
set DEEPSEEK_API_KEY=sk-...         # For Deepseek
```

### 4. Run tests directly

```bash
npm run dev
```

### 5. Start MCP Server (for AI assistant connection)

```bash
npm run mcp-server
```

Then connect your AI assistant (Claude/Deepseek) to this MCP server.

---

## 🛠️ MCP Tools Available to AI

| Tool | Description |
|------|-------------|
| `navigate` | Navigate to a URL |
| `click` | Click an element (with self-healing) |
| `type` / `fill` | Type text into fields (with self-healing) |
| `get_text` | Get element text (with self-healing) |
| `wait_for_selector` | Wait for element to appear |
| `screenshot` | Capture page screenshot |
| `press_key` | Press keyboard keys |
| `run_test` | Execute a full test case |
| `auto_checkin` | Commit & push to GitHub |
| `get_healing_summary` | View self-healing stats |

---

## 🧪 Self-Healing

When a locator fails, the engine tries these strategies in order:

1. `getByRole` — Find by ARIA role
2. `getByText` — Find by text content
3. `getByPlaceholder` — Find by placeholder attribute
4. `getByLabel` — Find by associated label
5. `getByTestId` — Find by `data-testid`
6. CSS selector — Try original selector as CSS
7. CSS alternatives — e.g., `textarea` → `input`, attribute variations
8. `[aria-label]` — Find by aria-label attribute

All healing actions are logged to `logs/healing-log.json`.

---

## 📤 GitHub Auto Checkin

After each test run, the framework automatically:
1. Creates a new branch: `test-run/<test-name>-<timestamp>`
2. Stages all changed files (tests, logs, screenshots)
3. Commits with descriptive message
4. Pushes to remote

---

## 🔧 Configuration

See `config/settings.json` for all options:

| Section | Key | Description |
|---------|-----|-------------|
| `ai` | `provider` | `"auto"`, `"claude"`, or `"deepseek"` |
| `browser` | `headless` | `true`/`false` for headed mode |
| `selfHealing` | `enabled` | Enable/disable self-healing |
| `selfHealing` | `maxRetries` | Max healing attempts per locator |
| `github` | `autoCheckin` | Enable auto commit/push |
| `logging` | `level` | `"debug"`, `"info"`, `"warn"`, `"error"` |

---

## 📄 License

MIT