Metadata-Version: 2.4
Name: qa-gentic-agents
Version: 1.1.0
Summary: Four MCP servers covering the full QA Software Test Life Cycle — test cases, Gherkin BDD, self-healing Playwright code, and Helix-QA file writing. Browser interaction via Playwright MCP. Silent MSAL OAuth against Azure DevOps.
Project-URL: Homepage, https://github.com/qa-gentic/qa-gentic-agents#readme
Project-URL: Repository, https://github.com/qa-gentic/qa-gentic-agents
Project-URL: Issues, https://github.com/qa-gentic/qa-gentic-agents/issues
License: MIT
Keywords: azure-devops,bdd,claude,copilot,cucumber,gherkin,mcp,msal,oauth,playwright,playwright-mcp,qa,self-healing,test-cases
Requires-Python: <3.14,>=3.10
Requires-Dist: mcp>=1.0.0
Requires-Dist: msal>=1.20.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: requests>=2.31.0
Description-Content-Type: text/markdown

# @qa-gentic/agents

> AI-powered QA STLC automation — from Azure DevOps work item to self-healing Playwright TypeScript in a Helix-QA project.

Works with **GitHub Copilot** (VS Code Agent mode), **Claude Code**, **Cursor**, and **Windsurf**.

---

## What It Does

Four Python MCP servers cover the full QA Software Test Life Cycle:

| Agent | Input | Output |
|---|---|---|
| `qa-test-case-manager` | ADO PBI / Bug / Feature ID | Manual test cases created & linked via TestedBy-Forward |
| `qa-gherkin-generator` | ADO Epic / Feature / PBI / Bug ID | `.feature` file attached to the ADO work item |
| `qa-playwright-generator` | Gherkin + live browser | `locators.ts` + page objects + step defs attached to ADO |
| `qa-helix-writer` | Generated `.ts` files + `helix_root` | Files written to Helix-QA directory layout on disk |

A fifth server — **Playwright MCP** (`http://localhost:8931/mcp`) — drives a real browser during code generation, replacing hand-authored locators with accessibility-tree-derived, zero-hallucination selectors.

---

## Install

```bash
npm install -g @qa-gentic/agents
qa-stlc init --vscode
```

`qa-stlc init` does three things:
1. `pip install qa-gentic-agents` — installs the four Python MCP servers
2. Copies skill files to `.github/copilot-instructions/` (and `.claude/` if not `--vscode`)
3. Writes `.vscode/mcp.json` with all five servers configured

---

## Requirements

- Node.js ≥ 18
- Python ≥ 3.10
- Azure DevOps organisation with a `.env` containing:

```
ADO_ORGANIZATION_URL=https://dev.azure.com/qa-gentic
ADO_PROJECT_NAME=YourProject
ADO_PAT=your-personal-access-token
APP_BASE_URL=your-app-base-url
APP_EMAIL=your-test-email@example.com
APP_PASSWORD=your-test-password
```

---

## Commands

```bash
qa-stlc init [--vscode] [--python <path>]
# Full bootstrap: pip install + skills + MCP config

qa-stlc skills [--target claude|vscode|cursor|windsurf|both|print]
# Copy skill files to the correct AI coding agent directory

qa-stlc mcp-config [--vscode] [--print] [--python <path>] [--playwright-port <n>]
# Write .vscode/mcp.json (--vscode) or .mcp.json (Claude Code)

qa-stlc verify
# Check that all five MCP servers are reachable
```

---

## Tool Reference

### qa-test-case-manager

| Tool | Description |
|---|---|
| `fetch_work_item` | Fetch a PBI, Bug, or Feature with acceptance criteria, linked test cases, and coverage hints. Returns `epic_not_supported` for Epics. Returns `confirmation_required: true` for Features. |
| `get_linked_test_cases` | List all test cases already linked to a work item. Call before generating to power the deduplication diff. |
| `create_and_link_test_cases` | Create structured manual test cases in ADO and link them via TestedBy-Forward. |

### qa-gherkin-generator

| Tool | Description |
|---|---|
| `fetch_epic_hierarchy` | Fetch an Epic and all child Features, PBIs, Bugs, and existing test cases. Use when user provides an Epic ID. |
| `fetch_feature_hierarchy` | Fetch a Feature and all child PBIs/Bugs with acceptance criteria and existing attachments. Use when user provides a Feature ID. |
| `fetch_work_item_for_gherkin` | Fetch a PBI or Bug with parent Feature context, suggested file name, and linked test case steps. Use when user provides a PBI or Bug ID. |
| `attach_gherkin_to_feature` | Validate and attach a `.feature` file to a Feature work item. |
| `attach_gherkin_to_work_item` | Validate and attach a `.feature` file to a PBI or Bug work item. |
| `validate_gherkin_content` | Structural validation — tags, scenario count, navigation steps. Returns `valid: bool` + `errors` + `warnings`. |

### qa-playwright-generator

| Tool | Description |
|---|---|
| `generate_playwright_code` | Generate `locators.ts`, `*Page.ts`, `*.steps.ts`, and `cucumber-profile.js` from validated Gherkin + live AX-tree `context_map`. Hard-blocks if `context_map` is absent to prevent hallucinated locators. |
| `scaffold_locator_repository` | Generate the six Helix-QA healing infrastructure files: `LocatorHealer.ts`, `LocatorRepository.ts`, `TimingHealer.ts`, `VisualIntentChecker.ts`, `DevToolsHealer.ts`, `HealingDashboard.ts`. |
| `validate_gherkin_steps` | Check for duplicate step strings and missing `When` steps. Prevents `Ambiguous step definition` runtime errors. |
| `attach_code_to_work_item` | Attach delta Playwright TypeScript files to an ADO work item. Pass only net-new delta files. |

### qa-helix-writer

| Tool | Description |
|---|---|
| `inspect_helix_project` | Inspect a Helix-QA project root. Returns `framework_state` (`present` / `partial` / `absent`) and `recommendation` (`tests_only` / `scaffold_and_tests`). |
| `list_helix_tree` | List the full directory tree of a Helix-QA project. |
| `read_helix_file` | Read an existing file from the Helix-QA project for overlap detection. |
| `write_helix_files` | Write generated files to the correct Helix-QA paths. Handles routing, deduplication, and interface adaptation automatically. |

### playwright (external)

| Tool | Description |
|---|---|
| `browser_navigate` | Navigate to a URL in the live browser. |
| `browser_snapshot` | Capture the full AX tree — source for zero-hallucination locators. |
| `browser_fill_form` | Fill multiple form fields by ref. |
| `browser_click` | Click an element by ref. |
| `browser_file_upload` | Upload a file to a file input by ref. |

---

## MCP Config

### VS Code / GitHub Copilot (`.vscode/mcp.json`)

```json
{
  "servers": {
    "qa-test-case-manager":    { "command": "/path/to/.venv/bin/qa-test-case-manager" },
    "qa-gherkin-generator":    { "command": "/path/to/.venv/bin/qa-gherkin-generator" },
    "qa-playwright-generator": { "command": "/path/to/.venv/bin/qa-playwright-generator" },
    "qa-helix-writer":         { "command": "/path/to/.venv/bin/qa-helix-writer" },
    "playwright": { "type": "http", "url": "http://localhost:8931/mcp" }
  }
}
```

### Claude Code (`.mcp.json`)

```json
{
  "mcpServers": {
    "qa-test-case-manager":    { "command": "/path/to/.venv/bin/qa-test-case-manager" },
    "qa-gherkin-generator":    { "command": "/path/to/.venv/bin/qa-gherkin-generator" },
    "qa-playwright-generator": { "command": "/path/to/.venv/bin/qa-playwright-generator" },
    "qa-helix-writer":         { "command": "/path/to/.venv/bin/qa-helix-writer" },
    "playwright": { "type": "url", "url": "ws://localhost:8931" }
  }
}
```

> VS Code requires `http://localhost:8931/mcp` (with `/mcp` suffix).  
> Claude Code requires `ws://localhost:8931` (WebSocket, no `/mcp`).  
> `qa-stlc mcp-config` writes the correct format automatically.

---

## Skills Installed

| Skill | Purpose |
|---|---|
| `AGENT-BEHAVIOR.md` | Zero-inference contract. Read first. Always. |
| `generate-test-cases.md` | PBI / Bug / Feature → ADO manual test cases |
| `generate-gherkin.md` | Epic / Feature / PBI / Bug → validated `.feature` + ADO attach |
| `generate-playwright-code.md` | Gherkin + live browser → three-layer self-healing Playwright TypeScript |
| `write-helix-files.md` | Generated files → Helix-QA disk layout, scaffold or merge |
| `deduplication-protocol.md` | READ → DIFF → CREATE mandatory pre-flight gate |

---

## Three-Layer Self-Healing Architecture

| Layer | Class | What it heals |
|---|---|---|
| 1 — Locator | `LocatorHealer` | primary selector → role → label → text → AI Vision → CDPSession AX tree |
| 2 — Timing | `TimingHealer` | network-trace drift → auto-adjusted timeouts → HealingDashboard |
| 3 — Visual | `VisualIntentChecker` | element screenshot diff at assertions → HealingDashboard |

Healed selectors persist in `LocatorRepository`. HealingDashboard: `http://localhost:7890`.

---

## Run Tests

```bash
ENABLE_SELF_HEALING=true \
HEALING_DASHBOARD_PORT=7890 \
APP_BASE_URL=<your-app-base-url> \
APP_EMAIL=<email> \
APP_PASSWORD=<password> \
cucumber-js --config=config/cucumber.js -p <feature_profile>

# Smoke only
cucumber-js --config=config/cucumber.js -p <feature_profile> --tags "@smoke"
```

---

## License

MIT
