@mmerterden/multi-agent-pipeline 8.6.0

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

@@ -0,0 +1,636 @@
+# 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 § 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 § 3.1 below references `ExploreCityDetailAboutCitySnapshotTests.swift`, which does NOT use remote images. A subagent that copies only the § 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 § 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 | § 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.
+```