Applitools Eyes Core SDK

Gem Version

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
  2. Installation
  3. Core Components
  4. Universal SDK Integration
  5. Error Handling
  6. Advanced Features
  7. Best Practices
  8. Troubleshooting
  9. 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.

# 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:

# 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:

# 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:

viewport_size = Applitools::RectangleSize.new(width, height)

This class provides methods for manipulating and comparing sizes:

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:

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
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:

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
# 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 
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:

# 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:

# 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:

# 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:

# 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 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 to obtain a commercial license.