# TestFly MCP Bridge & AI Studio

**Lightweight Model Context Protocol (MCP) bridge for [TestFly](https://github.com/hakanngul/testfly) Java Test Automation.**

Pairs with **Playwright MCP** for ultra-fast live browser driving, while providing autonomous **TestFly Java 21 codegen**, `.testfly/action-cache.json` management, and **AI self-healing patch remediation**.

Zero Python. Zero pip. Zero setup headaches.

[![Node.js](https://img.shields.io/badge/Node.js-%3E%3D18.0.0-green.svg)](https://nodejs.org/)
[![License: Apache 2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE)
[![Java 21](https://img.shields.io/badge/Java-21%2B-orange.svg)](https://www.oracle.com/java/)

---

## 🚀 Architecture: Bring Your Own Browser

Rather than maintaining a heavy Selenium browser driver in Python, TestFly adopts the modern **Bring Your Own Browser** pattern:

1. **Browser Driving:** Delegated to **Playwright MCP** (`@playwright/mcp`).
2. **TestFly Intelligence:** Handled by this **TestFly Bridge**:
   - Compiles recorded actions into idiomatic TestFly Java 21 (`BaseTest`, `BasePage`, `getByRole`, `assertThat`).
   - Manages autonomous `act("Goal")` plans in `.testfly/action-cache.json` for 0ms replay.
   - Reviews and applies AI self-healing git diff patches (`target/remediations/*.patch`).
   - Scaffolds new projects and calculates parallel CI test sharding.

```
[ AI Assistant (Cursor / Claude / Copilot) ]
               │
       ┌───────┴────────────────────────┐
       ▼                                ▼
[ playwright-mcp ]             [ testfly-bridge ]
(Browser Driving)              (Java Codegen & Agentic Tools)
 • Navigates & clicks           • Generates TestFly BaseTest / BasePage
 • Captures A11y DOM snapshots  • Manages .testfly/action-cache.json
 • Takes screenshots            • Applies target/remediations/*.patch
```

---

## ⚡ 1-Click Setup

### Option 1: VS Code Extension
Build and install the **TestFly Studio** extension from this checkout:
1. Open Command Palette (`Cmd+Shift+P` / `Ctrl+Shift+P`).
2. Run `TestFly: Configure Workspace MCP (Cursor & VS Code)` and select this checkout's `bin/testfly-mcp.js`.
3. Review and confirm the changes to the workspace `.cursor/mcp.json` and `.vscode/mcp.json`. Global assistant settings are not edited.

### Option 2: Configure from source
Replace `/absolute/path/testfly-mcp` with this checkout's path in an MCP client that supports this configuration shape:

```json
{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["-y", "@playwright/mcp@latest"]
    },
    "testfly": {
      "command": "node",
      "args": ["/absolute/path/testfly-mcp/bin/testfly-mcp.js"]
    }
  }
}
```

---

## 🛠️ Available MCP Tools

| Tool | Description |
|---|---|
| `generate_testfly_code` | Converts Playwright interactions or DOM snapshots into TestFly Java 21 test classes (`BaseTest`, `BasePage`, `getByRole`, `assertThat`). |
| `inspect_action_cache` | Reads and inspects autonomous `act("Goal")` plans frozen in `.testfly/action-cache.json`. |
| `manage_action_cache` | Invalidates or clears action cache plans so the AI can re-compile them. |
| `list_remediations` | Lists pending AI self-healing `.patch` files generated by `AiHealingEngine` in `target/remediations/`. |
| `apply_remediation_patch` | Applies a reviewed `.patch` file only with explicit `confirm: true`. |
| `init_testfly_project` | Scaffolds a TestFly 1.0.7 Java 21 test suite (`pom.xml`, `testfly.yml`, sample test) in an empty directory. |

---

## 🧩 VS Code Extension Features

- **Action Cache Explorer:** Visual webview panel to inspect, invalidate, and re-compile `act()` goals.
- **AI Self-Healing Patch Reviewer:** Visual diff viewer showing repaired selectors with a 1-click **Apply Patch to Code** button.
- **`testfly.yml` Editor:** Edit the shared starter template and existing YAML in the IDE.
- **Environment Diagnostics:** Instant verification of JDK 21, Maven, Node.js, and configuration status.

The current Node bridge does not implement `testfly record` or a live recorder studio. Those belonged to the historical Python recorder; this repository's codegen accepts actions supplied by an MCP client.