@edupia-tutor/spec-driven-docs 0.14.0

package/commands/map-testids.tmpl

@@ -0,0 +1,81 @@
+# /map-testids — Define/backfill stable test-ids onto reused & existing FE components
+
+> Companion to the FE tech-design §2b *Test Selectors* contract. `/generate-tech-docs` (FE) and
+> `/generate-code` assign test-ids to **new** code; this command handles the rest: **reused**
+> catalog components (id lives at the usage site; the component must *forward* a test-id) and
+> **existing / brownfield** screens already coded without test-ids. It reverse-documents what
+> exists, assigns stable ids where missing, ensures reusable components forward an id, records the
+> forwarding in the figma-components catalog, patches usage sites, and writes the §2b map — so QC
+> locates elements by id instead of scanning at runtime.
+
+Usage: `/map-testids {UC-ID}`
+
+## Gate
+{{include:steps/gate.md}}
+
+*Note: For this command, the target in Step 1 is a UC-ID. Read the UC's FE `.feature` (web/app), its Design Spec screens, the FE tech-design `{paths.tech_docs_dir}/{domain}/{prd-slug}/tech-docs/{UC-ID}-tech-design-{platform}.md` (if any), and the figma-components catalog for `active_module`.*
+
+## Context
+{{include:steps/context-loader.md}}
+
+---
+
+## Step 0 — Platform guard
+
+Resolve `platform` from `@trace.platform` / `platform_type`. Test-ids are a **FE/App** concern — if `system` / backend → HALT:
+```
+❌ /map-testids applies to FE/App (web/app) only. BE has no UI test-ids.
+```
+Resolve the test-id attribute from `@trace.testid_attr` (or by module): web `data-testid` · React Native `testID` · Flutter `Key`/`Semantics(identifier:)` · native iOS `accessibilityIdentifier`.
+
+## Step 1 — Collect actionable elements
+
+From the UC's FE `.feature` `When` steps + the Design Spec screens, list every **actionable** element the scenarios touch (button, input, link, select, toggle, form-submit). Skip static text/labels. For each, resolve the rendering component and classify:
+- **reused** — matches a row in the figma-components catalog (shared design-system component);
+- **existing** — feature-specific component already in the codebase (brownfield);
+- **new** — not yet coded (leave to `/generate-code`; just record the intended id).
+
+## Step 2 — Resolve a stable test-id per element
+
+- **Existing/brownfield:** read the component file. If the element **already** has a test-id (in the platform attribute) → **reverse-document** it (reuse as-is). Else assign by convention `{uc-lower}-{screen}-{element}-{type}` (e.g. `ft001-login-submit-btn`). Never embed the scenario number.
+- **Reused:** the id is applied at the **usage site** (not baked into the shared component) → assign by the same convention.
+- **Cross-platform:** if the **other** platform's tech-design (`{UC-ID}-tech-design-{web|app}.md`) already has a §2b id for the same logical element, **reuse that id value** (only the attribute differs per platform) so web and app stay consistent and QC logic is portable.
+
+## Step 3 — Ensure reusable components forward a test-id (catalog)
+
+For each **reused** actionable component, consult the catalog's **`## Test-ID Forwarding`** section (`{paths.domain_knowledge_dir}/figma-components/{active_module}.md`):
+- **Forwarding prop recorded** → use it at the usage site (Step 4).
+- **Not recorded** → inspect the component source:
+  - Already forwards (spreads `...props` / has a `testId`/`testID` prop / passes the attribute through) → **record** the prop in the catalog's Test-ID Forwarding table.
+  - Does **not** forward → **patch the component ONCE** to accept + forward a test-id (web: add prop `testId` → render `data-testid={testId}`; RN: `testID`; Flutter: pass `Key`/`Semantics(identifier:)`; iOS: `accessibilityIdentifier`), then record it in the catalog.
+
+Print every catalog row added and every shared component patched (these touch shared code — call them out for review).
+
+## Step 4 — Patch usage sites (EXTEND only)
+
+For each actionable element in this UC's **existing/reused** screens, add the test-id at the usage site — the raw attribute for plain elements, or the forwarding prop for a reused component — with the id from Step 2. **EXTEND mode:** touch only the attribute/prop; do not refactor anything else. Skip elements already carrying the correct id (idempotent).
+
+## Step 5 — Write/refresh the §2b Test Selectors map
+
+Create or update §2b of `{paths.tech_docs_dir}/{domain}/{prd-slug}/tech-docs/{UC-ID}-tech-design-{platform}.md`:
+- If the FE tech-design exists → update its §2b table.
+- If it does **not** exist yet (pure brownfield) → write a minimal file: the `@trace` header (incl `@trace.testid_attr`) + only §2b. `/generate-tech-docs` (FE) fills the remaining sections later; it must not overwrite the §2b ids this command recorded.
+
+Each row: `Test-ID | Element | Component (reused/existing/new) | Action | Serves SC`.
+
+## Step 6 — Handoff
+
+If the tech-design lives in the shared spec repo (`spec_source` set), commit + push (2-layer) like `/generate-tech-docs`. Shared-component patches go in the FE service submodule (2-tang push, see Sync & Update §4.4).
+
+## Output
+
+{{include:steps/report-footer.md}}
+
+```
+/map-testids Complete — {UC-ID} ({platform})
+Elements: {N} mapped — {reused} reused · {existing} existing (backfilled) · {new} deferred to /generate-code
+Forwarding: {M} shared components patched to forward a test-id · {K} catalog rows recorded
+§2b: {paths.tech_docs_dir}/{domain}/{prd-slug}/tech-docs/{UC-ID}-tech-design-{platform}.md updated ({N} selectors)
+Next: /review-tech-docs {tech-design}   ← review the §2b map + shared-component patches
+      /qc-design-test {UC-ID}            ← QC now locates by test-id (no scan)
+```