vizzly 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0011bf796b1114bd00011a649d41cb860d4658cc4d98164f53d4e2308404d6c2
-  data.tar.gz: 14551857950efde73e174cb04d46be7192724262978f4a009f99bde06da9daea
+  metadata.gz: 00b928505560c41d2c1402ccb75ce47a3814cfaedf3d15094b5685d21a5ae2fb
+  data.tar.gz: dafb6128f52bc6e76b9cba415ef1e8823615758048d58613fb1688e337ab8c15
 SHA512:
-  metadata.gz: c66401d88b74442243b1f01c44a479d58844c0448c3b954bedcd823ea777a96408d87ce98e6b02b8a3812751a4381ff0073a448d469c2156a45169a17154d104
-  data.tar.gz: 3c30f1d6e5cd13ce62a2a779fce10410f8b0f525e29fa92ecfe10cf520c7ac4db33ff9defb241967ee21c0fff94a8293cae6aee009b274ba5dadfc1437baaa90
+  metadata.gz: 7f9afac44fa26d16dd705e82dbe6f38cc161004ebe97580f6c47d1d68f2f808a57f644008e718339f1695b9cc421206ca30ec58229ef7d8fb68d1b1bb1658d9f
+  data.tar.gz: d9af13050f7617fd2e0c94abc364a8b90ca890d92d3df7542fe18797dc4aea014a21dcb1d1e62f96e7ab8ac699441f5a8c8a84cfb5015f72c182749dd17800b0

data/README.md

@@ -43,20 +43,40 @@ Vizzly.screenshot('checkout-page', image_data,
     browser: 'chrome',
     viewport: { width: 1920, height: 1080 }
   },
-  threshold: 5
+  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
 
 ```ruby
 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
+# Get client info, including the effective fail_on_diff setting
 puts client.info
 ```
 
@@ -100,6 +120,8 @@ 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
 

data/lib/vizzly.rb

@@ -11,12 +11,15 @@ module Vizzly
   # Default port for local TDD server
   DEFAULT_TDD_PORT = 47392
 
+  # rubocop:disable Metrics/ClassLength
   class Client
     attr_reader :server_url, :disabled
 
-    def initialize(server_url: nil)
+    def initialize(server_url: nil, fail_on_diff: nil)
+      @server_info = nil
+      @configured_fail_on_diff = fail_on_diff
       @server_url = server_url || discover_server_url
-      @disabled = false
+      @disabled = ENV['VIZZLY_ENABLED'] == 'false'
       @warned = false
     end
 
@@ -26,8 +29,13 @@ module Vizzly
     # @param image_data [String] PNG image data as binary string
     # @param options [Hash] Optional configuration
     # @option options [Hash] :properties Additional properties to attach
-    # @option options [Integer] :threshold Pixel difference threshold (0-100)
+    # @option options [Numeric] :threshold Delta E comparison threshold. When
+    #   omitted, the server's configured threshold is used.
+    # @option options [Integer] :min_cluster_size Ignore connected diff
+    #   clusters smaller than this size. When omitted, the server config is used.
     # @option options [Boolean] :full_page Whether this is a full page screenshot
+    # @option options [String] :build_id Build ID for grouping screenshots
+    # @option options [Numeric] :request_timeout Request timeout in milliseconds
     #
     # @return [Hash, nil] Response data or nil if disabled/failed
     #
@@ -41,6 +49,7 @@ module Vizzly
     #     properties: { browser: 'chrome', viewport: { width: 1920, height: 1080 } },
     #     threshold: 5
     #   )
+    # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity
     def screenshot(name, image_data, options = {})
       return nil if disabled?
 
@@ -51,21 +60,34 @@ module Vizzly
       end
 
       image_base64 = Base64.strict_encode64(image_data)
+      options = normalize_options(options)
+      normalized = normalize_screenshot_options(options)
+
+      normalized[:warnings].each { |warning| warn warning[:message] }
+
+      request_timeout = normalized[:request_timeout]
+      request_timeout_seconds = request_timeout ? request_timeout.to_f / 1000.0 : 30
+      build_id = normalized[:build_id] || ENV.fetch('VIZZLY_BUILD_ID', nil)
 
       payload = {
         name: name,
         image: image_base64,
         type: 'base64',
-        buildId: ENV.fetch('VIZZLY_BUILD_ID', nil),
-        threshold: options[:threshold] || 0,
-        fullPage: options[:full_page] || false,
-        properties: options[:properties] || {}
+        buildId: build_id,
+        properties: normalized[:properties],
+        warnings: normalized[:warnings]
       }.compact
 
       uri = URI("#{@server_url}/screenshot")
 
       begin
-        response = Net::HTTP.start(uri.host, uri.port, read_timeout: 30) do |http|
+        response = Net::HTTP.start(
+          uri.host,
+          uri.port,
+          use_ssl: uri.scheme == 'https',
+          open_timeout: 10,
+          read_timeout: request_timeout_seconds
+        ) do |http|
           request = Net::HTTP::Post.new(uri)
           request['Content-Type'] = 'application/json'
           request.body = JSON.generate(payload)
@@ -84,6 +106,11 @@ module Vizzly
             comp = error_data['comparison']
             diff_percent = comp['diffPercentage']&.round(2) || 0.0
 
+            if fail_on_diff?
+              raise Error,
+                    "Visual diff detected for \"#{comp['name'] || name}\" (#{comp['diffPercentage'] || 0}% difference)"
+            end
+
             # Extract port from server_url
             port = begin
               @server_url.match(/:(\d+)/)[1]
@@ -106,7 +133,13 @@ module Vizzly
                 "Screenshot failed: #{response.code} #{response.message} - #{error_data['error'] || 'Unknown error'}"
         end
 
-        JSON.parse(response.body)
+        body = JSON.parse(response.body)
+        if body['tddMode'] && %w[diff failed].include?(body['status']) && fail_on_diff?
+          raise Error,
+                "Visual diff detected for \"#{body['name'] || name}\" (#{body['diffPercentage'] || 0}% difference)"
+        end
+
+        body
       rescue Error => e
         # Re-raise Vizzly errors (like visual diffs)
         raise if e.message.include?('Visual diff')
@@ -125,6 +158,18 @@ module Vizzly
         # Disable the SDK after first failure to prevent spam
         disable!('failure')
 
+        nil
+      rescue Net::OpenTimeout
+        warn "Vizzly connection timed out for #{name}: couldn't connect within 10s"
+        warn "Server URL: #{@server_url}/screenshot"
+        warn 'This usually means the server is unreachable (firewall, network issue, or wrong host)'
+        disable!('failure')
+        nil
+      rescue Net::ReadTimeout
+        warn "Vizzly request timed out for #{name}: no response within 30s"
+        warn "Server URL: #{@server_url}/screenshot"
+        warn 'The server may be overloaded or processing is taking too long'
+        disable!('failure')
         nil
       rescue StandardError => e
         warn "Vizzly screenshot failed for #{name}: #{e.message}"
@@ -132,6 +177,7 @@ module Vizzly
         nil
       end
     end
+    # rubocop:enable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity
 
     # Wait for all queued screenshots to be processed
     # (Simple client doesn't need explicit flushing)
@@ -172,14 +218,82 @@ module Vizzly
       {
         enabled: !disabled?,
         server_url: @server_url,
+        serverUrl: @server_url,
         ready: ready?,
         build_id: ENV.fetch('VIZZLY_BUILD_ID', nil),
-        disabled: disabled?
+        buildId: ENV.fetch('VIZZLY_BUILD_ID', nil),
+        disabled: disabled?,
+        fail_on_diff: fail_on_diff?,
+        failOnDiff: fail_on_diff?
       }
     end
 
     private
 
+    def normalize_options(options)
+      options.transform_keys { |key| key.is_a?(String) ? key.to_sym : key }
+    end
+
+    def option_value(options, *keys)
+      keys.each do |key|
+        return options[key] if options.key?(key)
+      end
+
+      nil
+    end
+
+    def normalize_screenshot_options(options)
+      threshold = options[:threshold]
+      min_cluster_size = option_value(options, :min_cluster_size, :minClusterSize)
+      full_page = options.key?(:full_page) ? options[:full_page] : options[:fullPage]
+      build_id = option_value(options, :build_id, :buildId)
+      request_timeout = option_value(options, :request_timeout, :requestTimeout)
+      properties = {}
+      warnings = []
+
+      (options[:properties] || {}).each do |key, value|
+        option = key.to_s
+        case option
+        when 'threshold'
+          threshold = value if threshold.nil?
+        when 'min_cluster_size', 'minClusterSize'
+          min_cluster_size = value if min_cluster_size.nil?
+        when 'full_page', 'fullPage'
+          full_page = value if full_page.nil?
+        when 'build_id', 'buildId'
+          build_id = value if build_id.nil?
+        when 'request_timeout', 'requestTimeout'
+          request_timeout = value if request_timeout.nil?
+        else
+          properties[key] = value
+          next
+        end
+
+        warnings << reserved_property_warning(option)
+      end
+
+      properties = properties.merge(
+        threshold: threshold,
+        minClusterSize: min_cluster_size,
+        fullPage: full_page
+      ).compact
+
+      {
+        build_id: build_id,
+        request_timeout: request_timeout,
+        properties: properties,
+        warnings: warnings
+      }
+    end
+
+    def reserved_property_warning(option)
+      {
+        code: 'reserved-property-option',
+        option: option,
+        message: "Move \"#{option}\" out of properties; properties is only for user metadata."
+      }
+    end
+
     def warn_once(message)
       return if @warned
 
@@ -196,6 +310,15 @@ module Vizzly
       auto_discover_tdd_server
     end
 
+    def fail_on_diff?
+      return @configured_fail_on_diff unless @configured_fail_on_diff.nil?
+
+      env_value = ENV.fetch('VIZZLY_FAIL_ON_DIFF', '').downcase
+      return true if %w[true 1].include?(env_value)
+
+      @server_info && @server_info['failOnDiff'] == true
+    end
+
     # Auto-discover local TDD server by checking for server.json
     def auto_discover_tdd_server
       dir = Dir.pwd
@@ -207,6 +330,7 @@ module Vizzly
         if File.exist?(server_json_path)
           begin
             server_info = JSON.parse(File.read(server_json_path))
+            @server_info = server_info
             port = server_info['port'] || DEFAULT_TDD_PORT
             return "http://localhost:#{port}"
           rescue JSON::ParserError, Errno::ENOENT
@@ -220,6 +344,7 @@ module Vizzly
       nil
     end
   end
+  # rubocop:enable Metrics/ClassLength
 
   class << self
     # Get or create the shared client instance

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: vizzly
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Vizzly
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-01-07 00:00:00.000000000 Z
+date: 2026-06-01 00:00:00.000000000 Z
 dependencies: []
 description: A lightweight client SDK for capturing screenshots and sending them to
   Vizzly for visual regression testing
@@ -44,7 +44,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.3.27
+rubygems_version: 3.5.22
 signing_key:
 specification_version: 4
 summary: Vizzly visual regression testing client for Ruby