Metadata-Version: 2.4
Name: qa-gentic-stlc-agents
Version: 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/stlc-agents#readme
Project-URL: Repository, https://github.com/qa-gentic/stlc-agents
Project-URL: Issues, https://github.com/qa-gentic/stlc-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-stlc-agents

> 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.

[![PyPI version](https://img.shields.io/pypi/v/qa-gentic-stlc-agents)](https://pypi.org/project/qa-gentic-stlc-agents/)
[![Python >=3.10](https://img.shields.io/badge/python-%3E%3D3.10-blue)](https://python.org)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/qa-gentic/stlc-agents/blob/main/LICENSE)

---

## Overview

`qa-gentic-stlc-agents` is the Python backend for the QA STLC Agent system. It installs four Model Context Protocol (MCP) server binaries that AI coding agents (Claude Code, GitHub Copilot, Cursor, Windsurf) use to automate the full Software Test Life Cycle against Azure DevOps.

**The recommended installation path is via the npm companion package:**

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

This installs `qa-gentic-stlc-agents` via pip, copies skill files, and writes your MCP config automatically. If you prefer to install Python-only:

```bash
pip install qa-gentic-stlc-agents
```

---

## Requirements

- Python ≥ 3.10, < 3.14
- Azure DevOps organisation
- A `.env` file with ADO credentials (see [Configuration](#configuration))

---

## MCP Servers Installed

`pip install qa-gentic-stlc-agents` places four executable MCP server scripts on your PATH:

| Binary | Server Name | Purpose |
|---|---|---|
| `qa-test-case-manager` | `qa-test-case-manager` | ADO work item → structured manual test cases |
| `qa-gherkin-generator` | `qa-gherkin-generator` | ADO work item hierarchy → validated Gherkin `.feature` |
| `qa-playwright-generator` | `qa-playwright-generator` | Gherkin + live AX tree → self-healing Playwright TypeScript |
| `qa-helix-writer` | `qa-helix-writer` | Generated files → Helix-QA directory layout on disk |

All four servers communicate over **stdio MCP** — the standard transport for CLI-spawned MCP servers. No ports, no daemons, no firewall rules.

---

## Tool Reference

### `qa-test-case-manager`

Converts ADO work item acceptance criteria into structured manual test cases, linked back via `TestedBy-Forward` relation.

| Tool | Description |
|---|---|
| `fetch_work_item` | Fetch a PBI, Bug, or Feature. Runs coverage hint extraction across 11 categories. Returns `epic_not_supported` for Epics; `confirmation_required: true` for Features. |
| `get_linked_test_cases` | List all test cases already linked to a work item — used for deduplication diffing. |
| `create_and_link_test_cases` | Create structured manual test cases in ADO and link them via TestedBy-Forward. |

**Coverage hint categories:** `toast_notifications`, `file_size_boundary`, `post_action_state`, `platform_specific`, `computed_values`, `data_persistence`, `accessibility`, `image_manipulation`, `file_formats`, `cancel_flows`, `validation_errors`

**Complexity → TC range:**
- 1–3 story points → Simple → 3–6 test cases
- 4–8 story points → Medium → 6–12 test cases
- 9+ story points → Complex → 12–18 test cases

---

### `qa-gherkin-generator`

Converts ADO work item hierarchies into validated Gherkin `.feature` files and attaches them to the work item.

| Tool | Description |
|---|---|
| `fetch_epic_hierarchy` | Fetch an Epic with all child Features, PBIs, Bugs, and existing TCs. |
| `fetch_feature_hierarchy` | Fetch a Feature with all child PBIs/Bugs and linked test case steps. |
| `fetch_work_item_for_gherkin` | Fetch a PBI or Bug with parent Feature context and linked TC steps. |
| `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. |
| `validate_gherkin_content` | Structural validation — returns `valid: bool`, `errors[]`, `warnings[]`. |

**Routing (strict — no inference):**
- Epic ID → `fetch_epic_hierarchy`
- Feature ID → `fetch_feature_hierarchy`
- PBI/Bug ID → `fetch_work_item_for_gherkin`

**File naming:** `{id}_{title-kebab-case}_regression.feature`

---

### `qa-playwright-generator`

Converts validated Gherkin into production-ready, three-layer self-healing Playwright TypeScript. Selectors are derived from the live browser accessibility tree via Playwright MCP — never hallucinated.

| Tool | Description |
|---|---|
| `generate_playwright_code` | Gherkin + `context_map` → `locators.ts`, `*Page.ts`, `*.steps.ts`, cucumber profile. Hard-blocks if `context_map` is absent. |
| `scaffold_locator_repository` | Generate the six shared healing infrastructure files: `LocatorHealer`, `LocatorRepository`, `TimingHealer`, `VisualIntentChecker`, `DevToolsHealer`, `HealingDashboard`. |
| `validate_gherkin_steps` | Check for duplicate step strings and missing `When` steps. |
| `attach_code_to_work_item` | Attach delta TypeScript files to an ADO work item. Pass only net-new files. |

**Generated files per feature:**

| File | Contents |
|---|---|
| `locators.ts` | CDP-validated selectors with intent, stability score, bounding box, and visual intent flag |
| `{kebab}.page.ts` | Page object with all three healing layers active |
| `{kebab}.steps.ts` | Cucumber step definitions via PageFixture dependency injection |
| Cucumber profile key | Appended to `cucumber.config.ts` |

**Selector stability scoring (at generation time):**

| Selector type | Score |
|---|---|
| `data-testid` | 100 |
| `aria-role + aria-label` | 90 |
| Non-generated `id` | 80 |
| `aria-label` alone | 70 |
| `placeholder` | 60 |
| Role + text (XPath) | 50 |

---

### `qa-helix-writer`

Writes already-generated files to disk at the correct Helix-QA directory layout. No ADO dependency. No LLM calls. Pure path mapping and file I/O.

| Tool | Description |
|---|---|
| `inspect_helix_project` | Returns `framework_state` (`present` / `partial` / `absent`) and `recommendation` (`tests_only` / `scaffold_and_tests`). |
| `list_helix_tree` | Full directory listing of the Helix-QA project. |
| `read_helix_file` | Read an existing file for overlap detection before overwrite. |
| `write_helix_files` | Write generated files to the correct Helix-QA paths. |

**Directory mapping:**

| Generated file | Helix-QA path |
|---|---|
| `locators.ts` | `src/locators/<kebab>.locators.ts` |
| `<Page>.page.ts` | `src/pages/<Page>.page.ts` |
| `<feature>.steps.ts` | `src/test/steps/<feature>.steps.ts` |
| `<feature>.feature` | `src/test/features/<feature>.feature` |
| Cucumber profile key | `src/config/cucumber.config.ts` (appended, not replaced) |
| `utils/locators/*.ts` | `src/utils/locators/<file>` |

---

## Authentication

All four servers share a single MSAL token cache, using the same constants as `microsoft/azure-devops-mcp`:

```
Cache file: ~/.msal-cache/msal-cache.json
Client ID:  04b07795-8ddb-461a-bbee-02f9e1bf7b46 (Azure CLI)
Scope:      499b84ac-1321-427f-aa17-267ca6975798/.default
```

**Interactive (developer machines):** Sign into VS Code or run `az login` once. The token is cached silently for ~90 days.

**Non-interactive (CI/CD):** Set environment variables for service principal auth:

```env
AZURE_CLIENT_ID=your-app-id
AZURE_CLIENT_SECRET=your-secret
AZURE_TENANT_ID=your-tenant-id
```

---

## Configuration

`.env` file in your project root:

```env
ADO_ORGANIZATION_URL=https://dev.azure.com/your-org
ADO_PROJECT_NAME=YourProject
ADO_PAT=your-personal-access-token
APP_BASE_URL=https://your-app.example.com
APP_EMAIL=test-user@example.com
APP_PASSWORD=test-password

# Optional — for Layer 8 AI Vision healing at runtime
AI_API_KEY=your-anthropic-or-openai-key

# Optional — healing at runtime
ENABLE_SELF_HEALING=true
HEALING_DASHBOARD_PORT=7890   # set to 0 to disable HTTP server in CI
```

---

## Dependencies

```
mcp>=1.0.0
python-dotenv>=1.0.0
requests>=2.31.0
msal>=1.20.0
```

No TypeScript compiler required. All TypeScript generation is pure Python string templating.

---

## Three-Layer Self-Healing (at test runtime)

The generated Playwright code uses a three-layer healing architecture that runs when tests execute (not when agents run):

**Layer 1 — Locator Healing (`LocatorHealer.ts`):** When a selector fails, tries 8 recovery strategies: cached result → primary CSS → ARIA role → ARIA label → text → CDP AX tree → bounding box → AI Vision. Successful alternatives are queued for human approval at `http://localhost:7890`.

**Layer 2 — Timing Healing (`TimingHealer.ts`):** Detects network response drift > 20% from baseline, auto-adjusts timeouts with 50% headroom, queues suggestion for engineer review.

**Layer 3 — Visual Healing (`VisualIntentChecker.ts`):** At elements marked `visualIntent: true`, captures a scoped screenshot and pixel-diffs against an approved baseline. Threshold: 0.5%.

All suggestions require human approval via the HealingDashboard before entering version control.

---

## Running Tests

```bash
ENABLE_SELF_HEALING=true \
HEALING_DASHBOARD_PORT=7890 \
cucumber-js --config=config/cucumber.js -p <feature_profile>
```

---

## Development

```bash
git clone https://github.com/qa-gentic/stlc-agents.git
cd stlc-agents
make install      # create .venv + pip install -e .
make test         # pytest tests/ -v
make verify       # check MSAL auth
```

---

## Related

- **npm package:** [`@qa-gentic/stlc-agents`](https://www.npmjs.com/package/@qa-gentic/stlc-agents) — CLI installer and skill file distributor
- **GitHub:** [qa-gentic/stlc-agents](https://github.com/qa-gentic/stlc-agents)
- **Playwright MCP:** `npx @playwright/mcp@latest --port 8931`

---

## License

MIT © qa-gentic