snapshot

# Snapshot-Driven UI Iteration Use swift-snapshot-testing to create a visual feedback loop when implementing UI changes. Render SwiftUI views to PNG after each code change, compare against design goals, fix mismatches, and repeat. ## When to Use - Implementing UI from Figma designs or reference screenshots - Multi-step view redesigns where each step should match a target - Any SwiftUI work where you need to visually verify output - When design reference images are available for comparison ## When NOT to Use - Simple single-property changes (color, font) - Logic-only changes with no visual impact - When the project already has snapshot tests covering the view ## Core Flow ``` 1. SETUP Add swift-snapshot-testing dependency (temporary) 2. GOAL Collect design reference images 3. SCAFFOLD Create snapshot test rendering the target view 4. LOOP For each implementation step: a. Edit code b. Run snapshot test (record mode) c. Read generated PNG d. Compare against design e. If mismatch -> fix and re-snapshot f. If match -> commit the verified change, move to next step 5. CLEANUP Revert dependency + delete test file ``` ## Setup: Add Dependency Check if `swift-snapshot-testing` already exists in `Modules/Package.swift`. If not, add it temporarily. **In the `dependencies` array of `Modules/Package.swift`:** ```swift .package(url: "https://github.com/pointfreeco/swift-snapshot-testing", from: "1.17.0"), ``` **In the relevant test target's `dependencies` array:** ```swift .product(name: "SnapshotTesting", package: "swift-snapshot-testing"), ``` Common test targets in this project: - `PointOfSaleTests` — for POS views - `WooFoundationTests` — for shared UI components - `YosemiteTests` — for business logic views **Remember the original state** of `Modules/Package.swift` so you can revert exactly after cleanup. ## Goal: Collect References If the user provides design reference images (Figma exports, screenshots): ```bash mkdir -p ~/Downloads/snapshot_experiment cp ~/path/to/design.png ~/Downloads/snapshot_experiment/design.png ``` Read each reference image to understand the target state before writing code. If no reference image, the goal is inferred from the user's description of desired UI behavior. ## Scaffold: Create Snapshot Test Create a test file in the appropriate `Modules/Tests/*Tests/` directory: ```swift import XCTest import SnapshotTesting import SwiftUI @testable import TargetModule final class ViewNameSnapshotTests: XCTestCase { override func invokeTest() { withSnapshotTesting(record: .all) { super.invokeTest() } } func test_defaultState_snapshot() { let view = YourView(/* props for default state */) .frame(width: 375, height: 900) assertSnapshot(of: view, as: .image(layout: .sizeThatFits)) } func test_alternateState_snapshot() { let view = YourView(/* props for alternate state */) .frame(width: 375, height: 900) assertSnapshot(of: view, as: .image(layout: .sizeThatFits)) } } ``` **Important details for this project:** - `record: .all` in `invokeTest()` forces PNG generation every run - For POS views, set `.environment(\.horizontalSizeClass, .regular)` — POS is iPad-first - Use `.frame(width:height:)` to control render size. Start with `height: 900`, increase to `1200+` if content is clipped - Tests will always "fail" in record mode — this is expected, they report recording, not comparison - Use POS design tokens (`POSPadding`, `POSSpacing`, `POSFontStyle`, `Color+POSColorPalette`) when comparing POS designs ## Run: Execute Snapshot Tests Use the `/simulator` skill approach to discover a booted simulator UDID. Run only the snapshot tests for fast feedback: ```bash xcodebuild test \ -workspace WooCommerce.xcworkspace \ -scheme WooCommerce \ -destination 'platform=iOS Simulator,id=<SIMULATOR_UDID>' \ -only-testing:<TestTarget>/<SnapshotTestClass> \ CODE_SIGNING_ALLOWED=NO 2>&1 | tail -30 ``` **Prefer module-level test targets** over the full app for faster feedback (~25s vs minutes). **Generated PNGs appear at:** ``` Modules/Tests/<TestTarget>/__Snapshots__/<TestClass>/test_name.1.png ``` ## Compare: Read and Assess After each run: 1. Read the generated PNG using the Read tool 2. If a design reference exists, read it side by side 3. Identify specific mismatches: layout, spacing, missing elements, text wrapping, colors 4. Copy PNGs to working directory with step labels for history: ```bash cp Modules/Tests/<Target>/__Snapshots__/<Class>/test_name.1.png ~/Downloads/snapshot_experiment/step1.png ``` ## Fix: Iterate on Mismatches Common issues caught by snapshots: - **Text wrapping** in pills/badges at narrow widths — add `.lineLimit(1).fixedSize(horizontal: true, vertical: false)`, reduce padding - **Back button showing** in non-compact context — set `.environment(\.horizontalSizeClass, .regular)` - **Content clipped** at bottom — increase frame height in test - **Spacing mismatches** — check `POSPadding`/`POSSpacing` values against design - **Wrong section order** — compare VStack children order with design When fixing: edit the code and re-run snapshots to verify. Only commit once the snapshot matches the design goal — don't commit untested changes. ## Cleanup: Remove ALL Temporary Artifacts After implementation is complete, revert ALL temporary changes: ```bash # Revert Package.swift (removes snapshot dependency) git checkout -- Modules/Package.swift # Revert Package.resolved if it changed git checkout -- Modules/Package.resolved # Also revert workspace Package.resolved if changed git checkout -- WooCommerce.xcworkspace/xcshareddata/swiftpm/Package.resolved # Delete the snapshot test file rm Modules/Tests/<TestTarget>/<SnapshotTestClass>.swift # Delete generated snapshot directory rm -rf Modules/Tests/<TestTarget>/__Snapshots__ # Verify clean state git status ``` **Critical**: Never commit snapshot test files, `__Snapshots__/` directories, or the `swift-snapshot-testing` dependency. These are temporary iteration tools only. ## Quick Reference | Action | Command/Tool | |--------|-------------| | Add dependency | Edit `Modules/Package.swift` | | Run snapshots | `xcodebuild test -only-testing:<Target>/<Class>` | | Find PNGs | `Modules/Tests/<Target>/__Snapshots__/<Class>/test_name.1.png` | | View snapshot | Read tool on the PNG path | | Compare | Read both snapshot PNG and design reference | | Fix + re-run | Edit code, re-run xcodebuild, commit once verified | | Clean up | `git checkout -- Modules/Package.swift`, `rm` test file + snapshots |