<div align="center">

# 🚀 Migrating an Existing Playwright Framework to STLC Agents

<picture>
  <source media="(prefers-color-scheme: dark)" srcset="https://readme-typing-svg.demolab.com?font=Fira+Code&size=18&duration=2800&pause=600&color=8AB4F8&center=true&vCenter=true&width=720&lines=One-shot+conversion+%E2%80%94+source+%E2%86%92+Helix-QA+tree;Six+MCP+agents%2C+wired+end-to-end;Self-healing+locators+with+8-strategy+chain;VRT%2C+BDD%2C+ADO%2C+Jira+%E2%80%94+one+CLI+flag+away" alt="typing intro" />
  <img src="https://readme-typing-svg.demolab.com?font=Fira+Code&size=18&duration=2800&pause=600&color=1A73E8&center=true&vCenter=true&width=720&lines=One-shot+conversion+%E2%80%94+source+%E2%86%92+Helix-QA+tree;Six+MCP+agents%2C+wired+end-to-end;Self-healing+locators+with+8-strategy+chain;VRT%2C+BDD%2C+ADO%2C+Jira+%E2%80%94+one+CLI+flag+away" alt="typing intro" />
</picture>

</div>

```mermaid
flowchart LR
    A([📦 Existing Playwright Repo]):::src --> B{{🔎 stlc-migrate}}:::cli
    B --> C[🧪 Transformer]:::xform
    C --> D[🩺 Healer Scaffold]:::heal
    C --> E[📑 Agent Assets]:::agents
    C --> F[⚙️ Config Merge]:::cfg
    D & E & F --> G([🌲 Helix-QA Tree]):::out

    classDef src fill:#E8F0FE,stroke:#1A73E8,color:#0B57D0,stroke-width:2px
    classDef cli fill:#FEF7E0,stroke:#F9AB00,color:#5F4708,stroke-width:2px
    classDef xform fill:#E6F4EA,stroke:#188038,color:#0D652D
    classDef heal fill:#FCE8E6,stroke:#D93025,color:#A50E0E
    classDef agents fill:#F3E8FD,stroke:#A142F4,color:#681DA8
    classDef cfg fill:#E8EAED,stroke:#5F6368,color:#3C4043
    classDef out fill:#CEEAD6,stroke:#137333,color:#0B4A1E,stroke-width:2px
```

> A practical, one-shot conversion of an existing Playwright test suite into a **Helix-QA** tree that the five QA STLC agents (`test-case-manager`, `gherkin-generator`, `playwright-generator`, `helix-writer`, `jira-manager`) operate against. Done via the `stlc-migrate` CLI, the sixth MCP server (`qa-migration`).

<div align="center">

[![Status](https://img.shields.io/badge/status-stable-brightgreen?style=for-the-badge)](.) [![Pipeline](https://img.shields.io/badge/agents-5-blue?style=for-the-badge)](.) [![Healer](https://img.shields.io/badge/strategies-8-purple?style=for-the-badge)](.) [![License](https://img.shields.io/badge/CLI-one--command-orange?style=for-the-badge)](.)

</div>

---

## 📑 Jump to

<details>
<summary><b>Click to expand the table of contents</b></summary>

1. [Does it work on my project?](#1-does-it-work-on-my-project)
2. [One-command migration](#2-one-command-migration)
3. [CLI flags worth knowing](#3-cli-flags-worth-knowing)
4. [What lands in the Helix tree](#4-what-lands-in-the-helix-tree)
5. [After the migration](#5-after-the-migration)
6. [Re-migrating (refreshing scaffolds)](#6-re-migrating-refreshing-scaffolds)
7. [Limits & honest caveats](#7-limits--honest-caveats)

</details>

---

## 1. Does it work on my project?

The tool migrates **any Playwright-based project** that fits one of these four shapes — detected automatically.

```mermaid
flowchart TD
    Start([🔍 Scan source repo]):::start --> HasConfig{playwright.config<br/>found?}:::dec
    HasConfig -- no --> Reject([❌ Not in scope]):::bad
    HasConfig -- yes --> Lang{config<br/>language?}:::dec
    Lang -- .ts --> HasFeat1{any .feature<br/>or @cucumber?}:::dec
    Lang -- .js --> HasFeat2{any .feature<br/>or @cucumber?}:::dec
    HasFeat1 -- yes --> BDDTS([✅ playwright-bdd-ts]):::good
    HasFeat1 -- no --> TS([✅ playwright-ts]):::good
    HasFeat2 -- yes --> BDDJS([✅ playwright-bdd-js]):::good
    HasFeat2 -- no --> JS([✅ playwright-js]):::good

    classDef start fill:#E8F0FE,stroke:#1A73E8,color:#0B57D0,stroke-width:2px
    classDef dec   fill:#FEF7E0,stroke:#F9AB00,color:#5F4708
    classDef good  fill:#CEEAD6,stroke:#137333,color:#0B4A1E,stroke-width:2px
    classDef bad   fill:#FCE8E6,stroke:#D93025,color:#A50E0E,stroke-width:2px
```

<details>
<summary><b>📋 Detection signal cheat-sheet</b></summary>

| Source framework | Detection signal |
|------------------|------------------|
| `playwright-ts` | `playwright.config.ts`, no `.feature` files |
| `playwright-js` | `playwright.config.js`, no `.feature` files |
| `playwright-bdd-ts` | `playwright.config.ts` + `.feature` files (or `@cucumber/cucumber` in `package.json`) |
| `playwright-bdd-js` | `playwright.config.js` + `.feature` files (or `@cucumber/cucumber` in `package.json`) |

</details>

> [!WARNING]
> **Not in scope:** Selenium, Cypress, WebdriverIO, TestCafe, Puppeteer, standalone Jest/Mocha/Jasmine UI tests. The agents are wired to Playwright's APIs end-to-end (page-object class shape, locator semantics, `page.evaluate`, CDP healer); porting other frameworks is outside the migration's contract.

---

## 2. One-command migration

```mermaid
sequenceDiagram
    autonumber
    actor U as 👤 You
    participant PIP as 📦 pip
    participant CLI as 🛠 stlc-migrate
    participant FS as 💾 Helix-QA dir

    U->>PIP: pip install qa-gentic-stlc-agents
    PIP-->>U: ✅ installed (CLI + 5 MCP servers)
    U->>CLI: --source ./my-tests --helix ./helix-qa --dry-run
    CLI-->>U: 📋 mapping plan (no writes)
    U->>CLI: --source ./my-tests --helix ./helix-qa
    CLI->>FS: write transformed code + assets
    FS-->>U: 🌲 Helix-QA tree ready
```

```bash
# Install once (provides stlc-migrate + all six MCP servers)
pip install qa-gentic-stlc-agents

# Dry-run — see the file mapping plan without writing anything
stlc-migrate --source ./my-playwright-tests --helix ./helix-qa --dry-run

# Real migration
stlc-migrate --source ./my-playwright-tests --helix ./helix-qa
```

> [!NOTE]
> The Helix target directory must already exist (or use `--dry-run`).

---

## 3. CLI flags worth knowing

<details open>
<summary><b>🎛 <code>--integration</code> &nbsp;·&nbsp; pick your tracker</b></summary>

```
ado     │  ADO skills + .mcp.json entries only — Jira assets skipped
jira    │  Jira skills + .mcp.json entries only — ADO assets skipped
both    │  Everything (default)
```
</details>

<details>
<summary><b>⚔️ <code>--conflict</code> &nbsp;·&nbsp; what happens to existing files</b></summary>

```
interactive  │  Ask per-file (default)
skip         │  Keep target, log skipped
overwrite    │  Replace target  ⚠️ also auto-removes stale
             │   .feature / .steps.ts / .page.ts / .locators.ts orphans
             │   in role dirs the migration owns — useful after
             │   toggling layout flags
```
</details>

<details>
<summary><b>🌳 <code>--preserve-tree</code> &nbsp;·&nbsp; mirror source folder grouping</b></summary>

Mirror the source's subfolder grouping under `src/test/features/`, `src/test/steps/`, `src/pages/`, `src/locators/`. Sub-dir names are kebab-cased — `ECommerce` becomes `e-commerce`. Default flattens.
</details>

<details>
<summary><b>📸 <code>--features=vrt</code> &nbsp;·&nbsp; visual regression scaffold</b></summary>

Explicit VRT scaffold. **Auto-enabled** when the source has any `vrt:*` npm script or any `.env*` file mentioning `VRT_MODE`.
</details>

<details>
<summary><b>🔬 <code>--dry-run</code> · <code>--json</code></b></summary>

`--dry-run` previews without writing. `--json` emits machine-readable output for scripting.
</details>

**Combined example:**

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

---

## 4. What lands in the Helix tree

```mermaid
mindmap
  root((🌲 Helix-QA))
    Code transformation
      Page objects with healer wiring
      Locators in {selector, intent, stability}
      JS→TS, require→import
      data-testid→getByTestId
      text=→getByText
    Spec → BDD
      Lossless one-scenario-per-test
      No invented step text
    Self-healing infra
      LocatorHealer 8-strategy
      Intent-shape-aware attribute
      LocatorRepository schema v1
      TimingHealer
      VisualIntentChecker
      HealingDashboard Approve-all
    Agent assets
      .mcp.json all 6 servers
      .claude skills
      .github copilot-instructions
      AGENT-BEHAVIOR.md
      ORCHESTRATION_RULES.md
    Config merge
      playwright.config.ts
      cucumber.js + dotenv
      package.json scripts/deps
      tsconfig path aliases
    VRT runtime
      vrtCapture · vrtReport
      vrt.steps.ts
      vrt:baseline · vrt:test
      pngjs · pixelmatch · fs-extra
    Boilerplate fill
      HealApplicator · LocatorRules
      Logger · RetryHandler
      WaitHelper · environment.ts
    Report
      MIGRATION-REPORT.md
```

<details>
<summary><b>📋 Layer-by-layer table view</b></summary>

| Layer | What's produced |
|-------|----------------|
| **Code transformation** | Page objects, step files, locator files in `{selector, intent, stability}` form. Every locator interaction routed through `_healer.clickWithHealing` / `fillWithHealing` / `assertVisibleWithHealing`. JS→TS, `require`→`import`, `[data-testid]`→`getByTestId`, `text=`→`getByText`. |
| **Spec → BDD** | Non-BDD `.spec.*` files losslessly converted to one-scenario-per-test feature + step pairs. No invented step text, no Given/When/Then reclassification. |
| **Self-healing infra** (`src/utils/locators/`) | 8-strategy `LocatorHealer` (intent-shape-aware `attribute` strategy — `:is(input, …)[id*="password"]` blocks substring matches from picking up unrelated elements), `LocatorRepository` (schema v1, debounced writes, per-env file suffix), `TimingHealer`, `VisualIntentChecker`, `HealingDashboard` (Confirm/Revert both clear the entry; **Approve all** bulk action for ≥ 2 healed entries), `dashboard-server`. |
| **Agent assets** | `.mcp.json` (all 6 MCP servers + Playwright MCP, absolute binary paths), `.claude/skills/<name>/SKILL.md`, `.github/copilot-instructions/<name>.md`, `AGENT-BEHAVIOR.md`, `ORCHESTRATION_RULES.md`. |
| **Config merge** | `playwright.config.ts` settings merged; `config/cucumber.js` rewritten with `dotenv/config` as first `requireModule`; `package.json` gets `dotenv`, `@types/*` companions, `healix:dashboard`/`healix:review` scripts; `tsconfig.json` gains `@pages`/`@steps`/`@features`/`@locators`/`@hooks`/`@helper`/`@utils`/`@config` aliases. |
| **VRT runtime** *(only when `vrt` in features)* | `src/helper/vrt/{vrtCapture,vrtReport}.util.ts`, `src/test/steps/vrt.steps.ts`, `vrt:baseline`/`vrt:test` npm scripts, `pngjs`+`pixelmatch`+`fs-extra` deps, VRT block in `.env.example`. Hooks scaffold is VRT-aware when the migration owns it; when the source ships its own hooks, a wiring snippet is appended to `MIGRATION-REPORT.md`. |
| **Boilerplate fill** | Allow-listed helpers (`HealApplicator`, `LocatorRules`, `LocatorStrategy`, `Logger`, `RetryHandler`, `WaitHelper`, `environment.ts`, `base.locators.ts`, …) from `agent_helix_writer.tools.boilerplate.BOILERPLATE`. Never overwrites existing files; never clobbers the enhanced healer scaffold. |
| **Report** | `MIGRATION-REPORT.md` — written/skipped/conflicts/TODOs, removed orphans (when any), VRT wiring snippet (when applicable). |

</details>

### 🩺 The healing chain at a glance

```mermaid
stateDiagram-v2
    direction LR
    [*] --> Primary
    Primary --> Hit: ✅ selector resolves
    Primary --> S1: ❌ stale
    S1: attribute (intent-shape-aware)
    S2: type-hint
    S3: role
    S4: label
    S5: text
    S6: nearby-text
    S7: structural
    S8: visual-intent
    S1 --> Hit: match
    S1 --> S2: miss
    S2 --> Hit: match
    S2 --> S3: miss
    S3 --> Hit: match
    S3 --> S4: miss
    S4 --> Hit: match
    S4 --> S5: miss
    S5 --> Hit: match
    S5 --> S6: miss
    S6 --> Hit: match
    S6 --> S7: miss
    S7 --> Hit: match
    S7 --> S8: miss
    S8 --> Hit: match
    S8 --> Fail: 🛑 give up
    Hit --> Persist: record heal
    Persist --> [*]
    Fail --> [*]
```

---

## 5. After the migration

```mermaid
gantt
    title Post-migration workflow (typical timings)
    dateFormat  X
    axisFormat  %S
    section 📦 Install
    npm install               :a1, 0, 18
    section 🧠 Typecheck
    npx tsc --noEmit          :a2, after a1, 8
    section ✅ Test
    npm test                  :a3, after a2, 25
    section 🩺 Heal review
    healix:dashboard          :a4, after a3, 10
    section 📸 VRT (optional)
    vrt:baseline              :a5, after a4, 6
    vrt:test                  :a6, after a5, 6
```

```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; heals persist to self-heals/
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)
```

> [!TIP]
> When you **Confirm** a heal in the dashboard, the healed selector is written back to the source `*.locators.ts` file and the entry is cleared. Future runs use the corrected selector as the primary; the healing chain only fires again if the page changes.

<details>
<summary><b>📸 If VRT is on …</b></summary>

```bash
npm run vrt:baseline   # capture reference screenshots
# ... make UI changes ...
npm run vrt:test       # compare; diffs land in test-results/vrt/
```
</details>

---

## 6. Re-migrating (refreshing scaffolds)

```mermaid
flowchart LR
    A[Run #1<br/>--preserve-tree] -->|"creates nested dirs"| T1[(🌲 Tree v1)]
    T1 -->|"toggle off, re-run<br/>--conflict overwrite"| B[Run #2<br/>flat layout]
    B -->|"auto-sweeps<br/>role-dir orphans"| T2[(🌲 Tree v2)]

    style A fill:#E8F0FE,stroke:#1A73E8
    style B fill:#FEF7E0,stroke:#F9AB00
    style T1 fill:#E6F4EA,stroke:#188038
    style T2 fill:#CEEAD6,stroke:#137333,stroke-width:2px
```

Run again with `--conflict overwrite` to pick up tool-side improvements (new healer strategies, fresh skill files, updated env vars). The same flag auto-removes orphan `.feature` / `.steps.ts` / `.page.ts` / `.locators.ts` files in role dirs that this run didn't write — so toggling `--preserve-tree` on/off is a one-pass operation, no manual `rm -rf` needed.

```bash
stlc-migrate --source ./my-tests --helix ./helix-qa --conflict overwrite
```

<details>
<summary><b>🛡 What the orphan sweep <i>never</i> touches</b></summary>

- Non-role files: READMEs, JSON test data, `*.md`
- Other dirs: `src/helper/`, `src/hooks/`, `src/utils/locators/`, `src/fixtures/`, `src/test/support/` — they mix source-mapped, scaffolded, and operator-added files in ways the migration can't safely distinguish.

</details>

---

## 7. Limits & honest caveats

<table>
<tr>
<td width="50%" valign="top">

> [!IMPORTANT]
> **Zero-inference contract**
>
> The migration preserves source bugs verbatim rather than guessing fixes. If your source references a non-existent property, `tsc` will surface it; the tool won't paper over it.

</td>
<td width="50%" valign="top">

> [!WARNING]
> **Complex XPath / CSS**
>
> Selectors that can't be modernised (e.g. `xpath=//div[@class="foo"][2]/span[contains(text(),"bar")]`) are flagged with `// TODO: convert to getByRole` and left as-is.

</td>
</tr>
<tr>
<td width="50%" valign="top">

> [!NOTE]
> **Source hooks are kept**
>
> If the source ships its own `src/hooks/hooks.ts` and you enable VRT, paste the wiring snippet (from `MIGRATION-REPORT.md`) into your hooks manually.

</td>
<td width="50%" valign="top">

> [!TIP]
> **Existing settings win on merge**
>
> The migration never overwrites a value already present in `playwright.config.ts`, `tsconfig.json`, or `package.json`. Only missing settings/deps are added.

</td>
</tr>
</table>

---

<div align="center">

### 📚 Want the full pipeline reference?

Every transformation, every env var, every boilerplate file — see  
**[`skills/migrate-framework/SKILL.md`](../skills/migrate-framework/SKILL.md)**

<sub>Made with Mermaid diagrams · collapsibles · GitHub admonitions · works in GitHub, VSCode preview & most Markdown renderers</sub>

</div>
