@qa-gentic/stlc-agents 1.0.27 → 1.0.29

package/QUICKSTART-ADO.md

@@ -0,0 +1,400 @@
+# @qa-gentic/stlc-agents — Azure DevOps Quick Start
+
+> Azure DevOps pipeline: work item → test cases → Gherkin → Playwright TypeScript → Helix-QA.
+> For Jira Cloud see [QUICKSTART-JIRA.md](QUICKSTART-JIRA.md).
+
+
+Works with **GitHub Copilot** (VS Code Agent mode), **Claude Code**, **Cursor**, and **Windsurf**.
+
+[![npm version](https://img.shields.io/npm/v/@qa-gentic/stlc-agents)](https://www.npmjs.com/package/@qa-gentic/stlc-agents)
+[![PyPI version](https://img.shields.io/pypi/v/qa-gentic-stlc-agents)](https://pypi.org/project/qa-gentic-stlc-agents/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Node.js >=18](https://img.shields.io/badge/node-%3E%3D18-brightgreen)](https://nodejs.org)
+[![Python >=3.10](https://img.shields.io/badge/python-%3E%3D3.10-blue)](https://python.org)
+
+---
+
+
+## What It Does
+
+Six Python MCP servers cover the full QA Software Test Life Cycle. The ADO pipeline uses Agents 1–4 + the migration tool:
+
+| Agent | Input | Output |
+|---|---|---|
+| `qa-test-case-manager` | ADO PBI / Bug / Feature ID | Manual test cases created & linked via TestedBy-Forward |
+| `qa-gherkin-generator` | ADO 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 |
+| `qa-migration` / `stlc-migrate` | Existing Playwright project | Fully agent-ready Helix-QA tree — healer scaffold + skills + `.mcp.json` + BOILERPLATE infra |
+
+The Playwright MCP server (`http://localhost:8931/mcp`) is required for browser-driven code generation. It is not part of this package and must be started separately.
+
+---
+
+## Install
+
+### Greenfield (new Playwright + Cucumber + TypeScript project)
+
+```bash
+npm install -g @qa-gentic/stlc-agents
+qa-stlc init --vscode --integration ado
+```
+
+`qa-stlc init` performs:
+1. `pip install qa-gentic-stlc-agents` — installs all six Python MCP servers + `stlc-migrate` CLI
+2. Copies skill files to `.github/copilot-instructions/` (and `.claude/` if not `--vscode`)
+3. Writes `.vscode/mcp.json` with all six servers configured (Agents 1–4 + `qa-migration` + `playwright`)
+
+Start the Playwright MCP server before your first session:
+
+```bash
+npx @playwright/mcp@latest --port 8931
+```
+
+### Migrating an existing Playwright project
+
+```bash
+# Preview what would land in the target tree (writes nothing)
+stlc-migrate --source ./my-old-tests --helix ./helix-qa --dry-run
+
+# Full migration — installs every ADO agent skill + .mcp.json + healer scaffold
+stlc-migrate --source ./my-old-tests --helix ./helix-qa --integration ado
+
+# Refresh an already-migrated tree (picks up tool-side scaffold improvements)
+stlc-migrate --source ./my-old-tests --helix ./helix-qa --integration ado --conflict overwrite
+```
+
+After migration:
+
+```bash
+cd ./helix-qa
+npm install              # picks up dotenv, @types/fs-extra, etc.
+npx tsc --noEmit         # should be clean (any errors are source bugs preserved verbatim)
+npm test                 # healing fires on broken primary selectors and writes self-heals/healed-locators[.<env>].json
+npm run healix:dashboard # http://localhost:7890 — Confirm / Revert healed locators
+npm run healix:review    # http://localhost:7891 — read-only mirror (set HEALIX_REVIEW_PORT to enable)
+```
+
+See `skills/migrate-framework/SKILL.md` for the full migration pipeline + every healing env var.
+
+---
+
+
+## Requirements
+
+- Node.js ≥ 18
+- Python ≥ 3.10, < 3.14
+- Azure DevOps organisation with a `.env` containing:
+
+
+```env
+ADO_ORGANIZATION_URL=https://dev.azure.com/your-org
+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>] [--integration ado|jira|both]
+# Full bootstrap: pip install + skills + MCP config
+
+qa-stlc scaffold [--name <name>] [--dir <path>] [--no-install]
+# Copy full Playwright + Cucumber + TypeScript boilerplate to a new project directory
+
+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 six MCP servers are reachable
+
+stlc-migrate --source <existing> --helix <target> [--integration ado|jira|both] [--conflict overwrite|skip|interactive] [--dry-run] [--json]
+# Migrate an existing Playwright (with or without Cucumber) project into the
+# Helix-QA layout. Installs every agent skill, .mcp.json, healer scaffold,
+# AGENT-BEHAVIOR.md, ORCHESTRATION_RULES.md, and the 11-file BOILERPLATE
+# allowlist (strategy / rules / apply / helpers / config). The enhanced
+# `LocatorHealer` / `LocatorRepository` / `TimingHealer` / `VisualIntentChecker`
+# / `HealingDashboard` / `dashboard-server` scaffolds always win over BOILERPLATE
+# on overlapping files (schema v1, debounced persist, dashboard write-back).
+```
+
+### Makefile shortcuts
+
+```bash
+make bootstrap-ado                                       # one-shot: skills + .mcp.json for the ADO pipeline
+make migrate-ado SOURCE=<old> HELIX=<new>                # ADO migration with sensible defaults
+make migrate-ado SOURCE=<old> HELIX=<new> CONFLICT=overwrite   # re-migrate in place
+make audit-migration HELIX=<new>                         # framework_state + skills + healer scaffold + heal-store report
+```
+
+---
+
+## Usage
+
+
+Open your AI coding agent and use natural language:
+
+```
+# Generate test cases
+Generate test cases for work item #12345 in MyProject at https://dev.azure.com/myorg
+
+# Generate Gherkin BDD
+Generate a Gherkin regression suite for Feature #11000 in MyProject at https://dev.azure.com/myorg
+
+# Generate Playwright code (requires Playwright MCP running)
+Generate Playwright TypeScript for the Gherkin I just created. The login page is at /auth/login
+
+# Write to Helix-QA project
+Write the generated files to my Helix-QA project at /workspace/my-qa-project
+```
+
+---
+
+## 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_feature_hierarchy` | Fetch a Feature and all child PBIs/Bugs with acceptance criteria and existing attachments. |
+| `fetch_work_item_for_gherkin` | Fetch a PBI or Bug with parent Feature context, suggested file name, and linked test case 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 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. |
+| `validate_gherkin_steps` | Check for duplicate step strings and missing `When` steps. |
+| `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` | Returns `framework_state` (`present` / `partial` / `absent`) and `recommendation`. |
+| `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. |
+
+### 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
+
+> For ADO-only installs `qa-jira-manager` is omitted. Run `qa-stlc mcp-config --integration ado` to generate manually, or run `stlc-migrate --integration ado` and the migration will emit `.mcp.json` automatically with absolute binary paths.
+
+### 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" },
+    "qa-migration":            { "command": "/path/to/.venv/bin/stlc-migrate" },
+    "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" },
+    "qa-migration":            { "command": "/path/to/.venv/bin/stlc-migrate" },
+    "playwright": { "command": "npx", "args": ["@playwright/mcp@latest", "--isolated"] }
+  }
+}
+```
+
+> 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/` | PBI / Bug / Feature → ADO manual test cases (ADO only) |
+| `generate-gherkin/` | Feature / PBI / Bug → validated `.feature` + ADO attach |
+| `generate-playwright-code/` | Gherkin + live browser → three-layer self-healing Playwright TypeScript |
+| `write-helix-files/` | Generated files → Helix-QA disk layout, scaffold or merge |
+| `deduplication-protocol/` | READ → DIFF → CREATE mandatory pre-flight gate |
+
+---
+
+
+## Three-Layer Self-Healing Architecture
+
+| Layer | Class | What it heals |
+|---|---|---|
+| 1 — Locator | `LocatorHealer` | 8-strategy chain: cached → primary → **attribute** → **type-hint** → role → label → text → AI Vision. After match, introspects the live element and persists a specific single-attribute selector (`#id`, `[data-testid=…]`, etc.) — never the search union. |
+| 2 — Timing | `TimingHealer` | network-trace drift → auto-adjusted timeouts → HealingDashboard |
+| 3 — Visual | `VisualIntentChecker` | element screenshot diff at assertions → HealingDashboard |
+
+Healed selectors persist in `LocatorRepository` under a schema-v1 envelope at
+`self-heals/healed-locators[.<ENV>].json` (heal-only filter, debounced writes,
+read-modify-write merge, history cap). `HEAL_STRATEGY_ORDER` reorders the chain
+at class-load time; `LOCATOR_HEAL_ATTEMPTS` caps strategy retries; `LOCATOR_TIMEOUT`
+caps each `ATTACH_TO` probe.
+
+**HealingDashboard** runs as two servers from the same process:
+- `http://localhost:7890` — read/write: Confirm rewrites the source `*.locators.ts` `selector:` field; Revert restores the previous selector.
+- `http://localhost:7891` — read-only mirror (set `HEALIX_REVIEW_PORT` to enable).
+
+All Confirm actions persist to the source locator file in version control. Refer to
+[ARCHITECTURE-ADO.md § Three-Layer Self-Healing Architecture](ARCHITECTURE-ADO.md#three-layer-self-healing-architecture)
+for full env-var tuning and the write-back protocol.
+
+---
+
+## 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"
+```
+
+---
+
+
+## Scaffold a New QA Project
+
+The `scaffold` command copies the full Playwright + Cucumber + TypeScript boilerplate framework — including three-layer AI self-healing, BDD templates, and CI/CD integration — into a new project directory.
+
+```bash
+# Scaffold into ./my-qa-project (default name)
+qa-stlc scaffold
+
+# Custom project name and location
+qa-stlc scaffold --name acme-e2e --dir /path/to/workspace/acme-e2e
+
+# Skip npm install (e.g. to inspect files first)
+qa-stlc scaffold --name acme-e2e --no-install
+```
+
+After scaffolding:
+
+```bash
+cd my-qa-project
+npx playwright install chromium     # install browser binaries
+cp .env.example .env                # already done by scaffold
+# Edit .env — set BASE_URL and optionally AI_API_KEY
+npm test                            # run the example scenario
+```
+
+### What Gets Scaffolded
+
+| Layer | Contents |
+|---|---|
+| **Config** | `package.json`, `tsconfig.json`, `cucumber.js`, `.env.example`, `.gitignore` |
+| **CI/CD** | `Dockerfile`, `docker-compose.yml`, `azure-pipelines.yml` |
+| **Framework** | `src/hooks/`, `src/pages/BasePage.ts`, `src/locators/`, `src/config/` |
+| **Self-healing** | `LocatorHealer` (8-strategy chain), `LocatorRepository` (schema v1 envelope, heal-only filter), `TimingHealer`, `VisualIntentChecker`, `HealingDashboard` (write-back to source), `dashboard-server` (launcher for `npm run healix:dashboard` / `healix:review`). |
+| **AI utilities** | `AILocatorGenerator`, `AISelfHealing`, `AITestGenerator` |
+| **Auth** | `AuthManager`, `AuthSetup` |
+| **Templates** | `_template.feature`, `_template.locators.ts`, `_template.steps.ts`, `_TemplatePage.ts` |
+| **Example test** | `src/test/features/example.feature` + steps |
+
+### Healing Dashboard
+
+`npm run healix:dashboard` launches a single process that serves both:
+
+```bash
+npm run healix:dashboard          # http://localhost:7890 — Confirm / Revert (rewrites source *.locators.ts)
+HEALIX_REVIEW_PORT=7891 npm run healix:dashboard   # also serves http://localhost:7891 read-only mirror
+```
+
+Confirm on any healed entry writes the persisted single-attribute selector back to
+the source `*.locators.ts` `selector:` field in version control — no separate
+"promote to source" or CI step required.
+
+---
+
+
+## Development
+
+```bash
+make install-ado      # create .venv + pip install -e . (prints ADO next steps)
+make install-jira     # create .venv + pip install -e . (prints Jira next steps)
+make install-both     # create .venv + pip install -e . (prints Both next steps)
+make test             # run pytest tests/ -v
+make skills-ado       # install ADO skill files to .claude/skills/ + copilot-instructions/
+make skills-jira      # install Jira skill files
+make skills-both      # install all skill files
+make verify-ado       # check ADO agents + MSAL auth
+make verify-jira      # check Jira agents + OAuth token cache
+make mcp-config-ado   # write .vscode/mcp.json for ADO pipeline
+make mcp-config-jira  # write .vscode/mcp.json for Jira pipeline
+make mcp-config-both  # write .vscode/mcp.json for both pipelines
+make clean            # remove .venv, __pycache__, dist
+```
+
+---
+
+
+## Documentation
+
+- [Quick Start: Azure DevOps](QUICKSTART-ADO.md)
+- [Quick Start: Jira Cloud](QUICKSTART-JIRA.md)
+- [Architecture: ADO](ARCHITECTURE-ADO.md)
+- [Architecture: Jira](ARCHITECTURE-JIRA.md)
+- [Walkthrough: ADO](WALKTHROUGH-ADO.md)
+- [Walkthrough: Jira](WALKTHROUGH-JIRA.md)
+
+---
+
+
+## License
+
+MIT