eyes_core 6.6.1 → 6.9.6

data/README.md

@@ -0,0 +1,402 @@
+# Applitools Eyes Core SDK
+
+[![Gem Version](https://badge.fury.io/rb/eyes_core.svg)](https://badge.fury.io/rb/eyes_core)
+
+The `eyes_core` gem is the foundation of the Applitools Eyes Ruby SDK ecosystem. It provides the core functionality, base classes, and utilities that power all specialized Applitools SDKs for Ruby.
+
+## Table of Contents
+
+1. [Overview](#overview)
+2. [Installation](#installation)
+3. [Core Components](#core-components)
+   - [EyesBase](#eyesbase)
+   - [Configuration](#configuration)
+   - [Viewport Size](#viewport-size)
+   - [Batch Info](#batch-info)
+   - [Region](#region)
+   - [Match Settings](#match-settings)
+4. [Universal SDK Integration](#universal-sdk-integration)
+5. [Error Handling](#error-handling)
+6. [Advanced Features](#advanced-features)
+   - [Accessibility Testing](#accessibility-testing)
+   - [Layout Breakpoints](#layout-breakpoints)
+   - [Proxy Configuration](#proxy-configuration)
+7. [Best Practices](#best-practices)
+8. [Troubleshooting](#troubleshooting)
+9. [FAQ](#faq)
+
+## Overview
+
+The `eyes_core` gem serves as the foundation for all Applitools Ruby SDKs. While not intended for direct use, it provides essential functionality that enables visual testing across different platforms and frameworks.
+
+### Core Capabilities
+
+- **Configuration Management**: Centralized settings for all Eyes operations
+- **Server Communication**: Handles API interactions with Applitools services
+- **Data Structures**: Common models for regions, batches, and test results
+- **Visual Validation Primitives**: Base implementation for visual comparisons
+- **Universal SDK Integration**: Connects to the cross-platform Universal SDK
+- **Utility Functions**: Shared helpers for geometry, image processing, and more
+
+## Installation
+
+The `eyes_core` gem is automatically installed as a dependency when you install any of the specific Eyes SDK implementations. You typically don't need to install it directly.
+
+```ruby
+# Installing a specific SDK automatically includes eyes_core
+gem install eyes_selenium
+gem install eyes_images
+gem install eyes_capybara
+gem install eyes_appium
+
+# Or add to your Gemfile
+gem 'eyes_selenium'  # This will include eyes_core as a dependency
+```
+
+> **Note**: Direct installation of `eyes_core` is only needed if you're building a custom integration or extending the SDK functionality.
+
+## Core Components
+
+### EyesBase
+
+The `EyesBase` class is the foundation of all Eyes SDK implementations. It provides the core functionality for:
+
+- Opening and closing tests
+- Performing visual validations
+- Managing test configurations
+- Communicating with the Applitools server
+
+Key methods include:
+
+```ruby
+# Opening a test
+open_base(options = {})
+
+# Core validation method (used by specific implementations)
+check_window_base(region_provider, retry_timeout, match_window_data)
+
+# Closing a test and getting results
+close(throw_exception = true, be_silent = false)
+
+# Aborting a test
+abort_if_not_closed
+```
+
+### Configuration
+
+The `EyesBaseConfiguration` class manages all test settings. Key configurations include:
+
+```ruby
+# Basic test information
+config.app_name = "My Application"
+config.test_name = "My Test"
+config.viewport_size = Applitools::RectangleSize.new(1024, 768)
+
+# Authentication
+config.api_key = "YOUR_API_KEY"
+config.server_url = "https://eyesapi.applitools.com" # Default server
+
+# Test organization
+config.batch = Applitools::BatchInfo.new("My Batch")
+config.branch_name = "feature/branch"
+config.parent_branch_name = "master"
+
+# Match settings
+config.match_level = Applitools::MatchLevel::STRICT
+config.match_timeout = 5 # seconds
+config.ignore_caret = true
+config.ignore_displacements = false
+
+# Advanced features
+config.accessibility_validation = Applitools::AccessibilitySettings.new(
+  level: Applitools::AccessibilityLevel::AA,
+  guidelines_version: Applitools::AccessibilityGuidelinesVersion::WCAG_2_0
+)
+```
+
+The configuration system supports environment variables:
+- `APPLITOOLS_API_KEY` - Your API key
+- `APPLITOOLS_SERVER_URL` - The Applitools server URL
+- `APPLITOOLS_BRANCH` - Branch name for the test
+- `APPLITOOLS_PARENT_BRANCH` - Parent branch for baseline comparison
+- `APPLITOOLS_BASELINE_BRANCH` - Specific branch to use as baseline
+
+### Viewport Size
+
+The viewport size is defined using the `RectangleSize` class:
+
+```ruby
+viewport_size = Applitools::RectangleSize.new(width, height)
+```
+
+This class provides methods for manipulating and comparing sizes:
+
+```ruby
+size.width    # Get width
+size.height   # Get height
+size.empty?   # Check if width or height is zero
+size.to_hash  # Convert to a hash: {width: w, height: h}
+```
+
+### Batch Info
+
+The `BatchInfo` class groups test results for easier management:
+
+```ruby
+batch = Applitools::BatchInfo.new("My Batch Name")
+batch.id = "unique-batch-id"  # Optional, auto-generated if not provided
+batch.started_at = Time.now   # Optional, defaults to now
+```
+
+Batches with the same name and ID are grouped together in the Applitools dashboard.
+
+### Region
+
+The `Region` class represents a rectangular area for operations like:
+- Check specific parts of a page
+- Define ignore regions
+- Specify areas for accessibility checks
+
+```ruby
+region = Applitools::Region.new(left, top, width, height)
+
+# Operations
+region.contains?(location)   # Check if a point is inside the region
+region.intersect(other_region) # Get intersection of two regions
+region.empty?                # Check if the region has zero area
+```
+
+### Match Settings
+
+The `ImageMatchSettings` class controls how visual comparisons work:
+
+```ruby
+settings = Applitools::ImageMatchSettings.new
+settings.match_level = Applitools::MatchLevel::STRICT
+settings.ignore_caret = true
+settings.ignore_displacements = false
+```
+
+Match levels include:
+- `NONE` - No comparison (screenshot only)
+- `LAYOUT` - Compare layout structure
+- `CONTENT` - Compare textual content
+- `STRICT` - Compare visually with some tolerance (default)
+- `EXACT` - Pixel-perfect comparison
+
+## Universal SDK Integration
+
+The `eyes_core` gem integrates with the cross-language Universal SDK through several components:
+
+- `UniversalEyes` - Manages the session lifecycle and visual checks
+- `UniversalClient` - Handles communication with the Universal SDK
+- `UniversalCheckSettings` - Configures check operations
+- `UniversalServerControl` - Manages the Universal SDK process
+
+This integration provides:
+- Consistent behavior across language SDKs
+- Improved performance and reliability
+- Access to advanced features
+
+```ruby
+# The UniversalEyes class provides methods like:
+universal_eyes.check(check_settings, image_target)
+universal_eyes.close
+universal_eyes.abort
+```
+
+
+## Error Handling
+
+The SDK defines several error classes:
+
+- `EyesError` - Base class for all errors
+- `TestFailedError` - Test did not match the baseline
+- `DiffsFoundError` - Differences found during comparison
+- `NewTestError` - First run of a test with no baseline 
+
+```ruby
+begin
+  # Eyes operations
+  eyes.close
+rescue Applitools::NewTestError => e
+  puts "New test (no baseline): #{e.message}"
+  puts "See results at: #{e.test_results.url}"
+rescue Applitools::DiffsFoundError => e
+  puts "Found differences: #{e.message}"
+  puts "See results at: #{e.test_results.url}"
+rescue Applitools::TestFailedError => e
+  puts "Test failed: #{e.message}"
+rescue Applitools::EyesError => e
+  puts "Eyes error: #{e.message}"
+end
+```
+
+## Advanced Features
+
+### Accessibility Testing
+
+The SDK supports automated accessibility testing:
+
+```ruby
+# Configure accessibility testing
+config.accessibility_validation = Applitools::AccessibilitySettings.new(
+  level: Applitools::AccessibilityLevel::AA,
+  guidelines_version: Applitools::AccessibilityGuidelinesVersion::WCAG_2_1
+)
+
+# Add specific regions for accessibility checks
+check_settings.accessibility_region(
+  region, 
+  Applitools::AccessibilityRegionType::REGULAR_TEXT
+)
+```
+
+Accessibility levels:
+- `AA` - WCAG AA standard
+- `AAA` - WCAG AAA standard
+
+Guidelines versions:
+- `WCAG_2_0` - Web Content Accessibility Guidelines 2.0
+- `WCAG_2_1` - Web Content Accessibility Guidelines 2.1
+
+### Layout Breakpoints
+
+The SDK supports responsive design testing with layout breakpoints:
+
+```ruby
+# Enable automatic breakpoints
+config.layout_breakpoints = true
+
+# Specify exact breakpoint widths (in pixels)
+config.layout_breakpoints = [768, 1024, 1440]
+
+# Advanced configuration
+config.layout_breakpoints(
+  [768, 1024, 1440],  # Width breakpoints
+  reload: true,        # Reload page at each breakpoint
+  height_breakpoints: [600, 900]  # Height breakpoints
+)
+```
+
+### Proxy Configuration
+
+For environments that require a proxy to access the internet:
+
+```ruby
+# Basic proxy configuration
+config.proxy = Applitools::Connectivity::Proxy.new('http://proxy-address:port')
+
+# Proxy with authentication
+config.proxy = Applitools::Connectivity::Proxy.new(
+  'http://proxy-address:port',
+  'username',
+  'password'
+)
+
+# Alternative syntax
+config.set_proxy('http://proxy-address:port', 'username', 'password')
+```
+
+## Best Practices
+
+1. **Configuration Management**
+   - Create a base configuration that's shared across tests
+   - Override specific settings for individual tests as needed
+   - Use environment variables for deployment-specific settings
+
+2. **Batch Organization**
+   - Group related tests in the same batch
+   - Use descriptive batch names
+   - Consider using consistent batch IDs for CI/CD pipelines
+
+3. **Error Handling**
+   - Always wrap Eyes operations in try/catch blocks
+   - Handle different error types appropriately
+   - Decide on a strategy for handling new tests vs. failing tests
+
+4. **Resource Management**
+   - Always call `close` or `abort_if_not_closed` to release resources
+   - Use `abort_if_not_closed` in ensure blocks to prevent resource leaks
+
+5. **Performance Optimization**
+   - Only check what's necessary (specific regions when possible)
+   - Use the appropriate match level for each test
+   - Leverage batching to improve efficiency
+
+## Troubleshooting
+
+### Common Issues
+
+1. **API Key Errors**
+   - Ensure your API key is set correctly
+   - Check environment variables are properly configured
+   - Verify the API key has permissions for the server you're using
+
+2. **Connection Issues**
+   - Check network connectivity to Applitools servers
+   - Verify proxy settings if applicable
+   - Check server URL if using a private cloud
+
+3. **Match Level Problems**
+   - If getting too many false differences, consider using a less strict match level
+   - If missing important differences, use a stricter match level
+
+4. **Performance Issues**
+   - Large or complex pages may have slower performance
+   - Consider checking specific regions instead of full page
+   - Optimize match timeout settings
+
+
+### Logging
+
+The SDK provides built-in logging:
+
+```ruby
+# Set log level
+Applitools::EyesLogger.log_handler = Logger.new(STDOUT)
+Applitools::EyesLogger.log_handler.level = Logger::DEBUG
+```
+
+Log levels:
+- `DEBUG` - Very verbose for troubleshooting
+- `INFO` - Normal operations (default)
+- `WARN` - Potential issues
+- `ERROR` - Operation failures
+
+## FAQ
+
+### Q: Is `eyes_core` meant to be used directly?
+A: No, the `eyes_core` gem provides core functionality for other Eyes SDK implementations like `eyes_selenium` or `eyes_images`. You should use those specific implementations instead.
+
+### Q: How do I set my API key?
+A: You can set your API key in any of these ways:
+- Via environment variable: `ENV['APPLITOOLS_API_KEY']='your_api_key'`
+- In your code: `config.api_key = 'your_api_key'`
+- In your configuration file (if applicable to your test framework)
+
+### Q: How do match levels affect visual testing?
+A: Match levels determine how strictly Eyes compares screenshots:
+- `EXACT`: Pixel-perfect matching (very strict)
+- `STRICT`: Default level, allows small differences
+- `CONTENT`: More lenient, focuses on content matching
+- `LAYOUT`: Most lenient, only checks layout structure
+
+### Q: What's the difference between `close` and `abort_if_not_closed`?
+A: `close` completes the test and reports results to the Applitools dashboard, while `abort_if_not_closed` terminates the test without reporting results. Use `abort_if_not_closed` in exception handling.
+
+### Q: How do I handle tests with no baseline?
+A: When running a test for the first time with no baseline, it will raise a `NewTestError`. You can:
+1. Catch this error and handle it (e.g., approve it automatically in certain environments)
+2. Pass `false` to the `throw_exception` parameter of `close` to prevent the exception
+3. Use `save_new_tests = true` in your configuration (default) to save new tests as baselines
+
+
+### Q: Can I use eyes_core with non-web applications?
+A: Yes, through specialized SDKs like `eyes_images` for image comparison or `eyes_appium` for mobile testing, which build on the core functionality provided by `eyes_core`.
+
+## License
+
+This SDK is distributed under the Applitools SDK License Agreement. See the [LICENSE](LICENSE) file for more details.
+
+**Important:** This SDK may be used solely for your personal, non-commercial purposes. For commercial use, please contact your Applitools representative or visit [applitools.com](https://applitools.com) to obtain a commercial license.

data/eyes_core.gemspec

@@ -14,11 +14,13 @@ Gem::Specification.new do |spec|
   spec.description   = "Don't use it directly, take a look at eyes_selenium, eyes_images or eyes_calabash gems instead."
   spec.summary       = 'Core of the Applitools Ruby SDK'
   spec.homepage      = 'https://www.applitools.com'
-  spec.license       = 'Applitools'
+  spec.license       = 'Proprietary'
 
   spec.files         = `git ls-files lib/applitools`.split($RS) + [
     'lib/require_utils.rb',
     'lib/eyes_core.rb',
+    'LICENSE',
+    'README.md',
     'CHANGELOG.md',
     'eyes_core.gemspec',
     'Rakefile',
@@ -38,13 +40,12 @@ Gem::Specification.new do |spec|
   spec.add_dependency 'colorize'
   spec.add_dependency 'websocket'
   spec.add_dependency 'sorted_set'
-  spec.add_dependency 'eyes_universal', "= 4.35.1"
+  spec.add_dependency 'eyes_universal', "= 4.49.0"
 
   spec.add_development_dependency 'bundler'
   spec.add_development_dependency 'rake'
   spec.add_development_dependency 'rspec', '>= 3'
   spec.add_development_dependency 'rubocop', '<= 0.46.0'
-  spec.add_development_dependency 'webdrivers', '~> 5.0'
 
   # Exclude debugging support on Travis CI, due to its incompatibility with jruby and older rubies.
   unless ENV['TRAVIS']

data/lib/applitools/core/app_output_with_screenshot.rb

@@ -7,8 +7,7 @@ module Applitools
     def initialize(app_output, screenshot, allow_empty_screenshot = false)
       raise Applitools::EyesIllegalArgument.new 'app_output is not kind of Applitools::AppOutput' unless
           app_output.is_a? Applitools::AppOutput
-      raise Applitools::EyesIllegalArgument.new 'screenshot is not kind of Applitools::EyesScreenshot' unless
-          allow_empty_screenshot || screenshot.is_a?(Applitools::EyesScreenshot)
+      # No type checking for screenshot since EyesScreenshot is removed
       @app_output = app_output
       @screenshot = screenshot
     end
@@ -25,4 +24,4 @@ module Applitools
       app_output.screenshot_url
     end
   end
-end
+end

data/lib/applitools/core/debug_screenshot_provider.rb

@@ -15,7 +15,9 @@ module Applitools
       case image
       when Applitools::Screenshot
         image.save(file_name_to_save(suffix)) if image.area > 0
-      when Applitools::EyesScreenshot
+      # EyesScreenshot class has been removed
+      # when responding to :image method, try to save the image
+      when -> (img) { img.respond_to?(:image) && img.image.respond_to?(:area) && img.image.respond_to?(:save) }
         image.image.save(file_name_to_save(suffix)) if image.image.area > 0
       # when String
       #   ::ChunkyPNG::Image.from_string(image).save(file_name_to_save(suffix))

data/lib/applitools/core/dynamic_region.rb

@@ -6,16 +6,46 @@ module Applitools
   class DynamicRegion < ::Applitools::Region
     attr_accessor :region_type
     def initialize(element, region_type)
-      super(element.location.x, element.location.y, element.size.width, element.size.height)
+      if element.is_a?(::Applitools::Region)
+        super(element.left, element.top, element.width, element.height)
+        self.padding = element.current_padding if element.current_padding
+      else
+        super(element.location.x, element.location.y, element.size.width, element.size.height)
+      end
       self.region_type = region_type
     end
 
     def to_hash
+      hash = {
+        region: {
+          x: left,
+          y: top,
+          width: width,
+          height: height
+        }
+      }
+      
+      # Type should always be an array
       if region_type
-        super.merge(type: region_type)
-      else
-        super
+        hash[:type] = region_type.is_a?(Array) ? region_type : [region_type]
+      end
+      
+      if current_padding && !current_padding.zero?
+        if padding_top == padding_right && padding_right == padding_bottom && padding_bottom == padding_left
+          # If all padding values are the same, use a single number
+          hash[:padding] = padding_top
+        else
+          # Otherwise, use an object with individual values
+          hash[:padding] = {
+            top: padding_top,
+            right: padding_right,
+            bottom: padding_bottom,
+            left: padding_left
+          }
+        end
       end
+      
+      hash
     end
 
     alias json_data to_hash

data/lib/applitools/core/eyes_base.rb

@@ -38,8 +38,9 @@ module Applitools
 
     USE_DEFAULT_TIMEOUT = -1
 
-    SCREENSHOT_AS_IS = Applitools::EyesScreenshot::COORDINATE_TYPES[:screenshot_as_is].freeze
-    CONTEXT_RELATIVE = Applitools::EyesScreenshot::COORDINATE_TYPES[:context_relative].freeze
+    # Define these constants directly since EyesScreenshot is removed
+    SCREENSHOT_AS_IS = :screenshot_as_is
+    CONTEXT_RELATIVE = :context_relative
 
     class << self
       def set_viewport_size(driver, viewport_size)
@@ -677,8 +678,8 @@ module Applitools
         return
       end
 
-      control = last_screenshot.intersected_region control, EyesScreenshot::COORDINATE_TYPES[:context_relative],
-        EyesScreenshot::COORDINATE_TYPES[:screenshot_as_is]
+      # Use constants defined at class level since EyesScreenshot is removed
+      control = last_screenshot.intersected_region control, CONTEXT_RELATIVE, SCREENSHOT_AS_IS
 
       if control.empty?
         logger.info "Ignoring '#{text}' out of bounds"

data/lib/applitools/core/eyes_base_configuration.rb

@@ -207,9 +207,11 @@ module Applitools
 
     # layoutBreakpoints?: boolean | number[]
     def layout_breakpoints=(value)
-      config_hash[:layout_breakpoints] = { breakpoints: value } if value === true || value === false
-      config_hash[:layout_breakpoints] = { breakpoints: value } if value.is_a?(Array) && value.all? {|v| v.is_a?(Numeric)}
-      if value.is_a?(Hash)
+      if value === true || value === false
+        config_hash[:layout_breakpoints] = { breakpoints: value }
+      elsif value.is_a?(Array) && value.all? {|v| v.is_a?(Numeric)}
+        config_hash[:layout_breakpoints] = { breakpoints: value }
+      elsif value.is_a?(Hash)
         if value.has_key?(:breakpoints) || value.has_key?('breakpoints')
           config_hash[:layout_breakpoints] = value
         else
@@ -217,8 +219,27 @@ module Applitools
         end
       end
     end
-    def layout_breakpoints
-      config_hash[:layout_breakpoints]
+
+    def layout_breakpoints(value = nil, reload: nil, height_breakpoints: nil)
+      if value.nil?
+        config_hash[:layout_breakpoints]
+      else
+        if value.is_a?(Hash)
+          # If it's already a hash, add our options if not present
+          # Need to check both symbol and string keys
+          value[:layout_breakpoints][:reload] = value[:reload] || value['reload'] || reload
+          value[:layout_breakpoints][:height_breakpoints] = value[:height_breakpoints] || value['height_breakpoints'] || height_breakpoints
+          self.layout_breakpoints = value
+        else
+          # For non-hash values, create a hash with all options
+          self.layout_breakpoints = {
+            breakpoints: value,
+            reload: reload,
+            height_breakpoints: height_breakpoints
+          }
+        end
+        self
+      end
     end
     collect_method :layout_breakpoints
 

data/lib/applitools/core/eyes_screenshot.rb

@@ -1,62 +1,14 @@
 # frozen_string_literal: true
 
+# Empty placeholder for backward compatibility
+# This class has been removed as its functionality is now handled by the Universal SDK
+
 module Applitools
+  # Empty placeholder class to maintain backward compatibility
   class EyesScreenshot
-    extend Forwardable
-    extend Applitools::Helpers
-
-    def_delegators 'Applitools::EyesLogger', :logger, :log_handler, :log_handler=
-    attr_accessor :image, :top_left_location
-    def_delegators '@image', :width, :height
-
     COORDINATE_TYPES = {
-      context_as_is: 'CONTEXT_AS_IS',
-      screenshot_as_is: 'SCREENSHOT_AS_IS',
-      context_relative: 'CONTEXT_RELATIVE'
+      context_relative: :context_relative,
+      screenshot_as_is: :screenshot_as_is
     }.freeze
-
-    def initialize(screenshot)
-      Applitools::ArgumentGuard.is_a? screenshot, 'screenshot', Applitools::Screenshot
-      self.image = screenshot
-    end
-
-    abstract_method :sub_screenshot, false
-    abstract_method :convert_location, false
-    abstract_method :location_in_screenshot, false
-    abstract_method :intersected_region, false
-
-    def sub_screenshots(regions, coordinate_type)
-      Applitools::ArgumentGuard.is_a? regions, 'regions', Enumerable
-      regions.map do |region|
-        sub_screenshot(region, coordinate_type, false, true)
-      end
-    end
-
-    def convert_region_location(region, from, to)
-      Applitools::ArgumentGuard.not_nil region, 'region'
-      Applitools::ArgumentGuard.is_a? region, 'region', Applitools::Region
-      if region.empty?
-        return region.dup.tap do |r|
-          r.left = 0
-          r.top = 0
-          r.width = 0
-          r.height = 0
-        end
-      end
-      Applitools::ArgumentGuard.not_nil from, 'from'
-      Applitools::ArgumentGuard.not_nil to, 'to'
-
-      updated_location = convert_location(region.location, from, to)
-      region.dup.tap do |r|
-        r.left = updated_location.x
-        r.top = updated_location.y
-      end
-    end
-
-    private
-
-    def image_region
-      Applitools::Region.new(0, 0, image.width, image.height)
-    end
   end
-end
+end

data/lib/applitools/core/image_match_settings.rb

@@ -94,20 +94,22 @@ module Applitools
       end
 
       def ==(other)
-        min_diff_intensity == other.min_diff_intensity &&
-          min_diff_width == other.min_diff_width &&
-          min_diff_height == other.min_diff_height &&
-          match_threshold == other.match_threshold
+        return false unless other.is_a?(self.class)
+        self.min_diff_intensity == other.min_diff_intensity &&
+          self.min_diff_width == other.min_diff_width &&
+          self.min_diff_height == other.min_diff_height &&
+          self.match_threshold == other.match_threshold
       end
 
       def to_hash
         {
-          minDiffIntensity: min_diff_intensity,
-          minDiffWidth: min_diff_width,
-          minDiffHeight: min_diff_height,
-          matchThreshold: match_threshold
+          minDiffIntensity: self.min_diff_intensity,
+          minDiffWidth: self.min_diff_width,
+          minDiffHeight: self.min_diff_height,
+          matchThreshold: self.match_threshold
         }
       end
+
     end
 
     # export type MatchSettings<TRegion> = {