Metadata-Version: 2.4
Name: qa-stlc-agents
Version: 1.0.1
Summary: Three MCP agents covering the full QA Software Test Life Cycle — test cases, Gherkin BDD, and self-healing Playwright code. Browser interaction at generation time via Playwright MCP. Silent MSAL OAuth against Azure DevOps.
Project-URL: Homepage, https://github.com/your-org/qa-stlc-agents
Project-URL: Documentation, https://github.com/your-org/qa-stlc-agents#readme
Project-URL: Repository, https://github.com/your-org/qa-stlc-agents
Project-URL: Issues, https://github.com/your-org/qa-stlc-agents/issues
License: MIT
Keywords: azure-devops,bdd,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 STLC Agents

**QA automation for AI agents and humans.**

Three MCP agents covering the full Software Test Life Cycle — from Azure DevOps work item
to self-healing Playwright tests. Each agent exposes a focused set of tools and a skill file
that teaches a coding agent (Claude Code, GitHub Copilot, Gemini CLI) exactly how to use them.

```
qa-test-case-manager     → ADO work item → test cases created and linked in ADO
qa-gherkin-generator     → ADO Feature → BDD .feature file attached to Feature WI
qa-playwright-generator  → Gherkin → page object + step defs + self-healing infrastructure
```

A fourth MCP server — **Playwright MCP** (`github.com/microsoft/playwright-mcp`) — handles
browser interaction at code-generation time, replacing manual locator authoring with
accessibility-tree-derived, zero-hallucination selectors.

---

## Quick Start

```bash
# 1. Install all three QA STLC agents
pip install qa-stlc-agents

# 2. Start Playwright MCP (required for live locator verification)
npx @playwright/mcp@latest --port 8931

# 3. Install skills into your coding agent
./scripts/install-skills.sh               # Claude Code
./scripts/install-skills.sh vscode        # VS Code / GitHub Copilot

# 4. Generate .mcp.json for Claude Code (includes playwright entry)
python3 scripts/generate-mcp-config.py

# 5. Restart your MCP client — all four servers are ready
```

---

## Authentication

All three QA STLC agents share `~/.msal-cache/msal-cache.json` — the same token cache used by
`microsoft/azure-devops-mcp`. **No sign-in UI is shown anywhere.**

| Situation | What happens |
|---|---|
| Signed in to VS Code with Microsoft account | Silent — zero prompts |
| Ran `az login` or signed in via another MCP server | Silent — token reused |
| No cached token | Browser opens **once**, token cached ~90 days |
| CI/CD (service principal) | Set `AZURE_CLIENT_ID` + `AZURE_CLIENT_SECRET` + `AZURE_TENANT_ID` |

---

## MCP Configuration

### 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"
    },
    "playwright": {
      "type": "url",
      "url": "ws://localhost:8931"
    }
  }
}
```

Generate this automatically with correct paths:
```bash
python3 scripts/generate-mcp-config.py
```

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

```bash
python3 scripts/generate-mcp-config.py --vscode
```

---

## Agent Tools

### Test Case Manager — `qa-test-case-manager`

| Tool | Description |
|---|---|
| `fetch_work_item` | Fetch PBI/Bug with acceptance criteria, coverage hints, existing TC count |
| `create_and_link_test_cases` | Create TCs with XML steps in ADO, link via TestedBy-Forward |
| `get_linked_test_cases` | List TCs already linked to a work item |

**Skill:** `skills/generate-test-cases.md`

### Gherkin Generator — `qa-gherkin-generator`

| Tool | Description |
|---|---|
| `fetch_feature_hierarchy` | Feature + child PBIs + linked TCs with steps + best-practice example |
| `attach_gherkin_to_feature` | Upload .feature file and attach to Feature work item |

**Skill:** `skills/generate-gherkin.md`

### Playwright Generator — `qa-playwright-generator`

| Tool | Description |
|---|---|
| `generate_playwright_code` | Gherkin + context_map → locators.ts + page object + step defs + cucumber profile |
| `scaffold_locator_repository` | Generate all 6 self-healing infrastructure files (once per project) |
| `attach_code_to_work_item` | Attach generated .ts files to an ADO work item |
| `validate_gherkin_steps` | Parse .feature file → list all unique step strings |

**Skill:** `skills/generate-playwright-code.md`

### Playwright MCP — `playwright` (external)

Used by the coding agent at code-generation time to drive a real browser and derive
verified locators from the live accessibility tree — zero hallucinated selectors.

| Tool | Used for |
|---|---|
| `browser_navigate` | Navigate to login pages and feature screens |
| `browser_snapshot` | Get accessibility tree — source of locator derivation |
| `browser_fill` | Fill form fields (login, filters) |
| `browser_click` | Click navigation items and buttons |
| `browser_wait_for_url` | Wait for post-login or post-action navigation |
| `browser_wait_for_timeout` | Hard wait for dynamic content |

Start before running any generation workflow:
```bash
npx @playwright/mcp@latest --port 8931
# headless CI: npx @playwright/mcp@latest --headless --port 8931
```

---

## Self-Healing

The Playwright Generator produces page objects where **every interaction goes through
`LocatorHealer`**, never raw Playwright calls. When a locator breaks, an 8-strategy
healing chain runs automatically:

```
1. Cached healed selector from LocatorRepository    (instant — zero overhead)
2. Primary CSS/data-testid selector
3. page.getByRole() — intent keywords
4. page.getByLabel() — intent string
5. page.getByText() — partial match
6. playwright-cli snapshot → Claude AI Vision → selector persisted for future runs
7. DevToolsHealer.findByAxName() — CDPSession accessibility tree search (no AI cost)
8. DevToolsHealer.findByBoundingBox() — CDPSession spatial search at last known coordinates
```

Beyond locator healing, two additional layers run in parallel:

**Timing Healing** — `TimingHealer` intercepts network traces per action. When an API
drifts beyond 20% of its baseline duration (e.g. 300ms → 900ms), the timeout is
auto-adjusted for the current run and a suggestion is queued for engineer review.

**Visual Regression** — `VisualIntentChecker` captures element screenshots at key
assertions and diffs them against approved baselines. Catches regressions where an
element is found but looks wrong — wrong colour, truncated text, overlapped by
another element.

All AI-generated healing suggestions are reviewed in **HealingDashboard** at
`http://localhost:7890` before being permanently committed to the repository.

---

## Playwright MCP — Live Locator Verification (Step 0)

Before generating code, Playwright MCP drives a real browser to build a verified
locator map with zero hallucinated selectors.

Start Playwright MCP, then the coding agent:

1. Navigates to the login screen via `browser_navigate`
2. Snapshots the accessibility tree via `browser_snapshot`
3. Fills credentials and clicks login via `browser_fill` / `browser_click`
4. Waits for post-login URL via `browser_wait_for_url`
5. Navigates to each feature screen and snapshots its accessibility tree
6. Maps AX nodes to locators using the stability ranking:
   `data-testid (100) > aria-role+name (90) > id (80) > aria-label (70) > placeholder (60)`

Pass the resulting `context_map` to `generate_playwright_code` and every locator in
`locators.ts` is guaranteed to match a real element in the live DOM.

---

## Skills

Skills are Markdown files that teach a coding agent the full workflow for each STLC phase.
Install once per project:

```bash
./scripts/install-skills.sh         # Claude Code → .claude/skills/
./scripts/install-skills.sh vscode  # VS Code → .github/copilot-instructions/
```

Once installed, just ask your coding agent:

> *"Generate test cases for work item #12345 in MyProject at https://dev.azure.com/myorg"*

The agent reads the skill, calls `fetch_work_item`, designs test cases following the
granularity rules, then calls `create_and_link_test_cases` — all in one shot.

---

## Full End-to-End Workflow

```
User prompt:
  "Generate test cases, Gherkin, and Playwright automation for work item #12345
   in MyProject at https://dev.azure.com/myorg, using the live app at
   http://localhost:4200"

Coding agent (reads all 3 skills, calls tools in sequence):

  [Step 0 — Playwright MCP locator verification (requires Playwright MCP running)]

  playwright:browser_navigate + browser_snapshot → login screen
  playwright:browser_fill + browser_click → authenticate
  playwright:browser_wait_for_url → confirmed post-login

  playwright:browser_navigate + browser_snapshot (per feature screen)
    → accessibility tree nodes → context_map
    → stability: data-testid (100) > aria-role+name (90) > id (80) > aria-label (70)

  [Step 1 — Test Cases]
  qa-test-case-manager::fetch_work_item(12345, ...)
    → returns AC, coverage hints, existing TC count

  qa-test-case-manager::create_and_link_test_cases(...)
    → creates TCs in ADO with XML steps, links to WI #12345

  [Step 2 — Gherkin]
  qa-gherkin-generator::fetch_feature_hierarchy(parent_feature_id, ...)
    → Feature + child PBIs + existing TCs + best-practice Gherkin example

  qa-gherkin-generator::attach_gherkin_to_feature(...)
    → .feature file attached to Feature work item

  [Step 3 — Playwright Code]
  qa-playwright-generator::scaffold_locator_repository(...)
    → LocatorHealer.ts + LocatorRepository.ts + TimingHealer.ts +
      VisualIntentChecker.ts + DevToolsHealer.ts + HealingDashboard.ts

  qa-playwright-generator::generate_playwright_code(gherkin_content, context_map, ...)
    → locators.ts + {Feature}.page.ts + steps.ts + cucumber.js profile

  qa-playwright-generator::validate_gherkin_steps(gherkin_content)
    → confirms all steps have implementations

  qa-playwright-generator::attach_code_to_work_item(...)
    → .ts files attached to WI for traceability
```

---

## Installing from Source

```bash
git clone https://github.com/your-org/qa-stlc-agents
cd qa-stlc-agents
make install          # create .venv, pip install -e .
make skills           # copy skills to .claude/skills/
make verify           # check MSAL auth status
make test             # run test suite
```

---

## Optional Environment Variables

```bash
AZURE_TENANT_ID=your-entra-tenant-id    # pin to specific tenant
AZURE_CLIENT_ID=your-client-id          # custom app registration
                                         # (default: Azure CLI — no registration needed)
HEALING_DASHBOARD_PORT=7890             # HealingDashboard port (set to 0 to disable)
PLAYWRIGHT_MCP_PORT=8931                # port where playwright-mcp is listening
```

Copy `.env.example` to `.env` and uncomment as needed.

---

## CI/CD

```json
{
  "mcpServers": {
    "qa-test-case-manager": {
      "command": "/path/.venv/bin/qa-test-case-manager",
      "env": {
        "AZURE_CLIENT_ID": "${AZURE_CLIENT_ID}",
        "AZURE_CLIENT_SECRET": "${AZURE_CLIENT_SECRET}",
        "AZURE_TENANT_ID": "${AZURE_TENANT_ID}"
      }
    },
    "qa-gherkin-generator": {
      "command": "/path/.venv/bin/qa-gherkin-generator",
      "env": {
        "AZURE_CLIENT_ID": "${AZURE_CLIENT_ID}",
        "AZURE_CLIENT_SECRET": "${AZURE_CLIENT_SECRET}",
        "AZURE_TENANT_ID": "${AZURE_TENANT_ID}"
      }
    },
    "qa-playwright-generator": {
      "command": "/path/.venv/bin/qa-playwright-generator",
      "env": {
        "AZURE_CLIENT_ID": "${AZURE_CLIENT_ID}",
        "AZURE_CLIENT_SECRET": "${AZURE_CLIENT_SECRET}",
        "AZURE_TENANT_ID": "${AZURE_TENANT_ID}",
        "HEALING_DASHBOARD_PORT": "0"
      }
    },
    "playwright": {
      "type": "url",
      "url": "ws://localhost:8931"
    }
  }
}
```

In CI, start Playwright MCP as a background service before the agent runs:
```bash
npx @playwright/mcp@latest --headless --port 8931 &
```

Setting `AZURE_CLIENT_SECRET` enables the service principal flow — the browser never
opens in CI/CD. Set `HEALING_DASHBOARD_PORT=0` to disable the dashboard HTTP server
in automated pipelines; suggestions are still written to `locator-repository.json`
for async review. Store secrets in GitHub Actions secrets or Azure Key Vault.

---

## Platform Support

| Platform | Status |
|---|---|
| macOS (Intel + Apple Silicon) | ✅ |
| Linux (x64) | ✅ |
| Windows (x64) | ✅ (Python 3.10+) |

---

## Documentation

| Document | Contents |
|---|---|
| `docs/architecture.md` | Component breakdown, healing chain diagrams, ADO data flow, design decisions |
| `docs/walkthrough.md` | Step-by-step end-to-end example with real tool calls and responses |

---

## License

MIT