Skip to content
Latest

Ruby SDK overview

Use the Ruby client to send screenshots from RSpec, Minitest, or another Ruby test runner to the local Vizzly server.

Install

Install the CLI:

Terminal window
npm install -D @vizzly-testing/cli

Then install the gem:

gem 'vizzly'

Basic usage

require 'vizzly'
image_data = page.driver.browser.screenshot_as(:png)
Vizzly.screenshot('homepage', image_data)

The main module methods are:

  • Vizzly.screenshot
  • Vizzly.ready?
  • Vizzly.client.info

Options

Vizzly.screenshot('checkout', image_data,
properties: {
browser: 'chrome',
viewport: { width: 1920, height: 1080 }
},
threshold: 5,
min_cluster_size: 2,
full_page: true,
request_timeout: 60_000
)

Use properties for variant metadata. Add matching keys to local signatureProperties or your cloud project’s matching settings to keep separate baselines.

Pass comparison and request options at the top level, as shown above. Values inside properties stay metadata.

The Ruby client accepts both snake_case and JavaScript-style aliases for SDK options. request_timeout is measured in milliseconds.

Vizzly.client.info includes the effective build_id/buildId and fail_on_diff/failOnDiff values.

How discovery works

The gem looks for the server in this order:

  1. VIZZLY_SERVER_URL
  2. .vizzly/server.json in the current directory or a parent directory

You can also set VIZZLY_BUILD_ID to group screenshots and VIZZLY_FAIL_ON_DIFF=true or 1 to make local TDD diffs raise. .vizzly/server.json may also provide buildId and failOnDiff.

Run it

Local review:

Terminal window
npx vizzly tdd start
bundle exec rspec

Cloud build:

Terminal window
npx vizzly run "bundle exec rspec"

Failure behavior

If the client cannot reach the local Vizzly server, it warns once, disables itself for the rest of the run, and returns nil instead of crashing your tests.

Next steps