@qa-gentic/stlc-agents 1.0.27 → 1.0.29

package/skills/migrate-framework/SKILL.md

@@ -0,0 +1,207 @@
+# Skill: migrate-framework
+
+Migrate an existing Playwright test framework into the Helix-QA layout so every
+QA STLC agent (qa-test-case-manager, qa-gherkin-generator, qa-playwright-generator,
+qa-helix-writer, qa-jira-manager) can operate against it. The migration ships
+self-healing locator infrastructure, an HTTP healing dashboard, agent skill
+files, an `.mcp.json`, and every other asset the agents expect.
+
+## When to use this skill
+
+Trigger on any of:
+- "migrate my Playwright tests"
+- "convert existing tests to Helix"
+- "migrate playwright+cucumber project"
+- "bring old tests into the agent framework"
+- "stlc-migrate", "qa-migration", "migrate_framework" tool names
+
+## Supported source frameworks
+
+| Framework | Detection |
+|-----------|-----------|
+| Plain Playwright JS | `playwright.config.js`, no `.feature` files |
+| Plain Playwright TS | `playwright.config.ts`, no `.feature` files |
+| Playwright + Cucumber JS | `playwright.config.js` + `.feature` files or `@cucumber/cucumber` in package.json |
+| Playwright + Cucumber TS | `playwright.config.ts` + `.feature` files or `@cucumber/cucumber` in package.json |
+
+## Step-by-step workflow
+
+### Step 1 — Confirm source and target directories
+
+Ask the user for:
+- **Source directory** — root of the existing Playwright project (must exist)
+- **Helix root** — root of the Helix-QA project to migrate into (must exist unless dry-run)
+- **Integration** (optional) — `ado`, `jira`, or `both` (default `both`). Controls which agent skills + MCP entries get installed.
+
+### Step 2 — Detect the framework
+
+```
+detect_framework(source_dir=<source>)
+```
+
+Report back:
+- `framework` — one of: `playwright-bdd-ts`, `playwright-bdd-js`, `playwright-ts`, `playwright-js`
+- `language` — `typescript` or `javascript`
+- `bdd` — whether BDD/Cucumber files were found
+- `file_counts` — number of `.ts`, `.js`, `.feature` files found
+
+### Step 3 — Preview the migration plan
+
+```
+preview_migration(source_dir=<source>, helix_root=<helix>)
+```
+
+Show the user:
+- Total mappable files and their roles
+- Any conflicts (files already existing in Helix)
+- Files with unknown/unrecognised roles that will be skipped
+
+Ask the user to confirm before proceeding if there are conflicts.
+
+### Step 4 — Run the migration
+
+```
+migrate_framework(
+  source_dir=<source>,
+  helix_root=<helix>,
+  conflict_strategy="interactive",   # "overwrite" | "skip" | "interactive"
+  integration="both",                # "ado" | "jira" | "both"
+  dry_run=false,
+)
+```
+
+The tool applies this pipeline to each file:
+
+| Step | What happens |
+|------|-------------|
+| **JS → TS** | `require(...)` → `import`, `module.exports` → `export default`, async return types added |
+| **Locator modernisation** | `[data-testid]` → `getByTestId`, `text=` → `getByText`, `[aria-label]` → `getByLabel`, `[placeholder]` → `getByPlaceholder`, `role=X[name=Y]` → `getByRole`. Complex XPath/CSS flagged with `// TODO`. **Multi-line string-concat selectors** (`"a" + "b"`) are registered as a single `{selector, intent, stability}` entry preserving the concatenation. |
+| **Healer injection** | EVERY locator interaction (regardless of caller shape) is routed through `_healer.clickWithHealing` / `_healer.fillWithHealing` / `_healer.assertVisibleWithHealing`. Covered patterns: raw `page.click/fill`, chained `page.locator(X).click()`, custom wrappers (`base.waitAndClick`, `base.waitAndFill`, `*ByTestId` variants), non-awaited calls inside `Promise.all([...])`, `currentFixture.page.*` receivers, aliased references (`this.Elements.foo`, `const E = fooLocators`), inline class-field locator dictionaries (`private MassInviteElements = { ... }`), and dynamic selectors (auto-wrapped with `dyn.<prefix>.<n>` keys). Arguments are extracted by **balanced-paren scan** so calls like `fill(X, String(visitorCount))` extract the full second arg. |
+| **Locator registration** | Every page-object constructor gets `Object.entries(xxxLocators).forEach(([k, v]) => { this._repo.register(\`xxxPage.${k}\`, ...); this._repo.register(k, ...); })` so the runtime store knows about every key. Registers under both **namespaced** and **bare** key conventions so legacy hand-written `_healer.<…>("usernameInput", …)` and freshly-emitted `_healer.<…>("loginPage.usernameInput", …)` both resolve. |
+| **Import fixing** | Relative imports remapped to the **mapper's authoritative target paths** (no more "predicted" alias names that don't match what was actually written). Source-project `@pages/scweb/locators` → `@locators/locators.locators` exactly as the mapper renamed it. |
+| **Spec → BDD** | See "Zero-inference guarantees" below. |
+| **Config merge** | `playwright.config` settings merged. `cucumber.js` is rewritten with `dotenv/config` injected as the FIRST `requireModule` entry — so `.env` is loaded before any TS file is compiled. `package.json` gets `dotenv` runtime dep, `@types/*` companions for known JS-only deps (fs-extra, lodash, glob, mkdirp, rimraf, uuid, js-yaml, jsonwebtoken, module-alias, cookie, express, cors, node-fetch, minimist, yargs, semver), and two new scripts: `healix:dashboard` and `healix:review`. |
+| **tsconfig merge** | Adds path aliases (`@pages`, `@steps`, `@features`, `@locators`, `@hooks`, `@helper`, `@utils`, `@config`). Does **not** fabricate `strict: true` / `strictNullChecks` — the source's strictness setting is preserved verbatim (introducing strictness the source didn't have would surface cascading errors on code that compiled fine before). |
+
+#### Zero-inference guarantees for spec → BDD
+
+The converter is intentionally **lossless** and **non-fabricating**:
+
+- **No generic step text.** Step text is always the literal `test()` name (prefixed with the file slug for cross-file uniqueness). The tool does NOT invent `"I run step #N"`, `"I prepare state #N"`, or `"I execute if block #N"` text.
+- **One step per test.** The full original body of each `test('name', body)` is placed inside a single step definition. No per-statement splitting; no Given/When/Then reclassification.
+- **Hooks become real Cucumber hooks.** `test.beforeEach`/`afterEach`/`beforeAll`/`afterAll` → real `Before`/`After`/`BeforeAll`/`AfterAll`. `test.skip`/`only`/`fixme`/`fail`/`slow` modifiers → `@skip`/`@only`/… tags on the scenario.
+- **Nothing is dropped.** Module-level helpers, suite-scope `let`/`const`/`var`, comments, and hook bodies are all preserved. `test.use(...)`/`test.step(...)` and other runner-only calls are commented out as `// MIGRATION TODO:` rather than silently removed.
+- **Source bugs surface, not papered over.** If the original source references a non-existent property (e.g. `GlobalVars.Api.Username` when the class only exposes `username`), the migrated step keeps the original reference. `tsc` will flag it; the tool does not "fix" what it cannot verify.
+- **Step text with `/`, `(`, `)`, `{`, `}`** is rendered as a RegExp step definition automatically so Cucumber Expression parsing doesn't reject the test name.
+
+### Step 5 — Scaffold & assets installed automatically
+
+In addition to file-by-file migration, the tool emits a complete agent-ready
+tree:
+
+| Asset | What it does |
+|---|---|
+| `src/utils/locators/LocatorHealer.ts` | 8-strategy healing chain: cached-healed → primary → **attribute** → **type-hint** → role → label → text → AI Vision. After each successful strategy, the matched element is introspected and the **specific stable selector** (data-testid > id > name > placeholder > aria-label > autocomplete > input[type]) is persisted — not the search union. Strategy order tunable via `HEAL_STRATEGY_ORDER` CSV. |
+| `src/utils/locators/LocatorRepository.ts` | Heal store: schema v1 envelope (`{_version, _writtenAt, entries}`), heal-only persist filter (baseline-only entries don't get written), debounced writes (500ms), singleton process exit hook, read-modify-write merge for multi-instance safety, ENV-suffixed file path (`healed-locators.qa4.json` when ENV=qa4), capped `healingHistory` (default 50, env-tunable). |
+| `src/utils/locators/TimingHealer.ts` / `VisualIntentChecker.ts` | Network-trace timing healer + visual-regression checker. |
+| `src/utils/locators/HealingDashboard.ts` | Two-server HTTP UI. Primary at `HEALING_DASHBOARD_PORT` (default 7890) has Healed-locators + Pending-suggestions tables with Confirm/Revert / Approve/Reject buttons. Read-only mirror at `HEALIX_REVIEW_PORT` (opt-in, default 0). Auto-discovers all sibling heal-store files in the directory (so `healix:dashboard` without an ENV picks up `*.qa4.json` automatically). **Confirm on a healed entry writes the healed selector back to the locator `.ts` file** so the next run uses it as the primary. |
+| `src/utils/locators/dashboard-server.ts` | Standalone launcher for the dashboard. Wired via `healix:dashboard` and `healix:review` npm scripts. |
+| `src/utils/locators/{ElementContextHelper, HealApplicator, LocatorRules, LocatorStrategy, healix-ci-apply, review-server}.ts` | Filled from `agent_helix_writer.tools.boilerplate.BOILERPLATE` — purely additive infrastructure that integrates with the enhanced LocatorHealer. |
+| `src/utils/helpers/{Logger, RetryHandler, WaitHelper}.ts` | Filled from BOILERPLATE — helpers the strategy layer depends on. |
+| `src/config/environment.ts` | Filled from BOILERPLATE — referenced by Logger. |
+| `src/locators/base.locators.ts` | Filled from BOILERPLATE — base locator file. |
+| `.claude/skills/<name>/SKILL.md` + `.github/copilot-instructions/<name>.md` | Per-integration skill files (ado / jira / both). |
+| `AGENT-BEHAVIOR.md` + `ORCHESTRATION_RULES.md` | Copied to project root, `.claude/`, and `.github/copilot-instructions/`. |
+| `.mcp.json` | Auto-generated entries for every agent + Playwright MCP, with absolute binary paths. |
+| `.env.example` | Documents every healing env var: `HEAL_STORE_PATH`, `HEAL_LOG_PATH`, `HEAL_LOG_DISABLED`, `ENABLE_LOCATOR_VERSIONING`, `HEAL_HISTORY_CAP`, `LOCATOR_TIMEOUT`, `LOCATOR_HEAL_ATTEMPTS`, `HEAL_STRATEGY_ORDER`, `HEALING_DASHBOARD_PORT`, `HEALIX_REVIEW_PORT`, `ENABLE_AI_HEALING`, `AI_HEALING_PROVIDER`, `AI_HEALING_API_KEY`, `ENV` / `HELIX_ENV`. |
+
+### Step 6 — Review the migration report
+
+The tool writes `MIGRATION-REPORT.md` to the Helix root. Report back to the user:
+- Number of files written / skipped / conflicted
+- TODO count (locators needing manual review)
+- Path to `MIGRATION-REPORT.md`
+
+### Step 7 — Post-migration steps (tell the user)
+
+After migration, the user should:
+
+1. `npm install` — picks up new deps (`dotenv`, `@types/fs-extra`, etc.).
+2. `npx tsc --noEmit` — should be clean (any remaining errors are source bugs the migration preserved verbatim per the zero-inference contract).
+3. Review `// TODO: convert to getByRole` comments in locator files (complex XPath/CSS the tool wouldn't auto-rewrite).
+4. Fill in `.env` — at minimum, set `HEADLESS=false` if you want a visible browser.
+5. Verify `inspect_helix_project` reports `framework_state: "present"` against the migrated tree.
+6. Run the existing test suite (e.g. `npm test`) — healing fires automatically on broken primary selectors and writes to `self-heals/healed-locators[.<env>].json`.
+7. Inspect heals visually:
+   - `npm run healix:dashboard` → http://localhost:7890 (full UI with Confirm / Revert)
+   - `npm run healix:review`    → http://localhost:7891 (read-only mirror)
+8. When ready, click **Confirm** on a heal — the migration rewrites the source locator file's `selector:` field with the verified healed value. Future runs use it as the primary; the healing chain only fires if the page changes again.
+
+## Helix-QA file layout
+
+| Source role | Helix target |
+|-------------|-------------|
+| Locators (`*Locators.ts`, `*selectors.ts`) | `src/locators/<kebab>.locators.ts` |
+| Page objects (`*Page.ts`, `*.page.ts`) | `src/pages/<kebab>.page.ts` |
+| Step definitions (`*.steps.ts`, `step_definitions/**`) | `src/test/steps/<kebab>.steps.ts` |
+| Feature files (`*.feature`) | `src/test/features/<kebab>.feature` |
+| Playwright config | `playwright.config.ts` (merged) |
+| Cucumber config | `config/cucumber.js` (merged, with `dotenv/config` injected) |
+| Heal-store JSON | `self-heals/healed-locators[.<env>].json` (heal-only) |
+| Heal audit log | `self-heals/heal.log` (tab-separated `timestamp / key / strategy / selector`) |
+
+## CLI usage (terminal)
+
+```bash
+# Preview migration without writing
+stlc-migrate --source ./my-old-tests --helix ./helix-qa --dry-run
+
+# Full migration (interactive conflict handling, every agent reachable)
+stlc-migrate --source ./my-old-tests --helix ./helix-qa
+
+# ADO-only integration (no Jira skill / MCP entry)
+stlc-migrate --source ./my-old-tests --helix ./helix-qa --integration ado
+
+# Jira-only
+stlc-migrate --source ./my-old-tests --helix ./helix-qa --integration jira
+
+# Overwrite all existing files (refreshes scaffold + skill files)
+stlc-migrate --source ./my-old-tests --helix ./helix-qa --conflict overwrite
+
+# JSON output for scripting
+stlc-migrate --source ./my-old-tests --helix ./helix-qa --json
+
+# Makefile shortcut
+make migrate-preview SOURCE=./my-old-tests HELIX=./helix-qa
+```
+
+## Runtime environment variables
+
+Every knob has a sensible default. Override per-run in `.env` or via `cross-env` in npm scripts.
+
+| Variable | Default | Effect |
+|---|---|---|
+| `HEAL_STORE_PATH` | `./self-heals/healed-locators.json` | Where the heal-store JSON is read/written. |
+| `HEAL_LOG_PATH` | sibling `heal.log` | Tab-separated audit log per heal. |
+| `HEAL_LOG_DISABLED` | `false` | Set `true` to skip the audit log. |
+| `ENV` / `HELIX_ENV` | unset | When set, auto-suffixes the heal-store path: `healed-locators.qa4.json`. |
+| `ENABLE_LOCATOR_VERSIONING` | `true` | When `false`, keeps only the latest heal entry (no `healingHistory[]` accumulation). |
+| `HEAL_HISTORY_CAP` | `50` | Max heals retained per locator. `0` = unlimited. |
+| `LOCATOR_TIMEOUT` | `3000` | Per-strategy attach-probe timeout (ms). |
+| `LOCATOR_HEAL_ATTEMPTS` | `0` (unlimited) | Bound on the total number of probes before AI Vision fallback. |
+| `HEAL_STRATEGY_ORDER` | `attribute,type-hint,role,label,text` | CSV — omit names to disable; reorder to prioritise. |
+| `HEALING_DASHBOARD_PORT` | `7890` | Dashboard server port. `0` to disable. |
+| `HEALIX_REVIEW_PORT` | `0` (disabled) | Read-only review server port (rejects POSTs with 403). |
+| `ENABLE_AI_HEALING` | `true` | When `false`, AI Vision strategy is skipped. |
+| `AI_HEALING_PROVIDER` | `anthropic` | One of `anthropic` / `copilot` / `claude-code`. |
+| `AI_HEALING_API_KEY` (or `ANTHROPIC_API_KEY`) | unset | Required when AI Vision is enabled and primary fails. |
+
+## Key rules
+
+1. **Always run `preview_migration` first** — review the plan and conflicts before writing.
+2. **Never infer conflict decisions** — ask the user whether to overwrite, skip, or abort.
+3. **TODO comments are not errors** — complex locators flagged with `// TODO` are valid output; inform the user they need manual review.
+4. **Feature files are copied as-is** — no Gherkin transformation is applied to `.feature` files during migration (the spec→BDD conversion is only for non-BDD `.spec.*` sources).
+5. **BOILERPLATE fill is allowlisted** — `_BOILERPLATE_FILL_ALLOWLIST` in `_migrate.py` lists exactly which boilerplate entries are dropped in (the rest are held back because they assume APIs the enhanced scaffold doesn't expose).
+6. **Config merge is non-destructive** — existing settings in Helix configs are never overwritten; only missing settings are added. `--conflict overwrite` refreshes `.mcp.json`, `.env.example`, generated scaffolds, and the cucumber config to pick up tool-side improvements.
+7. **Healing scaffold takes precedence over BOILERPLATE** — the enhanced `LocatorHealer.ts` / `LocatorRepository.ts` / `TimingHealer.ts` / `VisualIntentChecker.ts` / `HealingDashboard.ts` are written first by `_scaffold_locator_repository`; the BOILERPLATE versions of the same files are never written.