@mmerterden/multi-agent-pipeline 11.1.0 → 11.3.0

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

@@ -1,636 +0,0 @@
-# PHASE 5B  -  Snapshot Tests
-
-Snapshot visual regression tests for ALL Figma variants in light and dark mode.
-
-PARENT: `phase-5-orchestrator.md`
-required  -  always execute this sub-phase.
-PARALLEL WITH: Phase 5A (both read from pass5/_test_index.md independently)
-
-**FRAMEWORK**: XCTest with swift-snapshot-testing (via ExternalSnapshotTesting)
-
----
-
-## PRE-CHECK: Load Test Index
-
-```
-Read: {artifactPath}/pass5/_test_index.md
-```
-
-EXTRACT:
-- `componentName`
-- `sourceModule`
-- `componentPath`
-- Artifact paths for: component_properties.json, 04b_component_architecture.md, 04_patterns.md
-
-Then read the actual artifacts to extract:
-- Enum properties (variant axes to snapshot)
-- Optional properties (boolean states to snapshot)
-- Component dimensions (from pass3/04_patterns.md)
-
-If test index missing → HALT, run orchestrator first.
-
----
-
-## GATE 1: DETERMINE_VARIANT_MATRIX
-
-### 1.1 Extract Snapshot Axes
-
-From `pass3/04b_component_architecture.md`, identify all properties that produce visual variations:
-
-| Property Type | Snapshot Treatment |
-|---------------|-------------------|
-| Enum (CaseIterable) | Loop through `.allCases` |
-| Optional Image? | Test with nil + with value |
-| Optional String? | Test with nil + with value |
-| Bool toggle | Test true + false |
-
-### 1.2 Calculate Matrix
-
-List all variant axes and their values. Example:
-
-| Axis | Values | Count |
-|------|--------|-------|
-| state | success, warning, error, standard, secondary | 5 |
-| leftIcon | nil, Image | 2 |
-| text | "Lorem", nil | 2 |
-| Theme | light, dark | 2 |
-
-**Snapshot strategy:**
-- Snapshot each enum case with default values for other properties → `{enum_count}` snapshots
-- Snapshot each optional toggle (with/without) → `{toggle_count}` snapshots
-- All of the above × 2 (light + dark) → total
-
-**DO NOT snapshot full cartesian product** unless total < 20. For large matrices, snapshot:
-1. Each enum case independently (other props at default)
-2. Each optional toggle independently (enum at first case)
-3. Both themes for all above
-
-### 1.3 Extract Dimensions
-
-From `pass3/04_patterns.md`, get component width and height for snapshot frame.
-If not available, use defaults: width=375, height based on component type.
-
----
-
-## GATE 2: DETERMINE_TEST_LOCATION
-
-```
-Test Target: {sourceModule}Tests
-Test Dir:    Tests/{sourceModule}Tests/Snapshot/{componentPath}/
-Test File:   {componentName}SnapshotTests.swift
-```
-
----
-
-## GATE 3: CREATE_SNAPSHOT_TEST_FILE
-
-### 3.0 Contrasting Background
-
-**ALWAYS** wrap the SUT in `Color.Background.backgroundGrey`. This is the app's standard page background, so snapshots show how the component looks in-app and make edges visible.
-
-```swift
-private func makeSUT(...) -> some View {
-    ComponentName(...)
-        .padding(8)
-        .background(Color.Background.backgroundGrey)
-}
-```
-
-Without this, white components are invisible against the default white snapshot canvas.
-
-### 3.0.1 Remote Image Initialization (required if the component uses `RemoteImage` / Kingfisher)
-
-**CRITICAL  -  this gate is easy to miss and produces silent false positives.**
-
-If the component (or any nested component it composes) renders images via `CoreUI.RemoteImage` / Kingfisher / any async image loader, the snapshot test MUST include image-initialization scaffolding. Without it, the snapshot captures the KFImage **placeholder state**  -  the first and every subsequent run compare placeholder to placeholder, so the tests "pass" while the reference PNGs contain no real image pixels at all.
-
-**How to detect the need**: if `pass3/04b_component_architecture.md` / `pass3/04_patterns.md` / `pass3/06_assets.md` mentions `RemoteImage`, `Kingfisher`, `KFImage`, image URL, remote image, or the component consumes any protocol/config with an `imageURL: URL` field, you MUST apply this gate. Also check if any **nested** component uses remote images  -  the parent inherits the requirement transitively.
-
-**NEVER use `usleep` on the main thread in either the prefetch or the image wait.** Kingfisher dispatches its `retrieveImage` completion handlers and KFImage's view-delivery updates back to the **main queue**. `usleep` blocks the main runloop, so those callbacks never fire, the cache never warms, and the snapshot captures a placeholder. Use `RunLoop.main.run(until:)` to spin the runloop instead  -  that allows queued main-actor work to drain while you wait. See the sibling `Homepage3rdPartyCardSnapshotTests.swift` for the canonical 20 ms pattern, and `HomepageAdditionalServices3rdPartyGroupSnapshotTests.swift` for the composite-view 4 s pattern (same rule, longer deadline).
-
-**Required scaffolding** (both references together show the full pattern):
-
-1. **Module imports**  -  `@testable import CoreUI` + `import Kingfisher` in addition to the usual `SnapshotTesting` / `SwiftUI` / `XCTest`.
-2. **Deterministic seeded URLs**  -  file-scope `let`s like `URL(string: "https://picsum.photos/seed/{slug}/{W}/{H}")!`. Seeds return the same image bytes for identical URLs → stable snapshots. Do NOT use unseeded picsum, placehold.it, or any URL that returns different bytes per request.
-3. **`@MainActor private func prefetchVariantImages(timeout:)`**  -  kicks `KingfisherManager.shared.retrieveImage(with:)` for every URL and **spins `RunLoop.main.run(until:)`** until every completion callback has fired (not `usleep`, not `isCached` polling). Use a `@MainActor final class` counter (`MainActor.assumeIsolated { counter.remaining -= 1 }` inside the completion) to satisfy Swift 6 concurrency rules  -  a captured `var Int` inside the closure will not compile. 20 s timeout is safe; the runloop exits early once the counter hits zero.
-4. **`override class func setUp()`**  -  after `TestDependencies.registerAll()`, set `RemoteImageConfiguration.shared.fadeDuration = 0`. This disables KFImage's crossfade animation so cached pixels appear on the first layout pass instead of fading in mid-snapshot.
-5. **`override func setUp()`**  -  call `prefetchVariantImages()` before every test, so each test sees warm cache.
-6. **`waitForImages()` helper**  -  **`RunLoop.main.run(until: Date().addingTimeInterval({seconds}))`**, NOT `usleep`. Call it in every assert helper AFTER `vc.view.layoutIfNeeded()` and BEFORE `SnapshotTesting.assertSnapshot(...)`. Duration depends on how many `RemoteImage` instances the view composes **simultaneously**:
-
-   | Simultaneous async-image views | `waitForImages` duration | Canonical reference |
-   |---|---|---|
-   | 1 (single card, single banner, etc.) | 20 ms (`usleep(20_000)` is OK for single-view, but `RunLoop.main.run` is still safer) | `Homepage3rdPartyCardSnapshotTests.swift` |
-   | 2-4 (group / row / carousel composing multiple cards) | 2-4 s via `RunLoop.main.run(until:)` | `HomepageAdditionalServices3rdPartyGroupSnapshotTests.swift` |
-   | 5+ (lists, grids, large composites) | 4-6 s via `RunLoop.main.run(until:)`; consider also capping list length to 3-5 in `makeSUT` |
-
-7. **Frame width sanity**  -  if the SUT renders a section title or horizontal carousel, make sure the snapshot frame width is wide enough to include the title and at least one full card. Clipped titles are a visible smoke signal that the frame is too narrow.
-
-**Skeleton** (adapt to single-view OR composite-view shape per the table above):
-
-```swift
-@testable import CoreUI
-import Kingfisher
-import SnapshotTesting
-import SwiftUI
-import XCTest
-@testable import {sourceModule}
-
-private let imageURL1 = URL(string: "https://picsum.photos/seed/{slug1}/{W}/{H}")!
-private let imageURL2 = URL(string: "https://picsum.photos/seed/{slug2}/{W}/{H}")!
-private let imageURL3 = URL(string: "https://picsum.photos/seed/{slug3}/{W}/{H}")!
-
-@MainActor
-private final class PrefetchCounter {
-    var remaining: Int
-    init(_ n: Int) { self.remaining = n }
-}
-
-/// Warms Kingfisher's memory cache for all variant URLs and spins the main
-/// runloop until every completion callback fires (or the deadline expires).
-/// Spinning the runloop is required  -  usleep on main would starve the
-/// Kingfisher callbacks and the cache would never warm.
-@MainActor
-private func prefetchVariantImages(timeout: TimeInterval = 20.0) {
-    let urls = [imageURL1, imageURL2, imageURL3]
-    let counter = PrefetchCounter(urls.count)
-    for url in urls {
-        KingfisherManager.shared.retrieveImage(with: url) { _ in
-            MainActor.assumeIsolated { counter.remaining -= 1 }
-        }
-    }
-    let deadline = Date().addingTimeInterval(timeout)
-    while counter.remaining > 0 && Date() < deadline {
-        RunLoop.main.run(until: Date().addingTimeInterval(0.05))
-    }
-}
-
-@MainActor
-final class {ComponentName}SnapshotTests: XCTestCase {
-
-    override class func setUp() {
-        super.setUp()
-        TestDependencies.registerAll()
-        RemoteImageConfiguration.shared.fadeDuration = 0   // required
-    }
-
-    override func setUp() {
-        super.setUp()
-        prefetchVariantImages()                             // required
-    }
-
-    /// required  -  uses RunLoop.main.run(until:), never usleep.
-    /// Duration scales with # of simultaneous RemoteImage views (see table
-    /// in phase-5b section 3.0.1). 20 ms is enough for a single-card SUT;
-    /// 2-4 s is required for composite views that render multiple cards
-    /// at once.
-    private func waitForImages() {
-        RunLoop.main.run(until: Date().addingTimeInterval(/* single: 0.02 | composite: 4.0 */))
-    }
-
-    private func assertSnapshot(_ view: some View, named: String, width: CGFloat, height: CGFloat, ...) {
-        let vc = UIHostingController(rootView: view)
-        vc.view.frame = CGRect(x: 0, y: 0, width: width, height: height)
-        vc.view.layoutIfNeeded()
-        waitForImages()                                     // required
-        SnapshotTesting.assertSnapshot(of: vc, as: .image(...), ...)
-    }
-}
-```
-
-**Verification checklist before committing reference PNGs:**
-
-1. Delete any pre-existing PNGs under `__Snapshots__/{ComponentName}SnapshotTests/`.
-2. Run the suite once. Expect failures on first run (`.missing` mode auto-records).
-3. Open at least one recorded PNG visually and confirm every card/image slot shows **real photographic content**, not a Kingfisher placeholder (light gradient + activity spinner) and not an all-blank background.
-4. Check file sizes: real photographic snapshots are typically 100 KB - 2 MB. A composite PNG at <50 KB is a strong signal of placeholder capture.
-5. Run the suite a second time  -  it MUST pass on the regression run. If not, increase `waitForImages` duration.
-6. Only commit PNGs (if tracked) and the test file together, never separately.
-
-**Root-cause note (why this gate exists):** the template in section 3.1 below references `ExploreCityDetailAboutCitySnapshotTests.swift`, which does NOT use remote images. A subagent that copies only the section 3.1 template will silently omit the scaffolding above and produce tests that lock in placeholder reference PNGs. This has happened in real runs:
-
-- `HomepageAdditionalServices3rdPartyGroupSnapshotTests` ({jira.projectKey}-132403): first fix copied the sibling's `usleep(20_000)` wait verbatim  -  the composite renders **three** `Homepage3rdPartyCard` instances simultaneously, and 20 ms wasn't enough for all three to drain. Second fix replaced both the prefetch poll AND the image wait with `RunLoop.main.run(until:)` and extended the wait to 4 s. Reference PNGs went from 65 KB (placeholder) to 750 KB - 1.76 MB (real photos).
-
-**If the component renders a single `RemoteImage`, the canonical reference is `Homepage3rdPartyCardSnapshotTests.swift`. If the component composes multiple `RemoteImage` instances simultaneously, the canonical reference is `HomepageAdditionalServices3rdPartyGroupSnapshotTests.swift`.** Neither the Explore reference nor the generic section 3.1 template is appropriate for remote-image components.
-
-### 3.1 Template
-
-Pick the canonical reference based on what the component renders:
-
-| Component shape | Canonical reference | section 3.0.1 scaffolding |
-|---|---|---|
-| Pure SwiftUI, no remote images | `ExploreCityDetailAboutCitySnapshotTests.swift` | Not required |
-| Single `RemoteImage` / Kingfisher instance | `Homepage3rdPartyCardSnapshotTests.swift` | **Required** (single-view variant) |
-| Composite view with 2+ `RemoteImage` instances rendered simultaneously | `HomepageAdditionalServices3rdPartyGroupSnapshotTests.swift` | **Required** (composite variant, 2-4 s `RunLoop.main.run` wait) |
-
-Then follow the established project pattern from the chosen reference:
-
-```swift
-//
-//  {componentName}SnapshotTests.swift
-//  {sourceModule}Tests
-//
-//  Created by {AUTHOR} on {DD.MM.YYYY}.
-//
-
-import SnapshotTesting
-import SwiftUI
-import XCTest
-@testable import {sourceModule}
-
-@MainActor
-final class {componentName}SnapshotTests: XCTestCase {
-
-    override class func setUp() {
-        super.setUp()
-        TestDependencies.registerAll()
-    }
-
-    override func invokeTest() {
-        withSnapshotTesting(record: .missing) {
-            super.invokeTest()
-        }
-    }
-
-    // MARK: - Light Mode Snapshots
-
-    // {generated variant tests}
-
-    // MARK: - Dark Mode Snapshots
-
-    // {generated dark mode tests}
-
-    // MARK: - Snapshot Helpers
-
-    private func assertSnapshot(
-        _ view: some View,
-        named name: String,
-        width: CGFloat = {componentWidth},
-        height: CGFloat = {componentHeight},
-        filePath: StaticString = #filePath,
-        testName: String = #function,
-        line: UInt = #line
-    ) {
-        let vc = UIHostingController(rootView: view)
-        vc.view.frame = CGRect(x: 0, y: 0, width: width, height: height)
-        vc.view.layoutIfNeeded()
-
-        SnapshotTesting.assertSnapshot(
-            of: vc,
-            as: .image(precision: 0.99, perceptualPrecision: 0.98),
-            named: name,
-            file: filePath,
-            testName: testName,
-            line: line
-        )
-    }
-
-    private func assertSnapshotDarkMode(
-        _ view: some View,
-        named name: String,
-        width: CGFloat = {componentWidth},
-        height: CGFloat = {componentHeight},
-        filePath: StaticString = #filePath,
-        testName: String = #function,
-        line: UInt = #line
-    ) {
-        let vc = UIHostingController(rootView: view)
-        vc.view.frame = CGRect(x: 0, y: 0, width: width, height: height)
-        vc.overrideUserInterfaceStyle = .dark
-        vc.view.layoutIfNeeded()
-
-        SnapshotTesting.assertSnapshot(
-            of: vc,
-            as: .image(precision: 0.99, perceptualPrecision: 0.98),
-            named: name,
-            file: filePath,
-            testName: testName,
-            line: line
-        )
-    }
-
-    // MARK: - Helpers
-
-    private func makeSUT(/* variant params */) -> {componentName} {
-        {componentName} { config in
-            config
-                .{property1}({value1})
-                .{property2}({value2})
-        }
-    }
-}
-```
-
----
-
-## GATE 4: GENERATE_ENUM_VARIANT_TESTS
-
-For each CaseIterable enum property, generate one test per case:
-
-### 4.1 Individual Case Tests (Light Mode)
-
-```swift
-// MARK: - {EnumName} Variants (Light)
-
-func test_snapshot_light_{caseName}() {
-    let sut = {componentName} { config in
-        config
-            .text("{sampleText}")
-            .{enumProperty}(.{caseName})
-    }
-    assertSnapshot(sut, named: "light_{caseName}")
-}
-```
-
-### 4.2 Individual Case Tests (Dark Mode)
-
-```swift
-// MARK: - {EnumName} Variants (Dark)
-
-func test_snapshot_dark_{caseName}() {
-    let sut = {componentName} { config in
-        config
-            .text("{sampleText}")
-            .{enumProperty}(.{caseName})
-    }
-    assertSnapshotDarkMode(sut, named: "dark_{caseName}")
-}
-```
-
----
-
-## GATE 5: GENERATE_OPTIONAL_VARIANT_TESTS
-
-For optional properties (Image?, String?) that change visual output:
-
-```swift
-// MARK: - Optional Variants
-
-func test_snapshot_light_withIcon() {
-    let sut = {componentName} { config in
-        config
-            .text("{sampleText}")
-            .state(.{defaultState})
-            .leftIcon(Image(systemName: "{iconName}"))
-    }
-    assertSnapshot(sut, named: "light_withIcon")
-}
-
-func test_snapshot_light_iconOnly() {
-    let sut = {componentName} { config in
-        config
-            .state(.{defaultState})
-            .leftIcon(Image(systemName: "{iconName}"))
-        // text omitted = nil = icon-only mode
-    }
-    assertSnapshot(sut, named: "light_iconOnly")
-}
-
-func test_snapshot_dark_withIcon() {
-    // Same as above with assertSnapshotDarkMode
-}
-```
-
----
-
-## GATE 5B: GENERATE_RTL_VARIANT_TESTS
-
-RTL (Right-to-Left) tests verify layout mirroring with Arabic localization.
-
-**CRITICAL:** RTL tests MUST use `TestDependencies.setLanguage("ar")` to override the app language so localized labels render in Arabic. Reset after each test with `TestDependencies.resetLanguage()`.
-
-### 5B.1 RTL State Tests (Light + Dark)
-
-Test a representative subset of enum states (3 is sufficient: first, middle, last or success/warning/error):
-
-```swift
-// MARK: - RTL Variants (Light)
-
-func test_snapshot_rtl_light_{caseName}() {
-    TestDependencies.setLanguage("ar")
-    let sut = makeSUT({enumProperty}: .{caseName})
-    assertSnapshotRTL(sut, named: "rtl_light_{caseName}")
-    TestDependencies.resetLanguage()
-}
-
-// MARK: - RTL Variants (Dark)
-
-func test_snapshot_rtl_dark_{caseName}() {
-    TestDependencies.setLanguage("ar")
-    let sut = makeSUT({enumProperty}: .{caseName})
-    assertSnapshotRTLDarkMode(sut, named: "rtl_dark_{caseName}")
-    TestDependencies.resetLanguage()
-}
-```
-
-### 5B.2 RTL Optional Variants
-
-Test icon + text and icon-only in RTL to verify icon position mirroring:
-
-```swift
-func test_snapshot_rtl_light_withIcon() {
-    let sut = {componentName} { config in
-        config
-            .text("{arabicText}")
-            .state(.{defaultState})
-            .leftIcon(Image(systemName: "{iconName}"))
-    }
-    assertSnapshotRTL(sut, named: "rtl_light_withIcon")
-}
-
-func test_snapshot_rtl_light_iconOnly() {
-    let sut = {componentName} { config in
-        config
-            .state(.{defaultState})
-            .leftIcon(Image(systemName: "{iconName}"))
-    }
-    assertSnapshotRTL(sut, named: "rtl_light_iconOnly")
-}
-// + dark variants with assertSnapshotRTLDarkMode
-```
-
-### 5B.3 RTL Snapshot Helpers
-
-Add these helpers alongside the existing assertSnapshot/assertSnapshotDarkMode:
-
-```swift
-private func assertSnapshotRTL(
-    _ view: some View,
-    named name: String,
-    width: CGFloat = {componentWidth},
-    height: CGFloat = {componentHeight},
-    filePath: StaticString = #filePath,
-    testName: String = #function,
-    line: UInt = #line
-) {
-    let rtlView = view.environment(\.layoutDirection, .rightToLeft)
-    let vc = UIHostingController(rootView: rtlView)
-    vc.view.frame = CGRect(x: 0, y: 0, width: width, height: height)
-    vc.view.semanticContentAttribute = .forceRightToLeft
-    vc.view.layoutIfNeeded()
-
-    SnapshotTesting.assertSnapshot(
-        of: vc,
-        as: .image(precision: 0.99, perceptualPrecision: 0.98),
-        named: name,
-        file: filePath,
-        testName: testName,
-        line: line
-    )
-}
-
-private func assertSnapshotRTLDarkMode(
-    _ view: some View,
-    named name: String,
-    width: CGFloat = {componentWidth},
-    height: CGFloat = {componentHeight},
-    filePath: StaticString = #filePath,
-    testName: String = #function,
-    line: UInt = #line
-) {
-    let rtlView = view.environment(\.layoutDirection, .rightToLeft)
-    let vc = UIHostingController(rootView: rtlView)
-    vc.view.frame = CGRect(x: 0, y: 0, width: width, height: height)
-    vc.view.semanticContentAttribute = .forceRightToLeft
-    vc.overrideUserInterfaceStyle = .dark
-    vc.view.layoutIfNeeded()
-
-    SnapshotTesting.assertSnapshot(
-        of: vc,
-        as: .image(precision: 0.99, perceptualPrecision: 0.98),
-        named: name,
-        file: filePath,
-        testName: testName,
-        line: line
-    )
-}
-```
-
-### 5B.4 Locale-Specific Variants (TR, EN)
-
-For components with localized static text, snapshot in Turkish and English to verify translations render correctly. Default (no setLanguage) uses the system language which may not match either.
-
-```swift
-// MARK: - Turkish Variants (Light)
-
-func test_snapshot_tr_light_{caseName}() {
-    TestDependencies.setLanguage("tr")
-    let sut = makeSUT({enumProperty}: .{caseName})
-    assertSnapshot(sut, named: "tr_light_{caseName}")
-    TestDependencies.resetLanguage()
-}
-
-// MARK: - Turkish Variants (Dark)
-
-func test_snapshot_tr_dark_{caseName}() {
-    TestDependencies.setLanguage("tr")
-    let sut = makeSUT({enumProperty}: .{caseName})
-    assertSnapshotDarkMode(sut, named: "tr_dark_{caseName}")
-    TestDependencies.resetLanguage()
-}
-
-// MARK: - English Variants (Light)
-
-func test_snapshot_en_light_{caseName}() {
-    TestDependencies.setLanguage("en")
-    let sut = makeSUT({enumProperty}: .{caseName})
-    assertSnapshot(sut, named: "en_light_{caseName}")
-    TestDependencies.resetLanguage()
-}
-
-// MARK: - English Variants (Dark)
-
-func test_snapshot_en_dark_{caseName}() {
-    TestDependencies.setLanguage("en")
-    let sut = makeSUT({enumProperty}: .{caseName})
-    assertSnapshotDarkMode(sut, named: "en_dark_{caseName}")
-    TestDependencies.resetLanguage()
-}
-```
-
-**When to include locale variants:** Always include TR + EN + AR (RTL) for components with static localized text. For components with only dynamic text (passed as parameters), locale variants are optional since the text comes from the caller.
-
-### 5B.5 Arabic Sample Text
-
-| English | Arabic |
-|---------|--------|
-| Success | نجاح |
-| Warning | تحذير |
-| Error | خطأ |
-| Standard | قياسي |
-| Secondary | ثانوي |
-| Lorem | نص |
-
----
-
-## GATE 6: RUN_AND_RECORD
-
-### 6.1 First Run  -  Record Reference Snapshots
-
-**IMPORTANT:** Use `xcodebuild`, NOT `swift test`. The project uses Xcode-specific features (`ColorResource`, `ImageResource`, asset catalogs) that are unavailable in SPM's `swift build`/`swift test`.
-
-```bash
-cd {repos.components.path} && \
-xcodebuild test \
-  -scheme UIComponents-Package \
-  -destination 'platform=iOS Simulator,name=iPhone 17 Pro' \
-  -only-testing:{sourceModule}Tests/{componentName}SnapshotTests
-```
-
-Snapshots auto-recorded to:
-```
-Tests/{sourceModule}Tests/__Snapshots__/{componentName}SnapshotTests/
-├── test_snapshot_light_{case1}.light_{case1}.png
-├── test_snapshot_dark_{case1}.dark_{case1}.png
-├── ...
-```
-
-### 6.2 Verify Snapshot Count
-
-| Expected | Actual | Status |
-|----------|--------|--------|
-| {EXPECTED_COUNT} total | {ACTUAL_COUNT} recorded | pass/fail |
-
-### 6.3 Second Run  -  Verify Regression
-
-```bash
-cd {repos.components.path} && \
-xcodebuild test \
-  -scheme UIComponents-Package \
-  -destination 'platform=iOS Simulator,name=iPhone 17 Pro' \
-  -only-testing:{sourceModule}Tests/{componentName}SnapshotTests
-```
-
-All tests must pass (snapshots match).
-
-| Result | Action |
-|--------|--------|
-| All pass | Proceed to OUTPUT |
-| Snapshot differs | Review diff images, fix if unintentional |
-| Missing snapshot | Run with `record: .missing` |
-
-FAIL →
-```
-STATUS: HALT
-PHASE: phase-5b
-GATE: RUN_AND_RECORD
-REASON: Snapshot tests failed.
-FAILED_SNAPSHOTS: {list}
-OPTIONS:
-1) Fix visual regression in component
-2) Update snapshots: withSnapshotTesting(record: .all)
-3) Review component against Figma design
-```
-
----
-
-## OUTPUT
-
-```
-STATUS: COMPLETE
-PHASE: phase-5b
-GATES_PASSED: [PRE_CHECK, DETERMINE_VARIANT_MATRIX, DETERMINE_TEST_LOCATION, CREATE_SNAPSHOT_TEST_FILE, GENERATE_ENUM_VARIANTS, GENERATE_OPTIONAL_VARIANTS, GENERATE_RTL_VARIANTS, RUN_AND_RECORD]
-ARTIFACTS_CREATED:
-  - Tests/{sourceModule}Tests/Snapshot/{componentPath}/{componentName}SnapshotTests.swift
-  - Tests/{sourceModule}Tests/__Snapshots__/{componentName}SnapshotTests/*.png
-SUMMARY: {COUNT} snapshot tests  -  {ENUM_COUNT} enum variants × 2 themes + {OPTIONAL_COUNT} optional variants × 2 themes + {RTL_COUNT} RTL variants × 2 themes + {LOCALE_COUNT} locale variants (TR/EN) × 2 themes = {TOTAL} snapshots.
-```