Skip to content
Vizzly Docs

Ruby SDK Overview

The Ruby client is intentionally small. It finds a running Vizzly server, sends screenshots to /screenshot, and then gets out of the way.

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 module API is usually enough:

  • 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,
  build_id: 'build-123',
  request_timeout: 60_000
)

properties are part of the screenshot identity, so use them when you want separate baselines for variants.

Keep properties for user metadata only. Pass threshold, min_cluster_size, full_page, build_id, and request_timeout as top-level options, as shown above.

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
vizzly tdd start
bundle exec rspec

Cloud build:

Terminal window
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