Metadata-Version: 2.4
Name: qa-gentic-stlc-agents
Version: 1.0.44
Summary: Six MCP servers for the full QA STLC — test cases, Gherkin BDD, self-healing Playwright code, Helix-QA file writing, Jira Cloud integration, and one-shot migration of existing Playwright projects into the Helix-QA layout. Both ADO and Jira pipelines run: fetch → test cases → Gherkin → Playwright → Helix-QA. Ships an 8-strategy LocatorHealer with a live HealingDashboard that writes confirmed selectors back to source. MSAL OAuth for ADO, OAuth 2.0 (3LO) for Jira Cloud.
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: atlassian,azure-devops,bdd,claude,claude-code,copilot,cucumber,framework-migration,gherkin,healing-dashboard,jira,locator-healer,mcp,mcp-server,msal,oauth,playwright,playwright-mcp,playwright-migration,qa,self-healing,stlc-migrate,test-cases
Requires-Python: >=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
Provides-Extra: webhook
Requires-Dist: anthropic>=0.40.0; extra == 'webhook'
Requires-Dist: fastapi>=0.110.0; extra == 'webhook'
Requires-Dist: openai>=1.0.0; extra == 'webhook'
Requires-Dist: uvicorn[standard]>=0.29.0; extra == 'webhook'
Description-Content-Type: text/markdown

# qa-gentic-stlc-agents

> Six MCP servers covering the full QA Software Test Life Cycle — test cases, Gherkin BDD, self-healing Playwright code, Helix-QA file writing, Jira Cloud integration, and one-shot migration (`stlc-migrate`) of existing Playwright projects into the Helix-QA layout. Browser interaction via Playwright MCP. Silent MSAL OAuth against Azure DevOps; OAuth 2.0 (3LO) for Jira Cloud.

[![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 six 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** or **Jira Cloud**, plus a one-shot `stlc-migrate` CLI for converting existing Playwright projects into the Helix-QA layout.

Both pipelines run the same end-to-end flow: fetch issue → analyse acceptance criteria → create test cases → generate Gherkin → generate Playwright TypeScript → write Helix-QA files. The ADO pipeline uses `qa-test-case-manager` as its entry point; the Jira pipeline uses `qa-jira-manager`. Agents 2–4 (`qa-gherkin-generator`, `qa-playwright-generator`, `qa-helix-writer`) are shared by both.

**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 **and/or** Jira Cloud site
- A `.env` file with ADO and/or Jira credentials (see [Configuration](#configuration))

---

## MCP Servers Installed

`pip install qa-gentic-stlc-agents` places six executable MCP server scripts plus the migration CLI 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 or Jira work item → 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 |
| `qa-jira-manager` | `qa-jira-manager` | Jira issue → test cases in Jira → Gherkin → Playwright → Helix-QA |
| `qa-migration` | `qa-migration` | Existing Playwright project → fully agent-ready Helix-QA tree (also exposed as `stlc-migrate` CLI) |

A seventh script, `qa-stlc-webhook` (optional, requires `pip install qa-gentic-stlc-agents[webhook]`), runs the FastAPI webhook bridge that drives the pipeline headlessly from ADO Service Hooks or Jira Webhooks.

All MCP 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_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 → ⛔ Not supported — warn user; ask for a Feature or PBI/Bug ID
- 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>` |

---

### `qa-migration` / `stlc-migrate`

One-shot conversion of an existing Playwright project (with or without Cucumber) into a fully agent-ready Helix-QA tree — page objects + locator files in `{selector, intent, stability}` form, healer wiring, agent skills, `.mcp.json`, and `MIGRATION-REPORT.md`.

```bash
stlc-migrate --source ./my-old-tests --helix ./helix-qa --dry-run
stlc-migrate --source ./my-old-tests --helix ./helix-qa --integration both
stlc-migrate --source ./my-old-tests --helix ./helix-qa --conflict overwrite
stlc-migrate --source ./my-old-tests --helix ./helix-qa --preserve-tree
stlc-migrate --source ./my-old-tests --helix ./helix-qa --features=vrt
```

| Flag | Description |
|---|---|
| `--integration ado\|jira\|both` | Which agent skills + MCP entries to install (default `both`). |
| `--conflict overwrite\|skip\|interactive` | Existing-file handling (default `interactive`). `overwrite` also removes orphans in role dirs the migration owns. |
| `--preserve-tree` | Mirror the source's subfolder grouping under `src/test/features/`, `src/test/steps/`, `src/pages/`, `src/locators/`. Default flattens. |
| `--features=vrt` | Scaffold Visual Regression Testing assets (`vrtCapture` / `vrtReport` utils, `vrt.steps.ts`, `vrt:baseline` / `vrt:test` npm scripts, `pngjs` / `pixelmatch` / `fs-extra` deps). Auto-enabled when the source has any `vrt:*` script or `VRT_MODE` in an `.env`. |
| `--dry-run`, `--json` | Preview + machine-readable output. |

The full pipeline reference is in `skills/migrate-framework/SKILL.md`.

---

## Authentication

### Azure DevOps (ADO pipeline)

The four ADO agents 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
```

### Jira Cloud (Jira pipeline)

`qa-jira-manager` uses Atlassian OAuth 2.0 (3LO). On first run, a browser opens once for sign-in. The token is cached at `~/.jira-cache/jira-token.json` and silently refreshed for ~60 days.

Required `.env` vars:
```
JIRA_CLIENT_ID=your-atlassian-oauth-client-id
JIRA_CLIENT_SECRET=your-atlassian-oauth-client-secret
JIRA_CLOUD_ID=your-atlassian-cloud-id
```

**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
# ── Azure DevOps (ADO pipeline) ───────────────────────────────────────────────
ADO_ORGANIZATION_URL=https://dev.azure.com/your-org
ADO_PROJECT_NAME=YourProject
ADO_PAT=your-personal-access-token

# ── Jira Cloud (Jira pipeline) ────────────────────────────────────────────────
JIRA_CLIENT_ID=your-atlassian-oauth-client-id
JIRA_CLIENT_SECRET=your-atlassian-oauth-client-secret
JIRA_CLOUD_ID=your-atlassian-cloud-id
# Optional — defaults to http://localhost:8765/callback
# JIRA_REDIRECT_URI=http://localhost:8765/callback

# ── Shared (browser-based test execution) ────────────────────────────────────
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 → **attribute (intent-shape-aware)** → type-hint → role → label → text → AI Vision. The attribute strategy constrains its substring matches with a CSS `:is(input, textarea, …)` prefix derived from the intent — so a `password` intent can only match `<input>`/`<textarea>`/`<select>`/`[contenteditable]`, never `<a id="forgot-password">`. 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-ado    # create .venv + pip install -e . (ADO pipeline next steps)
make install-jira   # create .venv + pip install -e . (Jira pipeline next steps)
make install-both   # create .venv + pip install -e . (both pipelines)
make test           # pytest tests/ -v
make verify-ado     # check ADO agents + MSAL auth
make verify-jira    # check Jira agents + OAuth token cache
```

---

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