✨ Align Ruby and Swift SDKs

[Robdel12]

Why

This PR aligns the Ruby and Swift SDKs with the contract established by the core, web, Vitest, and Ember slices.

These SDKs are especially important because users do not see the main JavaScript implementation details. They just call Vizzly.screenshot(...), client.screenshot(...), or app.vizzlyScreenshot(...) and expect the same build grouping, metadata, request timeout, comparison, and diff-failure behavior they get elsewhere.

Before this pass, Ruby and Swift were close but not fully aligned. Build IDs and request timeouts could be treated like metadata. failOnDiff was not consistently available. Swift XCTest helpers duplicated metadata construction across overloads. Ruby accepted flexible option shapes, but the behavior was not crisp enough about what was a real SDK option versus user metadata.

The goal is parity without overbuilding: one conceptual contract, expressed idiomatically in Ruby and Swift.

What changed

Ruby SDK

• Adds fail_on_diff: and honors VIZZLY_FAIL_ON_DIFF plus discovered .vizzly/server.json settings.
• Honors VIZZLY_ENABLED=false and reports disabled/ready state consistently.
• Accepts snake_case options and JS-style camelCase aliases where useful: min_cluster_size/minClusterSize, full_page/fullPage, build_id/buildId, and request_timeout/requestTimeout.
• Sends buildId as a request field, not screenshot metadata.
• Applies request_timeout to the HTTP read timeout in milliseconds.
• Treats properties as the user metadata bag.
• Strips reserved/config options from properties, promotes them to the correct behavior when no top-level value exists, and emits a warning.
• Raises on both current 200-style and older 422-style TDD diff responses when fail-on-diff is enabled.
• Exposes both snake_case and camelCase info fields where that helps Ruby users and cross-SDK tooling.

Swift SDK

• Adds optional failOnDiff override and honors VIZZLY_FAIL_ON_DIFF plus discovered server config.
• Adds optional fullPage, buildId, and requestTimeout.
• Converts millisecond request timeout into URLRequest.timeoutInterval.
• Sends buildId outside properties.
• Preserves fullPage: false as an intentional value.
• Includes a stable properties object in payloads.
• Handles both current and legacy TDD diff response shapes.

Swift XCTest helpers

• Centralizes XCTest metadata construction in VizzlyXCTestMetadata.
• Adds app/test/element metadata through one merge path.
• Includes platform/device/OS/viewport metadata for app screenshots.
• Includes platform metadata and element type for element screenshots.
• Keeps user-provided properties as the intentional override layer.
• Forwards buildId and requestTimeout through helper overloads.

Docs and package surface

• Ruby README examples now show the screenshot-level options where they are actually accepted.
• Swift README and integration docs describe the current API signatures and current vizzly run "..." command style.
• Swift package metadata now covers both the client and XCTest helper tests.

Testing

• Ruby tests cover disabled state, info shape, env/server-config fail-on-diff, current and legacy diff responses, fractional thresholds, nested viewport metadata, aliases, zero values, build ID routing, timeout conversion, and reserved properties warnings.
• Swift tests cover info/fail state, payload shape, explicit false full-page behavior, build ID routing, nested viewport metadata, default comparison behavior, and XCTest metadata merging.

The Ruby follow-up for the properties contract was re-run after the stack split. The broader real visual-diff E2E matrix is still intentionally left for a focused follow-up so this already-large SDK slice stays reviewable.

Verification

• Ruby preservation-branch verification: 20 tests / 55 assertions.
• Ruby post-split verification after properties warning work: bundle exec rake test in clients/ruby: 21 runs, 64 assertions, 0 failures.
• Swift preservation-branch verification: swift test --filter VizzlyClientTests: 17 passed.
• Covered by the full preservation branch verification before the stack was split.
• Stack cleanup verification: git diff --check and PR file-list checks for ✨ Align core SDK option contracts #283 through 📝 Document aligned SDK workflows #287.

[vizzly-testing]

Vizzly - Visual Test Results

CLI Reporter - Waiting for build

No builds received yet for this pull request.

CLI TUI - Approved

5 comparisons, no changes detected.

View build

---

_{rd/sdk-ruby-swift · c6adb798}