@mmerterden/multi-agent-pipeline 8.6.0

package/pipeline/skills/figma-ios/figma-to-component/phases/phase-5-orchestrator.md

@@ -0,0 +1,482 @@
+# PHASE 5 — Testing Orchestrator
+
+Orchestrates Phase 5 sub-phases: dispatches sub-agents to write test files, collects results.
+PREV: Phase 4 (Implementation)
+NEXT: Phase 6 (Code Connect Publish)
+
+**Date Format:** Use `DD.MM.YYYY` format (e.g., `23.02.2026`) for file headers.
+
+---
+
+## PURPOSE
+
+Phase 5 generates tests for the implemented component.
+Each sub-phase writes test files in a specific testing category.
+Phase 6 (Code Connect) consumes the verified component.
+
+---
+
+## PRE-CHECK: Phase 4 Complete
+
+```
+Read: {artifactPath}/IMPLEMENTATION_HISTORY.md
+Read: {artifactPath}/pass3/_index.md
+Read: {artifactPath}/pass3/04b_component_architecture.md
+```
+
+EXTRACT:
+- `componentName`
+- `artifactPath`
+- `sourceModule` (e.g., `UIComponents`)
+- `sourceLocation` (full path to component Swift file)
+- `componentPath` (path after `Sources/<Module>/`, e.g., `Components/MobileAppComponents/Components/Badges/LabelBadge`)
+
+Verify the component Swift file exists at `sourceLocation`.
+
+| Result | Action |
+|--------|--------|
+| All files exist + component Swift file exists | Proceed to CREATE_TEST_INDEX |
+| Missing | HALT |
+
+FAIL →
+```
+STATUS: HALT
+PHASE: phase-5
+GATE: PRE_CHECK
+REASON: Phase 4 artifacts or component Swift file not found.
+COMPLETED_GATES: []
+ARTIFACTS_CREATED: none
+USER_ACTION_REQUIRED: Run Phase 4 first.
+```
+
+---
+
+## GATE 1: CREATE_TEST_INDEX
+
+Create a single index file that maps to all artifact paths used by test sub-phases.
+This is the ONLY file that knows where artifacts live — sub-phases read this index.
+
+### 1.1 Write `{artifactPath}/pass5/_test_index.md`
+
+```markdown
+# Test Index
+
+Component: {componentName}
+Generated: {DD.MM.YYYY}
+
+## Component Source
+
+| Field | Value |
+|-------|-------|
+| Module | {sourceModule} |
+| Source File | {sourceLocation}/{componentName}.swift |
+| Configuration File | {sourceLocation}/{componentName}Configuration.swift |
+| Component Path | {componentPath} |
+
+## Artifact Paths
+
+| Artifact | Path | Used By |
+|----------|------|---------|
+| Component Properties | {artifactPath}/pass1/component_properties.json | 5A, 5B |
+| Testing Identifiers | {artifactPath}/pass2/utility_identifiers.md | 5A |
+| Component Architecture | {artifactPath}/pass3/04b_component_architecture.md | 5B |
+| Patterns | {artifactPath}/pass3/04_patterns.md | 5B |
+| Complexity | {artifactPath}/pass3/05_complexity.md | 5A |
+| Utility Integration | {artifactPath}/pass3/08_utility_integration.md | 5A |
+
+## Test Targets
+
+| Category | Target | Base Path |
+|----------|--------|-----------|
+| ViewInspector | {sourceModule}Tests | Tests/{sourceModule}Tests/ViewInspector/{componentPath}/ |
+| Snapshot | {sourceModule}Tests | Tests/{sourceModule}Tests/Snapshot/{componentPath}/ |
+| Unit | {sourceModule}Tests | Tests/{sourceModule}Tests/Unit/{componentPath}/ |
+
+## Test Files (populated by sub-phases)
+
+| Sub-Phase | File | Status |
+|-----------|------|--------|
+| 5A ViewInspector | {componentName}ViewInspectorTests.swift | pending |
+| 5B Snapshot | {componentName}SnapshotTests.swift | pending |
+| 5C Unit | {componentName}Tests.swift | pending / N/A |
+```
+
+---
+
+## ROUTING
+
+### Sub-Phase Inventory
+
+| Sub-Phase | File | Purpose | Required |
+|-----------|------|---------|----------|
+| 5A | `phase-5a-viewinspector.md` | ViewInspector structure + accessibility tests | **ALWAYS** |
+| 5B | `phase-5b-snapshot.md` | Snapshot tests for ALL Figma variants | **ALWAYS** |
+| 5C | `phase-5c-unit.md` | Unit tests for ViewModel/model logic | **CONDITIONAL** — only if testable logic exists |
+
+### Execution Flow
+
+```
+GATE 1: CREATE_TEST_INDEX
+    ↓
+Wave 1 (parallel):
+    5A — ViewInspector structure tests
+    5B — Snapshot visual tests
+    ↓
+Wave 2 (conditional):
+    5C — Unit tests (ONLY if component has ViewModel/model logic)
+    ↓
+GATE 2: UPDATE_TEST_INDEX
+    ↓
+GATE 3: TEST_EXECUTION (xcodebuild test — builds + runs, zero warnings, all tests pass)
+    ↓
+GATE 4: TEST_FILE_VALIDATION
+    ↓
+GATE 5: UPDATE_REGISTRY (phase5-finalize.py)
+    ↓
+PHASE OUTPUT
+```
+
+### Sub-Phase Inputs
+
+All sub-phases read from `{artifactPath}/pass5/_test_index.md` for paths.
+They then read the actual artifact files listed in the index — no data duplication.
+
+| Sub-Phase | Reads From (via index) |
+|-----------|----------------------|
+| 5A | component_properties.json, utility_identifiers.md, utility_integration.md |
+| 5B | component_properties.json, 04b_component_architecture.md, 04_patterns.md |
+| 5C | Component source file (scan for ViewModel/models) |
+
+---
+
+## GATE 2: UPDATE_TEST_INDEX
+
+After all sub-phases complete, update `pass5/_test_index.md`:
+- Set each sub-phase status to `complete` or `N/A`
+- Record test counts
+
+---
+
+## GATE 3: TEST_EXECUTION
+
+Build and run tests using the `run-uicomponents-tests.sh` script. The script uses `xcodebuild test` which builds before testing — no separate build gate is needed. This gate requires **zero build warnings** and **all tests passing**.
+
+### How it works
+
+The script runs tests via the `UIComponents-Package` scheme inside the SPM package directory (`{repos.components.path}/`). This uses the package's own umbrella scheme, avoiding the need for any one-time Xcode setup. The `xcodebuild test` command compiles first (catching build errors with exit code 65) then runs the tests.
+
+### Switch to local common dependency
+
+The UIComponents SPM package resolves `{project.slug}-common` from remote git, but Phase 2 adds identifiers/keys to the local editable copy. Before running tests, in `{repos.components.path}/Package.swift`, comment out the `.package(url: "...{project.slug}-common...", ...)` line and add `.package(path: "../{project.slug}-common"),` below it.
+
+### Run tests
+
+Run each test class separately to isolate failures:
+
+```bash
+REPO_ROOT=$(git rev-parse --show-toplevel)
+bash "${REPO_ROOT}/.instructions/figma/figma-to-swiftui/scripts/run-uicomponents-tests.sh" \
+    --filter "{ComponentName}ViewInspectorTests"
+```
+
+```bash
+bash "${REPO_ROOT}/.instructions/figma/figma-to-swiftui/scripts/run-uicomponents-tests.sh" \
+    --filter "{ComponentName}SnapshotTests"
+```
+
+For unit tests (if 5C was generated):
+
+```bash
+bash "${REPO_ROOT}/.instructions/figma/figma-to-swiftui/scripts/run-uicomponents-tests.sh" \
+    --filter "{ComponentName}Tests"
+```
+
+### Revert to remote dependency
+
+After all tests pass, uncomment the original `.package(url: ...)` line and remove the `.package(path: ...)` line in `Package.swift`.
+
+**Important:** Do NOT run multiple test filters in parallel — they share the same DerivedData build database and will fail with a database lock error. Run them sequentially.
+
+**Note on first-run snapshots:** When snapshot tests run for the first time, `record: .missing` mode will **record** reference images (not fail). The test passes but creates new `__Snapshots__/` directories with `.png` files. These reference images are **gitignored** and must NOT be committed — they are re-recorded automatically on each machine. The wiki/Confluence skill copies them from disk for documentation before they are discarded.
+
+### required GATE — SNAPSHOT_DESIGN_FIDELITY
+
+Snapshot tests passing does NOT mean the rendered component matches the Figma design. It only means "the pixels we recorded match the pixels we recorded". A broken test scaffold (missing image prefetch per `phase-5b-snapshot.md § GATE 3.0.1`, wrong hosting frame, clipped layout, misapplied modifier) records a broken render as "ground truth" and every subsequent run compares broken-vs-broken and reports PASS. The test infrastructure CANNOT catch this class of failure by itself.
+
+This gate runs automatically after `TEST_EXECUTION` succeeds, every time Phase 5B recorded or re-recorded snapshots (first run or after a test-file change). It is performed by the orchestrator itself — no user involvement, no pause for confirmation.
+
+**Procedure** (automated fix-and-retry loop, up to 4 attempts):
+
+1. Read `{artifactPath}/pass1/screenshot.png` — the Figma reference captured in Phase 1. (Claude is multimodal and sees images via the Read tool.)
+2. Read the LTR light variant from `__Snapshots__/{componentName}SnapshotTests/test_snapshot_light_default.light_default.png` (or the equivalent default-variant filename).
+3. Compare them directly in the orchestrator's own visual judgement — layout, proportions, hierarchy, typography, colors, gradients, background content, text legibility.
+4. **If match** (all match criteria hold): proceed to Phase 6.
+5. **If mismatch** (any non-match criterion triggers): do NOT halt on the first failure. Instead enter the fix-and-retry loop:
+
+    a. **Diagnose the specific mismatch**: what differs, where, and the most likely cause (component layout bug, wrong token, test scaffold issue, etc.). Write the diagnosis to `{artifactPath}/pass5/fidelity_attempt_{N}.md`.
+
+    b. **Apply a fix**:
+       - If the fault is in the component source (wrong modifier order, wrong token, missing effect, clipped layout), edit `{sourceLocation}/{componentName}.swift` (and/or Configuration file) to correct it.
+       - If the fault is in the test scaffold (missing image prefetch, wrong hosting frame, padding outside the frame), edit the snapshot test file.
+       - Do NOT edit Figma or claim the Figma reference is wrong.
+
+    c. **Delete stale snapshots** at `__Snapshots__/{componentName}SnapshotTests/` so the next test run re-records against the fixed component/scaffold.
+
+    d. **Re-run Phase 5B** via `run-uicomponents-tests.sh --filter "{componentName}SnapshotTests"`. The first run records; if you need a clean compare, run again.
+
+    e. **Re-compare** the new snapshot against `pass1/screenshot.png`. Go back to step 3.
+
+6. **Attempt budget**: up to 4 fix attempts total. After the 4th failed attempt, HALT with:
+
+    ```
+    STATUS: HALT
+    PHASE: phase-5
+    GATE: SNAPSHOT_DESIGN_FIDELITY
+    REASON: Rendered snapshot does not match Figma after 4 fix attempts.
+    ATTEMPTS:
+      1. {diagnosis and fix summary from fidelity_attempt_1.md}
+      2. {diagnosis and fix summary from fidelity_attempt_2.md}
+      3. {diagnosis and fix summary from fidelity_attempt_3.md}
+      4. {diagnosis and fix summary from fidelity_attempt_4.md}
+    CURRENT_MISMATCH: {description of the remaining delta}
+    USER_ACTION_REQUIRED: The mismatch is beyond automated repair. Review pass5/fidelity_attempt_*.md to see what was tried, then inspect the component manually.
+    ```
+
+7. **Counter tracking**: the attempt counter lives in the orchestrator's own task state — do NOT rely on grepping files. Increment after every mismatch-driven fix. Reset only on successful match.
+
+**Match criteria** (all must hold):
+- Overall layout, proportions, and hierarchy match Figma
+- Typography sizes, weights, and colors are correct
+- Background images (remote or local) actually render content, not placeholders / spinners / blank areas
+- Gradients, shadows, blur effects are visible at roughly the intensity shown in Figma
+- Text is legible and positioned where Figma shows it
+
+**Non-match criteria** (any one triggers HALT):
+- Loading spinner instead of the image
+- Text clipped or overflowing the container
+- Gradient baked in but invisible because of layout bugs
+- Wrong typography weight / size
+- Colors that look "close enough" but don't match Figma tokens
+- Any case where the recorded snapshot is visibly different from `pass1/screenshot.png` beyond expected aspect-ratio or sample-data differences
+
+**Never ask the user to confirm the match**. The orchestrator is multimodal and has direct visual access to both images. Surfacing the images to the user and asking for confirmation is forbidden — it wastes a round-trip and makes the gate advisory instead of blocking. The orchestrator makes the judgement itself, enters the fix loop on mismatch, and only HALTs after the 4-attempt budget is exhausted.
+
+**Never explain away a mismatch**. If the visual comparison shows a clear difference, enter the fix loop — do not rationalise that the snapshot is "close enough" or that the difference is "just the sample image". Ambiguous cases also enter the fix loop and surface the specific concern in the `fidelity_attempt_{N}.md` diagnosis.
+
+### Pass criteria
+
+Both conditions must be met:
+
+1. **All tests pass** — exit code 0, no test failures
+2. **Zero build warnings** — review xcodebuild output for warnings in the component's test files. Fix any warnings before proceeding.
+
+### Exit codes
+
+| Exit Code | Meaning | Action |
+|-----------|---------|--------|
+| 0 (PASS) | Build clean + all tests passed | Check output for warnings, then proceed to GATE 4 |
+| 2 (PACKAGE_NOT_FOUND) | UIComponents package directory missing | Verify package path exists |
+| 3 (NO_SIMULATOR) | No available iPhone simulator | Install an iOS Simulator runtime via Xcode > Settings > Platforms |
+| 65 (BUILD_FAIL) | Compilation failed | Read error output, fix build errors, re-run |
+| 1 (TEST_FAIL) | One or more tests failed | Read test output, fix failing tests, re-run |
+
+### Common build errors and fixes
+
+| Error | Fix |
+|-------|-----|
+| Missing import | Add `import SnapshotTesting`, `import ViewInspector`, or `@testable import UIComponents` |
+| `@MainActor` missing | Add `@MainActor` on the test class (Swift 6 strict concurrency requires this for classes using SwiftUI views or UIHostingController) |
+| Unknown helper method | Ensure `assertSnapshot`/`assertSnapshotDarkMode`/`assertSnapshotRTL`/`assertSnapshotRTLDarkMode` are defined in the test file |
+
+### Warning policy
+
+After tests pass (exit 0), review the output for any warnings in the component's test files. Common warnings to fix:
+
+| Warning | Fix |
+|---------|-----|
+| `'Inspectable' is deprecated` | Remove the `extension {ComponentName}: Inspectable {}` line — no longer required by ViewInspector |
+| `main actor-isolated property` | Add `@MainActor` to the test class |
+| Unused variable | Remove or use the variable |
+
+If warnings are found: fix them, re-run tests, confirm exit 0 with clean output.
+
+If tests fail:
+
+```
+STATUS: HALT
+PHASE: phase-5
+GATE: TEST_EXECUTION
+REASON: Test execution failed.
+TEST_ERRORS: {error output from xcodebuild test}
+COMPLETED_GATES: [PRE_CHECK, CREATE_TEST_INDEX, ROUTING, UPDATE_TEST_INDEX]
+USER_ACTION_REQUIRED: Fix the failing tests and re-run.
+```
+
+---
+
+## GATE 4: TEST_FILE_VALIDATION
+
+Validate that all generated test files follow the required patterns and that no tests are skipped.
+
+### 5.1 Structural validation — ViewInspector test file
+
+Check the ViewInspector test file at `Tests/{sourceModule}Tests/ViewInspector/{componentPath}/{componentName}ViewInspectorTests.swift`:
+
+```
+[ ] File exists
+[ ] Has `import ViewInspector`
+[ ] Has `import XCTest`
+[ ] Has `@testable import UIComponents`
+[ ] Does NOT have `extension {ComponentName}: Inspectable {}` (deprecated since ViewInspector 0.10+)
+[ ] Class is `@MainActor final class {ComponentName}ViewInspectorTests: XCTestCase`
+[ ] Has `makeSUT()` helper method
+[ ] Has `test_viewExists()` test
+[ ] Has `test_containsExpectedSubviews()` test
+[ ] Has variant rendering tests (e.g., `test_allStatesRender`)
+[ ] Has accessibility identifier tests for each testing ID
+[ ] No `XCTSkip` — all tests must execute
+[ ] No `throw XCTSkip` — no conditional skipping
+```
+
+### 5.2 Structural validation — Snapshot test file
+
+Check the Snapshot test file at `Tests/{sourceModule}Tests/Snapshot/{componentPath}/{componentName}SnapshotTests.swift`:
+
+```
+[ ] File exists
+[ ] Has `import SnapshotTesting`
+[ ] Has `import XCTest`
+[ ] Has `@testable import UIComponents`
+[ ] Class is `@MainActor final class {ComponentName}SnapshotTests: XCTestCase`
+[ ] Has `override func invokeTest()` with `withSnapshotTesting(record: .missing)`
+[ ] Has light + dark variants for EVERY Figma variant dimension
+[ ] Has RTL variants if component has text/localized content
+[ ] Has 4 snapshot helpers: assertSnapshot, assertSnapshotDarkMode, assertSnapshotRTL, assertSnapshotRTLDarkMode
+[ ] Each helper uses UIHostingController wrapping
+[ ] Each helper uses `.image(precision: 0.99, perceptualPrecision: 0.98)`
+[ ] RTL helpers set `.semanticContentAttribute = .forceRightToLeft`
+[ ] Dark helpers set `.overrideUserInterfaceStyle = .dark`
+[ ] No `XCTSkip` — all tests must execute
+```
+
+### 5.3 Test naming convention
+
+All test methods must follow the naming pattern:
+
+| Test type | Pattern | Example |
+|-----------|---------|---------|
+| ViewInspector | `test_{description}` | `test_viewExists`, `test_containsText` |
+| Snapshot Light | `test_snapshot_light_{variant}` | `test_snapshot_light_success` |
+| Snapshot Dark | `test_snapshot_dark_{variant}` | `test_snapshot_dark_success` |
+| Snapshot RTL Light | `test_snapshot_rtl_light_{variant}` | `test_snapshot_rtl_light_success` |
+| Snapshot RTL Dark | `test_snapshot_rtl_dark_{variant}` | `test_snapshot_rtl_dark_success` |
+
+### 5.4 Variant coverage check
+
+Cross-reference test methods against `pass3/04_patterns.md` variant list:
+
+- Every variant dimension from Figma must have a corresponding **light** snapshot test
+- Every variant dimension must have a corresponding **dark** snapshot test
+- If component has text/localized content: every key variant must have **RTL light** + **RTL dark** tests
+- Boolean toggle variants (e.g., with/without icon) must have separate test methods
+
+| Result | Action |
+|--------|--------|
+| All checks pass | Proceed to PHASE OUTPUT |
+| Any check fails | Fix the violation and re-validate |
+
+If validation fails:
+
+```
+STATUS: HALT
+PHASE: phase-5
+GATE: TEST_FILE_VALIDATION
+REASON: Test file validation failed.
+VIOLATIONS: {list of violations}
+COMPLETED_GATES: [PRE_CHECK, CREATE_TEST_INDEX, ROUTING, UPDATE_TEST_INDEX, TEST_EXECUTION]
+USER_ACTION_REQUIRED: Fix the violations listed above.
+```
+
+---
+
+## GATE 5: UPDATE_REGISTRY
+
+Run the Phase 5 finalize script to mark `tested` in the component registry:
+
+```bash
+python3 .instructions/figma/figma-to-swiftui/scripts/phase5-finalize.py \
+    --node-id "{nodeId}" \
+    --platform ios
+```
+
+| Result | Action |
+|--------|--------|
+| Exit 0, `"action": "updated"` | `status.ios.tested` set green, `against = implemented.version` — proceed |
+| Exit 0, `"action": "already_current"` | Already marked against current implemented.version — proceed |
+| Exit 0, `"action": "created"` | New registry file created — proceed |
+| Exit 1 | HALT — registry update failed |
+
+**Why this matters:** This is the single source of truth for `status.ios.tested`. The script records `against = status.ios.implemented.version` so when the next Phase 4 bumps `implemented.version`, this flag automatically drops to yellow until tests are re-run. `figma-iteration-commit` reads this and syncs the GitHub issue via `update-issue-from-registry.py`.
+
+FAIL →
+```
+STATUS: HALT
+PHASE: phase-5
+GATE: UPDATE_REGISTRY
+REASON: phase5-finalize.py failed.
+COMPLETED_GATES: [PRE_CHECK, CREATE_TEST_INDEX, ROUTING, UPDATE_TEST_INDEX, TEST_EXECUTION, TEST_FILE_VALIDATION]
+USER_ACTION_REQUIRED: Check script error output; verify node-id matches the registry.
+```
+
+---
+
+## PHASE OUTPUT
+
+```
+STATUS: COMPLETE
+PHASE: phase-5
+GATES_PASSED: [PRE_CHECK, CREATE_TEST_INDEX, ROUTING, UPDATE_TEST_INDEX, TEST_EXECUTION, TEST_FILE_VALIDATION, UPDATE_REGISTRY]
+ARTIFACTS_CREATED:
+  - {artifactPath}/pass5/_test_index.md
+SUB_PHASES:
+  - 5A ViewInspector: {COUNT} tests — {testFilePath}
+  - 5B Snapshot: {COUNT} tests ({LIGHT} light + {DARK} dark + {RTL} RTL) — {testFilePath}
+  - 5C Unit: {COUNT} tests or N/A — {testFilePath or N/A}
+TESTS: ✅ PASS (xcodebuild test — zero warnings, all tests green)
+VALIDATION: ✅ PASS (structure + naming + variant coverage)
+SUMMARY: Phase 5 testing complete. {TOTAL} tests across {FILE_COUNT} test files. Zero warnings. All tests passing.
+```
+
+---
+
+## VALIDATION CHECKLIST
+
+```
+[ ] pass5/_test_index.md created with all artifact paths
+[ ] 5A ViewInspector test file created — structure, accessibility, variant rendering tests
+[ ] 5B Snapshot test file created — light/dark/RTL variants, snapshot helpers
+[ ] 5C Unit tests created OR marked N/A (no testable logic)
+[ ] Test index updated with final status
+[ ] All test files follow existing project patterns (XCTest, makeSUT, closure init)
+[ ] xcodebuild test passed (exit 0, all tests green)
+[ ] Zero build warnings in component test files
+[ ] No XCTSkip in any test file — all tests must execute
+[ ] Snapshot test naming follows test_snapshot_{mode}_{variant} convention
+[ ] ViewInspector tests cover all accessibility identifiers
+[ ] Snapshot tests cover ALL Figma variant dimensions (light + dark minimum)
+[ ] RTL snapshot tests present for components with text/localized content
+[ ] Snapshot reference images generated locally (NOT committed — gitignored)
+[ ] phase5-finalize.py passed (status.ios.tested updated)
+```
+
+---
+
+## REFERENCES
+
+| Topic | File |
+|-------|------|
+| Phase 5A | `phase-5a-viewinspector.md` |
+| Phase 5B | `phase-5b-snapshot.md` |
+| Phase 5C | `phase-5c-unit.md` |
+| ViewInspector API | `reference/viewinspector.md` |
+| Snapshot Testing | `reference/snapshot-testing.md` |