@hiver/skills 1.0.7 → 1.0.9

package/collections/qa-skills/skills/playwright-gen/SKILL.md

@@ -0,0 +1,280 @@
+---
+name: playwright-gen
+description: Hiver Playwright automation — maps confirmed passing test cases onto the existing page objects in the poc-playwright / playwright-hig-automation repo, generates a runnable spec file in the repo house style, runs it, writes results back to the tracker, and opens a PR. Reuses methods, never invents selectors. Trigger on playwright-gen, generate automation, automate these test cases, write playwright tests, run the automation.
+---
+# playwright-gen — Tracker → Running Playwright Tests
+
+You are the **automation track**. Your input is a set of *confirmed* test cases (the qa-ui-run/qa-api-run
+tracker). Your output is a **real, runnable `.spec.ts` file** in the Playwright repo, executed, with
+pass/fail written back into the tracker. This is the step that removes the manual work of hand-writing
+automation.
+
+**Your prime directive: REUSE, never hallucinate.** The repo already has proven page objects with
+selectors that survive Hiver's quirks. You map English test steps onto *existing methods*. If a step
+needs a method that doesn't exist, you FLAG it (or generate a small, clearly-marked addition when the
+user approves) — you never invent a raw selector inline, because untested selectors are exactly what
+makes generated tests fail on a live demo.
+
+**Read before doing anything:**
+- `references/codegen-conventions.md` — the repo's house rules (getter locators, allure steps,
+  two-tier assertions, JSDoc, `authedPage`, path aliases). Generated code MUST match these.
+- `references/step-mapping.md` — how to translate a tracker row into page-object calls, the
+  automatable/skip filter, the missing-method policy, and multi-persona handling.
+- `../qa-kit/references/hiver-context.md` — Hiver concepts.
+- `../qa-kit/references/tracker-format.md` — the tracker schema you
+  read from and write back into (the `Initial Behaviour – Testing 1` + `Status` columns).
+
+> The `../qa-kit/references/…` paths point at the **qa-kit** skill installed alongside this one.
+> Use relative `references/…` for this skill's own files.
+
+---
+
+## Pipeline contract (Phase 1)
+
+This skill runs inside the file-based pipeline. Read
+`../qa-kit/references/handoff-contract.md` (§6 per-agent map) and
+`../qa-kit/references/eval.md` before starting.
+
+- **On start:** read `qa-output/.current-run` → `$RUN_DIR`, then read `$RUN_DIR/handoff.json`.
+  Everything in its cargo is already known — do NOT re-ask the user for it. Open your action log at
+  `$RUN_DIR/logs/playwright-gen.jsonl` and append one line per meaningful action.
+- **During:** the generated specs live in the POC repo (`specs/…`) by design; write the *pipeline*
+  artefacts — tracker.xlsx results and the Allure report path — into `$RUN_DIR`, and append actions
+  to the log.
+- **On finish:** write a step record `$RUN_DIR/steps/playwright-gen-run.json` per `eval.md` (leave
+  `verdict: null` — only qa-eval fills it). playwright-gen is **terminal** — it opens a PR rather than
+  handing off, so it writes no downstream `handoff.json`.
+- **Note (later phase):** the 3-attempt self-heal loop is a behaviour enhancement tracked separately — do not implement it as part of Phase 1 wiring.
+
+---
+
+## The workflow
+
+```
+   qa-ui-run (browser first pass)                 you can also start here directly
+            │  Phase 7 handoff                          │  (point at an existing tracker)
+            ▼                                            ▼
+   ┌──────────────────────────────────────────────────────────────┐
+   │  playwright-gen                                                │
+   │   0 intake → 1 catalog → 2 select+plan(GATE) → 3 map →         │
+   │   4 emit spec → 5 run → 6 write results back → 7 handoff       │
+   └──────────────────────────────────────────────────────────────┘
+                                   ▼
+              specs/<feature>.spec.ts  +  Allure report  +  updated tracker
+```
+
+Semi-auto: there are **two confirmation gates** — after the selection plan (Phase 2) and before the
+run if anything destructive/new was generated (Phase 4). Everything else flows automatically.
+
+---
+
+## PHASE 0 — Intake
+
+**If invoked by `qa-ui-run`/`qa-kit`:** read the handoff block from the conversation (see the contract at
+the bottom). Do NOT re-ask for the feature, product, effort, or the cases — they're already here.
+
+**If invoked directly:** collect the minimum below.
+
+| Input | Required | If missing |
+|---|---|---|
+| The test cases | YES | Either the **confirmed cases in the conversation** (preferred — most reliable) OR a path to the `TestTracker_*.xlsx`. If only the xlsx, parse it (see `step-mapping.md` §Reading the tracker). |
+| Feature name / slug | YES | Derive a kebab-case slug for the filename, e.g. `Hiver Notes` → `hiverNotes`. Match the repo's existing naming (`specs/hiverNotes.spec.ts`). |
+| Repo root | YES | Auto-detect: the dir containing `playwright.config.ts` + `pages/` + `fixtures/auth.fixture.ts`. Default to the poc-playwright / playwright-hig-automation repo. Confirm in one line. |
+| Product: HIG / Omni / Both | From handoff | Only affects env/personas; carry it through. |
+| Effort level | From handoff | Controls how many cases you attempt (mirror qa-ui-run sizing). |
+
+Open with one line: *"I'll build a method catalog from the repo, pick the automatable cases, generate
+`specs/<slug>.spec.ts` reusing existing page objects, run it, and write results back to the tracker."*
+
+A browser-first-pass "passed" status is **not** a hard precondition. If there was no live env, don't
+block — just confirm with the QA that the feature is stable enough to automate (*"Is the build stable
+and do you want automation now?"*). On yes, generate the specs and **gate them to self-skip cleanly**
+(an env `*_READY` flag + the tier-gate detector) until the env/build is available, rather than
+stalling on the missing browser pass. Mark selectors you couldn't verify against a live DOM as
+`// UNVERIFIED` so they're easy to confirm once the build exists.
+
+---
+
+## PHASE 1 — Build the Method Catalog (the key to reuse)
+
+Before writing a single line, learn what the repo already gives you. Read, in the repo root:
+
+1. `fixtures/auth.fixture.ts` — the fixtures available (`authedPage`, `personaContext(name, idx)`).
+2. `pages/*.page.ts` for the feature under test **and any obviously-related page** — extract the
+   **public getters** and **public async methods** with their signatures. These are your vocabulary.
+3. One existing spec for the same/adjacent feature (e.g. `specs/hiverNotes.spec.ts`) — as the golden
+   template for structure, imports, and idiom.
+4. `utils/env.ts` (`mustEnv`/`getEnv`), `utils/wait-helpers.ts`, and `CLAUDE.md` (conventions +
+   `knowledgebase-claude/HIVER-QUIRKS.md` pointers).
+
+Produce a **Method Catalog** — a compact list of what's callable, e.g.:
+
+```
+Page object: HiverNotesPage  (pages/hiver-notes.page.ts)
+  actions:  addNote(text) · editNote(text) · pinNote() · unpinNote() · replyToNote(text)
+            deleteNote() · openFirstSmConversation() · navigateToConversation(subject)
+  asserts:  verifyNotePresent(text) · verifyNoteEdited(text) · expectNotePinned(text)
+            expectEmptyNoteSaveBlocked() · countNotesContaining(text) → number
+Fixtures:   authedPage (Tony) · personaContext('steve'|'thor', workerIndex)
+```
+
+This catalog is what makes generated tests pass — every step you emit must resolve to something here.
+
+---
+
+## PHASE 2 — Select Automatable Cases & Plan (GATE 1)
+
+Go through every case in the tracker and classify it using `step-mapping.md` §The automatable filter:
+
+| Bucket | Meaning |
+|---|---|
+| **Automatable** | Single-account, UI/happy-path/validation, every step maps to a catalog method. |
+| **Needs new method** | Automatable in principle, but one or more steps have no matching page-object method. |
+| **Manual-only** | Skip — matches qa-ui-run's skip rules: two simultaneous accounts (unless multi-persona is explicitly in scope), network-inspection assertions, backend-failure simulation, or anything the tracker already marked `⏭️ Skipped`. (Only internal Gainsight event-tracking is excluded — a customer-facing analytics dashboard/report IS automatable UI.) |
+
+Print the **Automation Plan** and WAIT for confirmation:
+
+```
+Automation Plan — [Feature]  (repo: [root], file: specs/[slug].spec.ts)
+Automatable now:     [n] — [TC IDs]
+Needs new method:    [n] — [TC IDs]  → [the missing capability per case]
+Manual-only (skip):  [n] — [TC IDs]  → [reason, e.g. "requires network inspection"]
+Plan: generate [n] tests reusing [PageObject]. For "needs new method" cases I will:
+      [ (a) generate a small page-object method — I'll show the diff first, OR
+        (b) skip and note it, your call ].
+Run headed or headless? (headed recommended for the demo)
+Go?
+```
+
+Never silently drop a case — every case lands in exactly one bucket and is named.
+
+---
+
+## PHASE 3 — Map Steps → Method Calls
+
+For each automatable case, translate its **Test Steps** + **Expected Result** into page-object calls,
+following `step-mapping.md`. Rules of thumb:
+
+- One tracker case → one `test(...)`. One user-visible step-group → one `allure.step(...)` (3–7 total).
+- Pre-conditions → setup calls (`openFirstSmConversation()`, personas, env reads).
+- Expected-result lines → assertions: single facts via `expect()` in the spec; compound/domain checks
+  via the page object's `expect*`/`verify*` methods.
+- Use unique run tags for created data: `const tag = Date.now().toString().slice(-6)`.
+- For a **"needs new method"** case the user approved: add the smallest possible method to the page
+  object, reusing existing getters/patterns, and mark it with a `// [playwright-gen] generated for TC-xx`
+  comment. Show the diff before writing. If not approved, emit the test body with a
+  `test.fixme(...)` and a `// TODO: needs HiverNotesPage.<method>` note so nothing is lost.
+
+---
+
+## PHASE 4 — Emit the Spec File
+
+Write `specs/[slug].spec.ts` following `references/codegen-conventions.md` exactly:
+
+- Imports from the repo's path aliases / relative fixture path (match the golden template).
+- `test.describe('[Feature]', ...)` with a per-test `test.setTimeout()` sized to the flow.
+- Each test: JSDoc block (`@description`/`@steps`/`@expects`) **above** + matching
+  `allure.description()` + `allure.label('feature', '[Feature]')` + `allure.step()` calls inside.
+- `authedPage` for single-persona; `personaContext(...)` in a `try/finally` for multi-persona.
+
+After writing, run a quick sanity check and (GATE 2, only if you generated new page-object methods)
+confirm the diff is acceptable:
+
+```bash
+npx tsc --noEmit        # or: npm run typecheck
+```
+
+Fix any type errors before running. Report the file path.
+
+---
+
+## PHASE 5 — Run
+
+```bash
+# headed for the demo (browser visibly drives Hiver); drop --headed for CI
+npx playwright test specs/[slug].spec.ts --headed
+# a single case:  npx playwright test specs/[slug].spec.ts -g "case title"
+```
+
+Prereqs the repo owns (verify, don't re-implement): profile seeded (`npm run auth:all` done),
+extension staged, `.env` has the persona password. If the run bounces to Google sign-in or "Hiver
+topbar not visible", that's an environment/auth issue (see `CLAUDE.md` → HIVER-QUIRKS) — surface it,
+don't rewrite the test to work around it.
+
+Capture per-test outcome: passed / failed (+ the failing assertion or timeout) / skipped.
+
+---
+
+## PHASE 6 — Write Results Back + Report
+
+1. **Update the tracker** (`tracker-format.md` schema): for each executed case set
+   `Initial Behaviour – Testing 1` to `✅ As Expected` / `❌ Different — <detail>` / `⏭️ Skipped — <reason>`
+   and `Status` to `Pass` / `Fail` / `Not Tested`. Use openpyxl (see `step-mapping.md` §Writing results back).
+   If the cases live only in-conversation, produce the updated tracker instead.
+2. **Allure report**: `npm run allure:generate && npm run allure:open` (or `npm run allure:serve`).
+3. Print the summary:
+
+```
+Automation Run — [Feature]  (specs/[slug].spec.ts)
+Generated:  [n] tests   Ran: [n]
+✅ Passed:  [n] — [IDs]
+❌ Failed:  [n] — [IDs]  → [one-line cause each]
+⏭️ Skipped: [n] — [IDs]
+New page-object methods added: [list or none]
+Report: [allure path]   Tracker updated: [path]
+```
+
+For any ❌: say whether it looks like a **product bug** (hand back to qa-ui-run → `clickup-ticket.md`) or a
+**test/selector issue** (offer to adjust the generated test and re-run just that case).
+
+> **Step record (Phase-2).** After finishing this phase, write `$RUN_DIR/steps/playwright-gen-run.json` per `eval.md`:
+> `input` = passing cases, `output` = `{ "artifact": "<spec file paths + tracker results + Allure path>", "summary": "<n specs generated / passed / failed>" }`,
+> `self_check` = `{ "passed": <bool>, "notes": "spec compiles+ran, no hallucinated page-object methods, results written back to tracker" }`, `verdict: null`
+> (only qa-eval fills `verdict`). Append the same to `$RUN_DIR/logs/playwright-gen.jsonl`.
+
+---
+
+## PHASE 7 — Handoff / Next Steps
+
+- Offer to run the other track's cases, add more cases (bump effort), or wire the spec into CI.
+- If this was invoked by `qa-kit`/`qa-ui-run`, report the artefacts produced (spec file, Allure report,
+  updated tracker) back up so the orchestrator can close out.
+
+---
+
+## Handoff contract (what qa-ui-run prints before invoking you)
+
+```
+=== PLAYWRIGHT-GEN HANDOFF (from qa-ui-run) ===
+Feature:            [name]            Slug: [kebab]
+Product:            HIG / Omni / Both
+Effort level:       smoke / standard / exhaustive
+Repo root:          [abs path to poc-playwright/playwright-hig-automation]
+Tracker:            [path to TestTracker_*.xlsx  OR  "cases in conversation"]
+Automatable cases:  [TC IDs qa-ui-run marked single-account / non-failure-sim / passed]
+Skip (manual):      [TC IDs + reason]
+Existing page objects: [e.g. HiverNotesPage @ pages/hiver-notes.page.ts]
+Live observations:  [selectors/timing from qa-ui-run browser pass, if any]
+=== END HANDOFF ===
+```
+
+If a field is missing, fill it in Phase 0/1 — don't stall.
+
+---
+
+## Notes
+
+- You are the ONLY skill that writes into the Playwright repo. Keep changes surgical: one spec file,
+  plus small clearly-marked page-object additions when approved. Never refactor existing page objects.
+- Don't duplicate triage or test-case authoring — that's `qa-kit`/`qa-ui-run`. You consume their output.
+- Prefer reusing a method over adding one. Prefer skipping-with-a-note over an invented selector.
+- The repo is the source of truth for *how* to drive Hiver; the tracker is the source of truth for
+  *what* to verify. Your job is to connect them.
+
+---
+
+## Finish — grade the run.
+
+When the track is done (bugs filed, and any playwright-gen automation complete), invoke `qa-eval`
+(Skill tool, `skill: qa-eval`) on this run. Safe to re-run; in a mixed run the last invocation
+produces the complete report. Do not block on its result.

package/collections/qa-skills/skills/playwright-gen/references/codegen-conventions.md

@@ -0,0 +1,100 @@
+# Codegen Conventions — match the repo's house style exactly
+
+Generated specs must be indistinguishable from hand-written ones in the `poc-playwright` /
+`playwright-hig-automation` repo. These rules are distilled from that repo's `CLAUDE.md`. When the
+repo's `CLAUDE.md` and this file disagree, **the repo wins** — re-read it in Phase 1.
+
+## The golden template
+
+Study `specs/hiverNotes.spec.ts` before generating — it is the reference for imports, structure, and
+idiom. A generated single-persona test should look like this:
+
+```typescript
+/**
+ * @description One-sentence summary of what this test verifies and why.
+ * @steps
+ * 1. First user-visible action
+ * 2. Second user-visible action
+ * 3. Verification
+ * @expects
+ * - Concrete observable outcome 1
+ * - Concrete observable outcome 2
+ */
+import { allure } from 'allure-playwright'
+import { test, expect } from '../fixtures/auth.fixture'
+import { HiverNotesPage } from '../pages/hiver-notes.page'
+
+test.describe('Hiver Notes', () => {
+  test.setTimeout(120_000)
+
+  test('descriptive name — maps to the tracker case title', async ({ authedPage }) => {
+    allure.description('Full intent — what + why.')
+    allure.label('feature', 'Hiver Notes')
+
+    const tag = Date.now().toString().slice(-6)   // unique run data
+    const noteText = `note ${tag}`
+    const notes = new HiverNotesPage(authedPage)
+
+    await allure.step('Open first SM conversation', async () => {
+      await notes.openFirstSmConversation()
+    })
+
+    await allure.step('Add a note', async () => {
+      await notes.addNote(noteText)
+    })
+
+    await allure.step('Verify the note is saved', async () => {
+      await notes.verifyNotePresent(noteText)
+    })
+  })
+})
+```
+
+## Hard rules
+
+1. **Imports** — `test`/`expect`/`personaContext` come from the fixture, not `@playwright/test`:
+   `import { test, expect, personaContext } from '../fixtures/auth.fixture'`. Page objects via the
+   repo's path aliases (`@pages/…`) or relative (`../pages/…`) — match the golden template's choice.
+2. **Fixtures** — single persona → `async ({ authedPage })`. Multi-persona → get the second persona
+   from `personaContext('steve', 1)` and ALWAYS clean up in `finally { await cleanup() }`.
+3. **JSDoc above every test** with `@description` / `@steps` / `@expects`, AND matching
+   `allure.description()` + `allure.label('feature', '<Feature>')` inside. They must not contradict.
+4. **Allure steps** — one per user-visible outcome, aim for **3–7 per test**. Never wrap every click.
+   Step labels should read like the tracker's Test Steps.
+5. **Assertions — two tiers**:
+   - single fact → `expect()` in the spec (`await expect(notes.noteText).toHaveText('hi')`),
+   - compound/domain-meaningful → an `expect*`/`verify*` method on the page object.
+6. **Locators** — you generally don't write locators; you call page-object methods. If you must add a
+   locator to a page object, use the **public getter** pattern (`get x(): Locator { return this.page.locator(...) }`),
+   never a `private readonly` field in the constructor.
+7. **Variable names — full, no short aliases** (ESLint `id-length` min 3). `const sendActions = …`,
+   not `const sa = …`. Allowed short names: `i`, `j`, `e`, `r`, `t`, `el`, `id`, `_`.
+8. **Timeouts** — set a realistic `test.setTimeout()` per test (Hiver flows are slow; existing specs
+   use 120k–600k). Prefer `test.setTimeout()` inside each test over relying on describe-level config
+   (the repo notes `-g` filtering makes describe-level timeouts unreliable in PW 1.59.1).
+9. **Unique data** — anything created (notes, subjects, tags) gets a `Date.now().toString().slice(-6)`
+   suffix so re-runs don't collide. Keep it short — Hiver truncates some fields (~28 chars for notes).
+10. **No invented selectors in the spec.** Selectors live in page objects only. A spec that contains
+    `page.locator('...')` for feature UI is a smell — move it to (or reuse from) the page object.
+
+## Multi-persona shape (only when the case genuinely needs two accounts)
+
+```typescript
+const { page: stevePage, cleanup } = await personaContext('steve', 1)
+try {
+  const steveNotes = new HiverNotesPage(stevePage)
+  // ... drive steve alongside authedPage (tony) ...
+} finally {
+  await cleanup()   // closes context + deletes temp profile — never skip
+}
+```
+
+Cross-persona sync is slow (30–90s) and thread IDs are non-portable across Gmail accounts — see the
+repo's HIVER-QUIRKS. Only generate multi-persona tests when the tracker case is explicitly cross-user
+AND the user opted into it; otherwise it's a "manual-only" case.
+
+## What "done" looks like
+
+- `npm run typecheck` passes on the new file.
+- `npm run lint` has no new errors (id-length, unused imports).
+- The file reads like the golden template — a reviewer can't tell it was generated.

package/collections/qa-skills/skills/playwright-gen/references/step-mapping.md

@@ -0,0 +1,137 @@
+# Step Mapping — tracker row → Playwright calls
+
+This is the translation logic: how a single tracker case becomes a `test()`, which cases you attempt,
+what to do when a method is missing, and how to read/write the tracker file.
+
+## The automatable filter
+
+Classify EVERY case into exactly one bucket. Mirror qa-ui-run's skip rules so the two tracks agree.
+
+**Automatable** — attempt it — when ALL hold:
+- Single account (only `authedPage`/Tony needed), OR multi-persona explicitly in scope.
+- It's a UI happy-path, validation, or configuration flow.
+- Every Test Step maps to a method in the Phase-1 catalog (or one the user approves adding).
+- No dependence on inspecting analytics/network or simulating a backend failure.
+
+**Needs new method** — automatable but a step has no matching page-object method. List the missing
+capability precisely (e.g. *"TC-07 needs `HiverNotesPage.filterByAuthor(name)` — no equivalent getter"*).
+
+**Manual-only** — skip, and record the reason in the tracker's Testing-1 column as `⏭️ Skipped — <reason>`:
+- Two simultaneous accounts when multi-persona wasn't opted into → *"requires multi-account setup"*.
+- Any network-inspection assertion → *"requires network inspection"*. (Only internal Gainsight event-tracking is out of scope — a customer-facing analytics dashboard/report IS automatable UI: reading rendered metrics/charts and checking they reconcile is normal verification.)
+- Backend/API failure simulation → *"requires API error simulation"*.
+- Anything the tracker already marked `⏭️ Skipped` in the browser pass.
+
+Never silently drop a case. If unsure, put it in "needs new method" and ask.
+
+## Mapping the fields
+
+| Tracker field | Becomes |
+|---|---|
+| **Test Case** (title) | the `test('…')` name + `@description` + `allure.description()` |
+| **Pre-conditions** | setup `allure.step` — `openFirstSmConversation()`, persona init, `mustEnv()` reads. `SM:`/`Extension:` notes are context, not code. |
+| **Test Data** | `const` values at the top of the test, tagged unique where created. |
+| **Test Steps** (numbered) | grouped into 3–7 `allure.step()` blocks of page-object calls, in order. |
+| **Expected Result** (numbered) | assertions — `expect()` for single facts, `expect*`/`verify*` page-object methods for compound checks. Put them in the step whose outcome they verify, or a final "Verify …" step. |
+| **Priority** | ordering only (P0 first). Doesn't change the code. |
+
+### Worked example
+
+Tracker row:
+```
+TC: A-02 · "Verify a saved note appears in the activity panel"
+Pre: Logged in as Tony · SM: sdf · Extension v7.5.40
+Steps: 1. Open first SM conversation  2. Click Add a note  3. Type text  4. Save
+Expected: 1. Editor opens  2. Note appears in the activity panel with the typed text
+```
+Maps to (reusing `addNote` which already encapsulates click→type→save):
+```typescript
+test('A-02: a saved note appears in the activity panel', async ({ authedPage }) => {
+  test.setTimeout(120_000)
+  allure.description('Verify a saved note appears in the activity panel with the typed text.')
+  allure.label('feature', 'Hiver Notes')
+
+  const tag = Date.now().toString().slice(-6)
+  const noteText = `panel-check ${tag}`
+  const notes = new HiverNotesPage(authedPage)
+
+  await allure.step('Open first SM conversation', async () => {
+    await notes.openFirstSmConversation()
+  })
+  await allure.step('Add a note', async () => {
+    await notes.addNote(noteText)
+  })
+  await allure.step('Verify the note appears in the activity panel', async () => {
+    await notes.verifyNotePresent(noteText)
+  })
+})
+```
+Note how four literal UI steps collapsed into the existing `addNote()` — prefer the coarse existing
+method over re-implementing click/type/save. That's what keeps generated tests green.
+
+## Missing-method policy
+
+When a case is "needs new method" and the user approved generating it:
+- Add the **smallest** method to the relevant `pages/*.page.ts`, reusing existing getters and the
+  `dismissMuiOverlays()`/`waitForRightPanel()` helpers from `BasePage`.
+- Follow the getter-locator pattern; give it a clear name (`verb + object`).
+- Mark it: `// [playwright-gen] added for TC-07 — filter notes by author`.
+- Show the diff before writing. Re-run `npm run typecheck`.
+
+When NOT approved: emit the test with `test.fixme('TC-07 — needs HiverNotesPage.filterByAuthor')`
+so the intent is captured in the file and shows as skipped, not lost.
+
+Never write a raw feature selector inline in the spec as a shortcut — untested selectors are the #1
+cause of a generated test failing on stage.
+
+## Reading the tracker (when input is an .xlsx, not in-conversation cases)
+
+Prefer the confirmed cases already in the conversation. If you must parse the file, use openpyxl:
+
+```python
+# needs a python with openpyxl. If none: python3 -m venv ~/.qa-venv && ~/.qa-venv/bin/pip install openpyxl
+from openpyxl import load_workbook
+wb = load_workbook("TestTracker_HiverNotes_2026-07-09.xlsx")
+ws = wb["Test Cases"]
+headers = [c.value for c in ws[1]]                 # row 1 = header (frozen)
+col = {h: i for i, h in enumerate(headers)}
+for row in ws.iter_rows(min_row=2, values_only=True):
+    if row[col["TC ID"]] is None:                  # skip merged section-header rows
+        continue
+    tc = {h: row[col[h]] for h in headers}
+    # tc["Test Case"], tc["Test Steps"], tc["Expected Result"], tc["Priority"], ...
+```
+Section-header rows are merged and have no TC ID — skip them. Steps/Expected are newline-separated
+within one cell.
+
+## Writing results back
+
+After the run, set two columns per executed case and save the workbook:
+
+```python
+TESTING1 = col["Initial Behaviour – Testing 1"]   # yellow column
+STATUS   = col["Status"]
+# map a case id → outcome from the playwright run
+for row in ws.iter_rows(min_row=2):
+    tc_id = row[col["TC ID"]].value
+    if tc_id in results:
+        r = results[tc_id]                          # {'testing1': '✅ As Expected', 'status': 'Pass'}
+        row[TESTING1].value = r["testing1"]
+        row[STATUS].value   = r["status"]
+wb.save(path)
+```
+Values must match the schema: Testing-1 uses `✅ As Expected` / `❌ Different — <detail>` /
+`⚠️ Partial — <detail>` / `⏭️ Skipped — <reason>`; Status uses `Pass` / `Fail` / `Bug` / `Blocked` /
+`Not Tested`. Don't touch the "Testing 2" column — that's the QA engineer's manual pass.
+
+## Parsing the Playwright run
+
+Get machine-readable results with the JSON reporter, then map test titles → TC IDs (put the TC ID at
+the start of each test title so this is trivial):
+
+```bash
+npx playwright test specs/hiverNotes.spec.ts --reporter=json > run.json
+```
+`suites[].specs[].tests[].results[].status` gives `passed` / `failed` / `skipped` / `timedOut`. A
+`failed`/`timedOut` → `❌ Different` + `Fail`; grab the error message for the detail. `skipped` (from
+`test.fixme`) → `⏭️ Skipped`. Keep the Allure reporter too (config already has it) for the visual report.