@qa-gentic/stlc-agents 1.0.5 → 1.0.7

package/.github/copilot-instructions/generate-playwright-code.md

@@ -1,464 +0,0 @@
----
-name: generate-playwright-code
-description: >
-  Use this skill whenever the user asks to generate, create, or update Playwright TypeScript
-  automation code for a Feature, PBI, or Bug. Triggers when the user mentions "Playwright",
-  "page object", "locators", "step definitions", "automation", "self-healing", "locator
-  repository", "TimingHealer", "VisualIntentChecker", or asks to automate a Gherkin feature
-  file. Always reads existing attached Playwright files from the ADO work item before generating
-  anything, to avoid duplicate locators, page methods, and step definitions. Works with any ADO
-  work item type: PBI, Bug, or Feature ID.
-compatibility:
-  tools:
-    - qa-playwright-generator:scaffold_locator_repository
-    - qa-playwright-generator:generate_playwright_code
-    - qa-playwright-generator:attach_code_to_work_item
-    - qa-playwright-generator:validate_gherkin_steps
-    - qa-test-case-manager:get_linked_test_cases
-    - qa-gherkin-generator:fetch_feature_hierarchy
-    - playwright:browser_navigate
-    - playwright:browser_snapshot
-    - playwright:browser_fill_form
-    - playwright:browser_click
-    - playwright:browser_file_upload
----
-
-# Generate Playwright Code Skill
-
-> **Read `AGENT-BEHAVIOR.md` before this skill.** The behavior rules there override any
-> inference. This skill provides the step-by-step workflow only.
-
-Generate production-quality, three-layer self-healing Playwright TypeScript automation from a
-validated Gherkin feature file, using live Playwright MCP snapshots for verified locators.
-Works with any ADO work item type: PBI, Bug, or Feature ID.
-
----
-
-## Three Healing Layers
-
-Every generated page object implements three layers of self-healing:
-
-| Layer | Class | What it heals |
-|---|---|---|
-| 1 — Locator | `LocatorHealer` | primary selector → role → label → text → AI Vision → CDPSession AX tree |
-| 2 — Timing | `TimingHealer` | network-trace drift → auto-adjusted timeouts → HealingDashboard |
-| 3 — Visual | `VisualIntentChecker` | element screenshot diff at assertions → HealingDashboard |
-
-Healed selectors are persisted in `LocatorRepository` — zero overhead on repeat runs.
-HealingDashboard runs at `http://localhost:7890` during test execution for approve/reject.
-
----
-
-## ⛔ Mandatory Pre-Flight: Deduplication Protocol
-
-Before generating or attaching any file, run the deduplication protocol:
-`skills/deduplication-protocol.md`
-
-The protocol is **work-item-scoped**: PHASE 1 runs once per `work_item_id` and results are
-cached. If `generate-gherkin` already ran for this `work_item_id`, skip PHASE 1 and read from
-`CACHE[work_item_id]` directly. A different `work_item_id` always triggers a fresh PHASE 1.
-
----
-
-## Step-by-Step Workflow
-
-### Step 0 — Route: fresh project vs. existing boilerplate
-
-Before any other step, determine whether the Helix-QA project already has the automation
-infrastructure in place.
-
-```
-Call: qa-helix-writer:list_helix_tree(helix_root)
-         │
-         ├─ framework_state: "absent" or "partial"  →  FRESH PROJECT
-         │        Call scaffold_locator_repository(...)  FIRST
-         │        Then call generate_playwright_code(...)
-         │
-         └─ framework_state: "present"  →  EXISTING BOILERPLATE
-                  Call generate_playwright_code(...)  ONLY
-                  Do NOT call scaffold_locator_repository — infra already exists
-```
-
-**Why this matters:** `scaffold_locator_repository` generates the six shared infrastructure
-files (`LocatorRepository`, `LocatorHealer`, `TimingHealer`, `VisualIntentChecker`,
-`DevToolsHealer`, `cucumber.config.ts`). Calling it on an existing project overwrites those
-files and destroys any customisations. Never call it when `framework_state: "present"`.
-
----
-
-### Step 1 — Load existing Playwright artifacts from cache
-
-Read from `CACHE[work_item_id]` (populated by the deduplication protocol pre-flight):
-
-```
-CACHE[work_item_id].existing_attachments.locators_ts   → existing locator keys
-CACHE[work_item_id].existing_attachments.page_objects  → existing method names
-CACHE[work_item_id].existing_attachments.steps_files   → existing step strings
-```
-
-If a file exists but content could not be read, treat it as fully covering its domain and
-produce no new file of that type unless you can prove a gap.
-
----
-
-### Step 2 — GAP CHECK: identify screens you cannot reach and ASK before proceeding
-
-Before navigating the live app, scan the Gherkin feature file for every `Given` step that
-requires a specific app state — a state only reachable by performing a real action (uploading
-a file, submitting a form, triggering an error, completing a multi-step flow).
-
-For each such step, ask: **can I reach this screen right now with the information I have?**
-
-#### Blockers that require a user question before proceeding
-
-| Blocker | Example | What to ask |
-|---|---|---|
-| File upload required to reach a screen | "Given I am on the failure summary screen" — only after uploading a CSV with bad rows | "Please provide the CSV file or tell me which emails to use as known duplicates" |
-| Specific record / ID required | "Given work item #12345 has linked test cases" | "Which org / record should I test against?" |
-| Error state requires specific bad data | "Given the upload is rejected for unsupported format" | "Should I use .txt or .pdf to test the rejection?" |
-| Multi-step prerequisite from a sibling PBI | "Given the mass add has completed" | "Should I replay the upload step, or is there a seed/shortcut?" |
-| Screen only exists after a backend event | "Given the processing is complete" | "Is there a test endpoint I can hit to seed this state?" |
-
-**If any blocker is found, output a question block and wait for answers.**
-
-#### Question format
-
-```
-Before I navigate the live app to capture locators for "<feature title>", I need:
-
-**[Blocker type]: [screen or element name]**
-[One sentence describing what the Gherkin step requires]
-→ [Specific question — what file, what email, what record, what sequence?]
-
-I will not proceed until these are answered, to avoid inventing selectors
-(stability: 0) for screens I cannot reach.
-```
-
-**Only proceed to Step 3 once every blocker is resolved, OR the user explicitly grants
-sign-off to proceed with known `stability: 0` limitations documented.**
-
----
-
-### Step 3 — Live locator verification through the FULL flow
-
-Navigate through **every screen in the Gherkin feature** — including state-dependent screens —
-using the real test data provided in Step 2. Never snapshot only the landing page and infer.
-
-```
-playwright:browser_navigate(APP_BASE_URL)
-playwright:browser_snapshot()                    ← login screen
-
-playwright:browser_fill_form(fields: [
-  { name: "Email",    type: "textbox", ref: "<ref>", value: "<email>" },
-  { name: "Password", type: "textbox", ref: "<ref>", value: "<password>" }
-])
-playwright:browser_click(ref: "<login-button-ref>")
-playwright:browser_snapshot()                    ← dashboard — verify logged in
-
-← Navigate through EVERY prerequisite step to reach state-dependent screens
-playwright:browser_click(...)                    ← e.g. "Add Users" button
-playwright:browser_click(...)                    ← e.g. "Add Multiple" tab
-playwright:browser_snapshot()                    ← capture screen locators
-
-← Upload real test file (from user's Step 2 answer)
-playwright:browser_file_upload(
-  files: ["<real file path>"],
-  element: "file upload input",
-  ref: "<ref from snapshot>"
-)
-playwright:browser_snapshot()                    ← verify file attached, Next enabled
-
-playwright:browser_click(...)                    ← "Next" / Submit
-playwright:browser_snapshot()                    ← capture processing screen (if any)
-playwright:browser_snapshot()                    ← capture state-dependent result screen
-                                                    ← capture ALL interactive elements here
-
-playwright:browser_click(...)                    ← any further actions (Export, Accept, etc.)
-playwright:browser_snapshot()                    ← capture post-action state
-```
-
-**Rule:** Every locator in the generated `locators.ts` must appear in one of these snapshots.
-If a screen cannot be reached because test data is missing, go back to Step 2 and ask — do
-not assign `stability: 0` and continue silently.
-
----
-
-### Step 4 — Build the context_map
-
-From each snapshot, map AX tree nodes to locator entries using this stability rank:
-
-| Selector source | Stability |
-|---|---|
-| `data-testid` attribute | 100 |
-| `aria-role` + accessible name | 90 |
-| `id` attribute | 80 |
-| `aria-label` | 70 |
-| `placeholder` text | 60 |
-| Gherkin-inferred (no live verification) | 0 — `⚠ NOT VERIFIED` comment required |
-
-Only include keys NOT already present in the existing `locators.ts` (from Step 1).
-
-**Example context_map (built from Playwright MCP AX snapshots):**
-```json
-{
-  "emailInput":         { "selector": "[data-testid='auth0_login-input-email']",        "intent": "Auth0 login email field",              "stability": 100 },
-  "loginButton":        { "selector": "[data-testid='auth0_login-button-login']",       "intent": "Submit login credentials",             "stability": 100 },
-  "addUsersButton":     { "selector": "[data-testid='person_header-button-add_users']", "intent": "Add Users button, opens slide-out",    "stability": 100 },
-  "addMultipleTab":     { "selector": "[data-testid='person_slider-tab-add_multiple']", "intent": "Add Multiple tab in Add Users panel",  "stability": 100 },
-  "fileInput":          { "selector": "input[type='file']",                             "intent": "Hidden file input for CSV upload",     "stability": 70  },
-  "nextButton":         { "selector": "button:has-text('Next')",                        "intent": "Proceed after file upload",            "stability": 90  },
-  "exportListButton":   { "selector": "button:has-text('Export List')",                 "intent": "Export failed users CSV",              "stability": 90, "visualIntent": true },
-  "failureSummaryTable":{ "selector": "table",                                          "intent": "Failed user rows table",               "stability": 80, "visualIntent": true }
-}
-```
-
----
-
-### Step 5 — Generate the code
-
-```
-qa-playwright-generator:generate_playwright_code(
-  gherkin_content          : <validated .feature file content>,
-  page_class_name          : "<ScreenName>Page",
-  app_name                 : "<AppName>",
-  context_map              : <context_map from Step 4>,
-  healing_strategy         : "role-label-text-ai",
-  enable_timing_healing    : true,
-  enable_visual_regression : true
-)
-```
-
-The tool produces four files:
-- `locators.ts` — selector registry with intent, stability score, visualIntent flag
-- `{ScreenName}Page.ts` — three-layer self-healing page object
-- `{feature}.steps.ts` — Cucumber step definitions
-- `cucumber-profile.js` snippet — profile config to add to `config/cucumber.js`
-
----
-
-### Step 6 — Apply the deduplication delta filter
-
-Diff generated output against `CACHE[work_item_id].existing_attachments`:
-
-**locators.ts:** Remove keys already in existing file. Empty delta → skip. Non-empty → attach as `locators.delta.ts`:
-```typescript
-// DELTA — merge these keys into the existing locators.ts
-// Generated: <date> | Work item: #<id>
-```
-
-**{ScreenName}Page.ts:** Remove methods already in existing page object. Empty delta → skip. Non-empty → attach as `{ScreenName}Page.delta.ts` with merge header.
-
-**{feature}.steps.ts:** Remove any `Given(` / `When(` / `Then(` whose step string already exists. Empty delta → skip. Non-empty → attach only net-new steps.
-**CRITICAL: Never re-register an existing step string** — causes `Ambiguous step definition` at runtime.
-
----
-
-### Step 7 — Delivery gate (mandatory before attaching to ADO)
-
-Before calling `attach_code_to_work_item`, present the following to the user and wait:
-
-```
-I've generated the following Playwright TypeScript files for work item #{id}:
-
-  📄 locators.delta.ts      — {N} new locator keys
-  📄 {ScreenName}Page.delta.ts — {N} new page methods
-  📄 {feature}.steps.delta.ts  — {N} new step definitions
-
-**Do you want me to attach these to ADO work item #{id}? (yes / no)**
-
-Note:
-- Saying yes here only attaches the Playwright files.
-- It does NOT create manual test cases or attach Gherkin files.
-- If you also want those, say so separately.
-```
-
-**Do not call `attach_code_to_work_item` until the user replies "yes".**
-
-If user says "yes", call with delta files only:
-
-```
-qa-playwright-generator:attach_code_to_work_item(
-  organization_url : "<org_url>",
-  project_name     : "<project>",
-  work_item_id     : <id>,
-  files            : [
-    { file_name: "locators.delta.ts",         content: "..." },
-    { file_name: "{ScreenName}Page.delta.ts",  content: "..." },
-    { file_name: "{feature}.steps.delta.ts",   content: "..." }
-  ]
-)
-```
-
-If user says "no": present the files inline. Offer local download only if user says
-"save" or "download". Do not create a local file automatically.
-
-**After attach — STOP. Do not trigger Helix write or any other action automatically.**
-Helix-QA disk writes are a separate decision requiring a separate user request.
-
----
-
-## Generated File Structures
-
-### locators.ts
-
-```typescript
-/**
- * Locators: <ScreenName>Page
- * SOURCE: Playwright MCP AX tree snapshot — <app-url>/<route>
- * Stability: data-testid(100) > role+name(90) > id(80) > aria-label(70) > placeholder(60)
- * ⚠ stability:0 entries were NOT reached in the live session — get user sign-off before using.
- */
-export const <ScreenName>Locators = {
-  // stability: 100 — data-testid, survives refactors
-  addUsersButton: {
-    selector  : "[data-testid='person_header-button-add_users']",
-    intent    : "Add Users button that opens the slide-out panel",
-    stability : 100,
-  },
-  // stability: 90 — aria-role+name, visualIntent: screenshot at assertions
-  exportListButton: {
-    selector     : "button:has-text('Export List')",
-    intent       : "Export List button on the failure summary screen",
-    stability    : 90,
-    visualIntent : true,
-  },
-  // ⚠ stability: 0 — NOT VERIFIED: could not reach this screen (reason: <why>)
-  // Get user sign-off before using in automation.
-  someUnreachedElement: {
-    selector  : "[data-testid='TODO']",
-    intent    : "...",
-    stability : 0,
-  },
-} as const;
-
-export type LocatorKey = keyof typeof <ScreenName>Locators;
-```
-
-### {ScreenName}Page.ts
-
-```typescript
-import { Page, expect, Download } from '@playwright/test';
-import { fixture }               from '@hooks/pageFixture';
-import { <ScreenName>Locators }  from './locators';
-import { LocatorHealer }         from '@utils/locators/LocatorHealer';
-import { LocatorRepository }     from '@utils/locators/LocatorRepository';
-import { VisualIntentChecker }   from '@utils/locators/VisualIntentChecker';
-import { TimingHealer }          from '@utils/locators/TimingHealer';
-
-/**
- * <ScreenName>Page — Three-Layer Self-Healing Page Object
- * Layer 1 (LocatorHealer):  primary → role → label → text → AI Vision → AX tree
- * Layer 2 (TimingHealer):   network-trace drift → auto-adjusted timeouts
- * Layer 3 (VisualIntentChecker): element screenshot diff at key assertions
- * HealingDashboard: http://localhost:7890
- * RULE: Never use page.click / page.fill / page.locator directly.
- */
-export default class <ScreenName>Page {
-  private readonly loc    = <ScreenName>Locators;
-  private readonly page:   Page;
-  private readonly healer: LocatorHealer;
-  private readonly repo:   LocatorRepository;
-  private readonly visual: VisualIntentChecker;
-  private readonly timing: TimingHealer;
-
-  constructor(page?: Page) {
-    this.page   = page ?? fixture().page;
-    this.repo   = fixture().locatorRepository ?? new LocatorRepository();
-    this.healer = new LocatorHealer(this.page, fixture().logger, this.repo);
-    this.visual = new VisualIntentChecker(this.page, fixture().logger, this.repo);
-    this.timing = new TimingHealer(this.page, fixture().logger, this.repo);
-    Object.entries(this.loc).forEach(([k, v]) => this.repo.register(k, v.selector, v.intent));
-  }
-
-  async login(email: string, password: string): Promise<void> {
-    await this.page.goto(process.env.APP_BASE_URL!, { waitUntil: 'networkidle' });
-    await this.healer.fillWithHealing('emailInput',    this.loc.emailInput.selector,    email,    this.loc.emailInput.intent);
-    await this.healer.fillWithHealing('passwordInput', this.loc.passwordInput.selector, password, this.loc.passwordInput.intent);
-    await this.healer.clickWithHealing('loginButton',  this.loc.loginButton.selector,             this.loc.loginButton.intent);
-    await this.timing.waitForNetworkIdle('login');
-  }
-
-  // All interactions go through LocatorHealer — never raw page.click / page.fill
-}
-```
-
-### {feature}.steps.ts
-
-```typescript
-import { Given, When, Then, Before } from '@cucumber/cucumber';
-import { expect }                    from '@playwright/test';
-import { fixture }                   from '@hooks/pageFixture';
-import <ScreenName>Page              from '@pages/<screenName>/<ScreenName>Page';
-
-let page_: <ScreenName>Page;
-
-Before(async () => { page_ = new <ScreenName>Page(fixture().page); });
-
-Given('I am logged in to {word} as {string}', async (_app: string, email: string) => {
-  await page_.login(email, process.env.APP_PASSWORD!);
-});
-
-// Only net-new steps — never re-register steps already in existing files
-```
-
----
-
-## Run Commands
-
-```bash
-ENABLE_SELF_HEALING=true \
-HEALING_DASHBOARD_PORT=7890 \
-APP_BASE_URL=https://account.myamplify.io \
-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"
-```
-
----
-
-## Quality Gates — Do Not Attach Without These
-
-- [ ] Deduplication protocol run — existing locator keys, methods, step strings extracted
-- [ ] **Gap check (Step 2) completed** — every state-dependent screen identified
-- [ ] **All blockers answered by user before any navigation began**
-- [ ] **Live snapshots taken of every screen in the full flow** using real test data
-- [ ] **Zero `stability: 0` locators** for screens reachable with provided test data
-- [ ] Every `stability: 0` locator has `⚠ NOT VERIFIED` comment with explicit user sign-off
-- [ ] No step string re-registers an already-registered Given/When/Then
-- [ ] Page object methods use `LocatorHealer` — never raw `page.click` / `page.fill`
-- [ ] Credentials sourced from `process.env`, not hardcoded
-- [ ] Delta files have merge-instruction comment at top
-
----
-
-## Locator Stability Reference
-
-| Pattern | Stability | When to use |
-|---|---|---|
-| `[data-testid='...']` | 100 | Always prefer — survives refactors |
-| `role=button[name='...']` | 90 | When data-testid absent |
-| `#id` | 80 | When id is stable and meaningful |
-| `[aria-label='...']` | 70 | Accessibility attributes |
-| `[placeholder='...']` | 60 | Input fields only |
-| Text / position selectors | 0 | Last resort — flag for upgrade |
-
----
-
-## Explicit Delivery Rules — No Inference
-
-| Decision | Rule |
-|---|---|
-| Generate Playwright code | Always: show file summary and delta counts first |
-| Attach to ADO | Requires explicit "yes" at Step 7 gate |
-| User says "no" at Step 7 | Present files inline; offer local download only if user asks |
-| Local file creation | Only if user says "save" or "download" |
-| Helix-QA disk write | Must be a separate user request — not triggered by ADO attachment |
-| Test case creation | Must be a separate user request — not triggered by this skill |
-| Gherkin attachment | Must be a separate user request — not triggered by this skill |
-| Prior Gherkin "yes" | Has NO bearing on Playwright attachment decision |
-| Prior test case "no" | Has NO bearing on Playwright attachment decision |
-
-**Each artifact delivery is independent. A yes/no for one does not answer any other.**