🤖 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

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)

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

4. Run tests directly

npm run dev

5. Start MCP Server (for AI assistant connection)

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