Vizzly Ruby Client

A lightweight Ruby client SDK for capturing screenshots and sending them to Vizzly for visual regression testing.

Installation

Add this line to your application's Gemfile:

gem 'vizzly'

And then execute:

bundle install

Or install it yourself as:

gem install vizzly

Usage

Basic Usage

require 'vizzly'

# Take a screenshot
image_data = File.binread('screenshot.png')
Vizzly.screenshot('homepage', image_data)

With Options

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

Ruby option names use snake_case. The client also accepts camelCase aliases for parity with the JavaScript API: minClusterSize, fullPage, buildId, and requestTimeout. request_timeout is measured in milliseconds, so 60_000 means one minute.

Using a Client Instance

client = Vizzly::Client.new
client.screenshot('login-form', image_data)

# Override local TDD visual diff behavior for this client
strict_client = Vizzly::Client.new(fail_on_diff: true)

# Attach screenshots to a known build and tune request timeout in milliseconds
client.screenshot(
  'checkout',
  image_data,
  build_id: 'build_123',
  request_timeout: 60_000
)

# Check if client is ready
puts "Ready: #{client.ready?}"

# Get client info, including the effective fail_on_diff setting
puts client.info

Integration with Test Frameworks

RSpec + Capybara

RSpec.describe 'Homepage', type: :feature do
  it 'displays the homepage correctly' do
    visit '/'
    expect(page).to have_content('Welcome')

    # Take a screenshot for visual regression testing
    image_data = page.driver.browser.screenshot_as(:png)
    Vizzly.screenshot('homepage', image_data)
  end

  it 'displays the checkout page' do
    visit '/checkout'
    fill_in 'Email', with: 'test@example.com'

    # Take a screenshot with properties
    image_data = page.driver.browser.screenshot_as(:png)
    Vizzly.screenshot('checkout-form', image_data,
      properties: {
        browser: 'chrome',
        viewport: { width: 1920, height: 1080 }
      }
    )
  end
end

Configuration

The client automatically discovers a running Vizzly TDD server by looking for .vizzly/server.json in the current and parent directories.

You can also configure via environment variables:

• VIZZLY_SERVER_URL - Server URL (e.g., http://localhost:47392)
• VIZZLY_BUILD_ID - Build identifier for grouping screenshots
• VIZZLY_FAIL_ON_DIFF - Set to true or 1 to raise when a local TDD comparison returns a visual diff

Development

After checking out the repo, run tests:

ruby test/vizzly_test.rb

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/vizzly-testing/cli.

License

The gem is available as open source under the terms of the MIT License.