# QAFusionX

Sequential MCP QA agent. When this server is connected in Cursor it **locks Ask mode**, asks two compulsory questions, then walks a 15-step workflow that cannot skip. Completing step N writes a tick in `step-by-step/` — that tick is the only way step N+1 unlocks.

The Control Console is a live GUI for the same engine: numbered pipeline, Ask-mode banner, artifact browser, and a test-run console you can watch.

**LOCKED — visible browser on every user's device.** The workflow is a pipeline, but crawl and GUI tests never run as a silent job inside it. When any user runs QAFusionX on their machine, a **separate browser window opens on that device** and shows every screen, popup, and click. Headless is rejected. There is no silent mode.

**LOCKED — unbreakable one-browser session.** Open one window and keep it open for Round 1 → Round 2 → all stories → maker → checker → suite. Never close mid-flow. Never reopen a second browser for the next story. Logout/login stays in the same window. Close only at end-of-flow.

## What it does

1. **Ask — project & target** (Ask mode) — product name, what to test, live URL, screenshot.
2. **Ask — user stories** (Ask mode, compulsory) — zip / files, Jira link, or generate-from-system.
3. Persist `User stories/` and `General/01-target.md`.
4. **Round 1 crawl** — every screen and popup: capture → reason → reference MD → living plan → next click.
5. Freeze Round 1 plan / todo.
6. **Round 2 crawl** — same directory shape, hunting anything Round 1 missed.
7. **Generate user stories** — **only if Question 2 was generate-from-system**. After Round 2, create `GeneratedUser stories/` from every captured flow. Later tests use that set only. Zip/Jira runs mark this step N/A.
8. **Complete system map** — long, exhaustive markdown (short files are rejected).
9. **Human test cases** in Jira functional format under `testCase Human/`.
10. Upload those cases to Jira (or write offline payloads).
11. Convert 1:1 to YAML in `testc2ai/`.
12. Generate **GUI and API** Playwright scripts in `AutomatedScripts/`.
13. Run the suite in a **visible headed browser** (you watch every click) with results also streamed to the GUI.
14. Export failures to `reports/QAFusionX-Issues.xlsx` + `.csv` with proof.
15. File Jira **bug** tickets: subject, precondition, steps, expected, actual, proof.
16. **Attach all proof PNGs** to Jira bugs via `qafusionx_attach_bug_proofs` (locked — not description-only paths).
17. Generate **iPay Lite format** Excel QA pack via `qafusionx_generate_ipay_excel` (Area | Concern | User story | …).

## Run locally

```bash
npm install
npx playwright install chromium
cd console && npm install && cd ..
cp .env.example .env   # optional Jira credentials
npm run dev
```

- Control Console: http://127.0.0.1:43181
- Engine API: http://127.0.0.1:43180
- Sample app under test: http://127.0.0.1:43181/sample/login  
  Demo login: `qa.analyst` / `FusionX@2026`

Click **Run guided demo** on the console to execute every step against the bundled Intermediary Management sample (Emergency Details fields matching a Jira functional case).

MCP-only:

```bash
npx tsx src/index.ts
```

## Attach QAFusionX to Cursor (every project, every chat)

**Windows — full TBB + mesh install (recommended):**

```powershell
git clone https://github.com/thejanaloit/QAFusionX.git $env:USERPROFILE\QAFusionX
cd $env:USERPROFILE\QAFusionX
npm run install:mesh
# or: powershell -ExecutionPolicy Bypass -File .\scripts\install-full-mesh.ps1
```

This automatically links **and bootstraps** (clone + npm install if missing):

| Component | Role |
| --- | --- |
| **ThejaBackBone (TBB)** | Vault for credentials; auto-cloned from GitHub if missing |
| **ThejaUltimate** | Orchestration + browser QA; auto-cloned + `npm install` |
| **theGod** | Supreme invent / unstuck; auto-cloned + `npm install` |
| **ThejaThinkingPattern (TTP)** | Rule2 thinking |
| **ThejaCentralBrain (TCB)** | Fused QA knowledge |
| **ThejaD** | FusionX banking toolkit (optional clone) |
| **QAFusionX** | Sequential QA workflow (this repo) |

Config lives in `config/tbb-mesh.json`. Override roots with env vars (`THEJA_BACKBONE_ROOT`, etc.) before install.

**macOS / Linux:**

```bash
git clone https://github.com/thejanaloit/QAFusionX.git ~/QAFusionX
cd ~/QAFusionX
npm install --omit=dev
python3 scripts/link-tbb-mesh.py
bash scripts/install-global-cursor.sh
```

That writes a **user-level** config (`~/.cursor/mcp.json`) and **user rules** (`~/.cursor/rules/qafusionx.mdc`, `qafusionx-visible-browser.mdc`). Cursor merges that into every workspace and every Agent/Ask chat. Then:

1. Command Palette → **Developer: Reload Window**
2. Settings → **Tools & MCP** → turn **QAFusionX** on (green)

This repo also has `.cursor/mcp.json` so opening the QAFusionX folder alone is enough. The installer is what makes it global.

On first use the agent **must**:

1. Switch to **Ask** mode.
2. Ask what the project is and what to test (URL + screenshot).
3. Ask for user stories (zip, Jira, or generate). This second question is mandatory.

Until both answers are stored, every later tool returns `BLOCKED`.

## Publish to GitHub

The cloud agent that built this project has no GitHub login, so it cannot create `github.com/<you>/QAFusionX` from here. The source is already on the Cursor Origin remote. On your machine, after `gh auth login`:

```bash
bash scripts/publish-github.sh QAFusionX public
```

That creates the GitHub repo, adds a `github` remote, and pushes `main`.

## User story sources

| Method | How |
| --- | --- |
| Zip / files | `qafusionx_submit_user_stories` with `source: "zip"` and `zipPath` or `files[]` |
| Jira | `source: "jira"` and `jiraLink` (browse URL, JQL, or issue key). Needs `JIRA_EMAIL` + `JIRA_API_TOKEN` |
| Generate | `source: "generate"` only records the choice. After Round 2, `GeneratedUser stories/` is created from the captured screens. Test cases must use that directory. |

## Artifact layout

```
artifacts/
  step-by-step/                 ticks — the only unlock
  User stories/                 zip / Jira stories
  GeneratedUser stories/        method 3 only, after Round 2
  General/                      01-target.md, human-qa-research.md
  Screens/
    round one/screenshots|references|plan/
    round two/screenshots|references|plan/
    complete-system-map.md
  testCase Human/               Jira-shaped markdown + json
  testc2ai/                     YAML for the AI runner
  AutomatedScripts/gui|api
  reports/                      suite results, XLSX/CSV, proof
  jira/                         upload log, payloads, created keys
  bugs/                         bug tickets with proof
```

## Human test case shape

Titles follow the Jira functional pattern:

`[Sales & Marketing Module] [Intermediary Management][Add new/Manage][FP] - Validate that the Emergency Details section displays all required fields.`

Required sections: Affects versions, Labels, Test Case Type, Priority, Parent, Linked work items, Preconditions, Test Steps, Test Comments, Expected Result, Actual Result.

## Jira

Set `JIRA_BASE_URL`, `JIRA_EMAIL`, `JIRA_API_TOKEN`, `JIRA_PROJECT_KEY`. Without them, QAFusionX still completes the steps by writing `jira/payloads/*.json` — it never skips the node.

## Visible browser (LOCKED)

This rule is locked in the engine, MCP protocol, and Cursor rules. You cannot turn it off.

The pipeline still runs step by step. That does **not** mean Round 1, Round 2, or GUI tests run in the background.

When QAFusionX runs on a user's device:

1. A **separate real browser window** opens on **that device**.
2. Crawl and GUI tests happen in that window.
3. The user watches every navigation and click.

`QAFUSIONX_HEADED=0` is rejected. If the machine has no display, QAFusionX stops and tells you to run it on the user's own computer. It will not continue headless.

## Sinhala — මෙය කොහොමද පාවිච්චි කරන්නේ

Cursor එකේ QAFusionX MCP එක connect කළාම **Ask mode** එකට යන්න. මුලින්ම project එක සහ test කරන්න ඕන දේ, URL එක, screenshot එක අහනවා. ඊට පස්සේ **අනිවාර්යයෙන්** user stories අහනවා — zip, Jira link, හෝ system එකෙන් generate. මේ දෙකම උත්තර දුන්නට පස්සේ විතරක් crawl / test generation පටන් ගන්න පුළුවන්. කිසිම step එකක් skip කරලා ඊළඟ එකට යන්න බෑ; `step-by-step/` තියෙන tick එක තමයි ඊළඟ unlock එක.

මේක කිසිම සෙත්ම pipeline එකක් ඇතුළේ කරනවා වගේ කරන්න එපා. හැම user කෙනෙක්ගේමම device එකේ වෙනම browser එකක් open වෙලා ඒකෙන් පේන්න ඕන. Headless lock කරලා තියෙනවා.