🤖 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