Applitools Eyes Images SDK for Ruby

Gem Version

The Applitools Eyes Images SDK for Ruby enables visual testing of images from any source. Test screenshots, rendered images, or any visual content without requiring browser automation.

Table of Contents

  1. Overview
  2. Installation
  3. Key Components
  4. Basic Usage
  5. Advanced Features
  6. Configuration
  7. Best Practices
  8. Troubleshooting
  9. FAQ
  10. API Reference

Overview

The Applitools Eyes Images SDK enables you to perform visual testing on image files directly. Unlike other Applitools SDKs that work with web browsers or mobile devices, the Images SDK works with raw image data from any source.

Key Features

  • Direct Image Testing: Test images without browser or device automation
  • Multiple Image Sources: Support for files, byte arrays, base64, and image objects
  • Region-Based Testing: Focus on specific areas within images
  • Flexible Matching: Apply different match levels and comparison strategies
  • Dynamic Content Handling: Ignore or float regions with changing content
  • Test Organization: Group related tests with batch management
  • Framework Integration: Works with RSpec, Minitest, and other Ruby test frameworks

Common Use Cases

  • Testing generated PDFs, charts, or reports
  • Validating screenshots from desktop applications
  • Cross-platform UI consistency checks
  • Design mockup validation
  • Image processing pipeline testing

Installation

Add the SDK to your Gemfile:

gem 'eyes_images'

Or install it directly:

gem install eyes_images

Dependencies

The Eyes Images SDK has the following dependencies:

  • eyes_core - Core Applitools functionality
  • Ruby image handling libraries

Key Components

Eyes Class

Applitools::Images::Eyes is the main class for interacting with the Applitools Eyes service. It provides methods for initializing, configuring, and performing visual checks on images.

Target Class

Applitools::Images::Target defines what to capture during a check operation. It provides a fluent interface for specifying:

  • Image source (path, bytes, or image object)
  • Regions to check
  • Regions to ignore
  • Floating regions
  • Match levels

Image Class

The SDK works with several types of image representations:

  • File paths
  • Image bytes
  • Ruby image objects
  • Base64 encoded image strings

Basic Usage

Initializing Eyes

require 'eyes_images'

# Initialize the Eyes SDK
eyes = Applitools::Images::Eyes.new
eyes.api_key = 'YOUR_APPLITOOLS_API_KEY'

# Optional: Configure logging
eyes.log_handler = Logger.new(STDOUT)

Opening a Test

# Start the test
eyes.open(
  app_name: 'My Image App',
  test_name: 'Product Images Test'
)

Visual Validations

# Check an image from a file path
eyes.check_image(
  image_path: '/path/to/image.png',
  tag: 'Product Image'
)

# Check an image from bytes
image_bytes = File.read('/path/to/image.png', mode: 'rb')
eyes.check_image(
  image_bytes: image_bytes,
  tag: 'Product Image from Bytes'
)

# Check a specific region in an image
region = Applitools::Region.new(10, 20, 300, 150) # x, y, width, height
eyes.check_region(
  image_path: '/path/to/image.png',
  region: region,
  tag: 'Product Logo'
)

Closing a Test

# Close the test and get results
results = eyes.close(false)
puts "Test results: #{results}"

# Always include in an ensure block
ensure
  # If the test was not closed properly, abort it
  eyes.abort_if_not_closed

Advanced Features

Region-based Testing

Test specific regions within an image:

# Define a region
region = Applitools::Region.new(10, 20, 300, 200)  # x, y, width, height

# Check only that region
eyes.check_region(
  image_path: '/path/to/image.png',
  region: region,
  tag: 'Header region'
)

Target API

The Target API provides a fluent interface for more complex validations:

# Create a target from a file path
target = Applitools::Images::Target.path('/path/to/image.png')

# Create a target from image bytes
bytes = File.read('/path/to/image.png', mode: 'rb')
target = Applitools::Images::Target.bytes(bytes)

# Run the check
eyes.check('My image check', target)

Batch Testing

Group multiple tests into a batch for easier management and reporting:

# Create a batch
batch = Applitools::BatchInfo.new('Product Images Batch')
batch.id = 'unique-batch-id'  # Optional: Set a custom batch ID

# Assign batch to the Eyes instance
eyes.batch = batch

# Run multiple tests with this batch
eyes.open(app_name: 'My App', test_name: 'First Test')
eyes.check_image(image_path: '/path/to/image1.png', tag: 'Image 1')
eyes.close

# Another test in the same batch
eyes.open(app_name: 'My App', test_name: 'Second Test')
eyes.check_image(image_path: '/path/to/image2.png', tag: 'Image 2')
eyes.close

Match Levels

Set different strictness levels for visual comparisons:

# Set match level for the entire test
eyes.match_level = Applitools::MatchLevel::LAYOUT

# Set match level for a specific check using Target API
target = Applitools::Images::Target.path('/path/to/image.png')
  .match_level(Applitools::MatchLevel::CONTENT)
eyes.check('Content Match Level', target)

# Available match levels:
# - Applitools::MatchLevel::EXACT   # Pixel-perfect matching
# - Applitools::MatchLevel::STRICT  # Default, allows small differences
# - Applitools::MatchLevel::CONTENT # Ignores colors, checks content
# - Applitools::MatchLevel::LAYOUT  # Checks only layout structure
# - Applitools::MatchLevel::NONE    # No comparison, just captures image

Ignoring Regions

Specify regions to ignore during comparison:

# Using Target API with region object
ignore_region = Applitools::Region.new(50, 100, 200, 50)
target = Applitools::Images::Target.path('/path/to/image.png')
  .ignore(ignore_region)
eyes.check('Image with ignored region', target)

# Multiple ignore regions
target = Applitools::Images::Target.path('/path/to/image.png')
  .ignore(Applitools::Region.new(50, 100, 200, 50))
  .ignore(Applitools::Region.new(300, 200, 100, 100))
eyes.check('Image with multiple ignored regions', target)

Floating Regions

Floating regions allow elements to "float" or shift position within defined bounds:

# Define a floating region with offsets (max_left, max_up, max_right, max_down)
floating_region = Applitools::Region.new(10, 20, 300, 150)
target = Applitools::Images::Target.path('/path/to/image.png')
  .floating(floating_region, 10, 10, 10, 10)
eyes.check('Image with floating region', target)

Configuration

Test Configuration

# Set the viewport size (affects baseline selection)
eyes.viewport_size = Applitools::RectangleSize.new(1024, 768)

# Configure match settings
eyes.match_timeout = 5000  # milliseconds
eyes.match_level = Applitools::MatchLevel::STRICT

# Set server URL (for on-premise deployments)
eyes.server_url = 'https://eyes.mycompany.com'

# Set a proxy
eyes.proxy = Applitools::Connectivity::Proxy.new('http://proxy.company.com', 8080)

Batch Configuration

# Create a batch with name
batch = Applitools::BatchInfo.new('My Batch Name')

# Set batch sequence name for grouping batches
batch.sequence_name = 'Weekly Regression'

# Additional batch properties
batch.id = 'unique-id-for-batch'  # Custom ID for the batch
batch.add_property('Environment', 'Production')
batch.add_property('Branch', 'main')

# Assign to Eyes instance
eyes.batch = batch

Best Practices

  1. Consistent Image Sources

    • Ensure images are captured consistently (same resolution, format, etc.)
    • Use the same image processing library throughout your tests

  2. Efficient Region Selection

    • Test specific regions when possible instead of full images
    • Group related elements into logical regions

  3. Proper Error Handling

    • Always use try/finally blocks and call abort_if_not_closed()
    • Handle and log exceptions appropriately

  4. Batch Organization

    • Group related tests into meaningful batches
    • Use batch properties to add important metadata

  5. Match Level Selection

    • Use appropriate match levels based on content type
    • Consider using LAYOUT for dynamic text content
    • Consider using STRICT for logos and important branding elements

  6. Baseline Management

    • Establish good baseline images under controlled conditions
    • Review and update baselines when intended changes occur

  7. API Key Security

    • Store API keys in environment variables or secure configuration
    • Never hard-code API keys in source code

Troubleshooting

Common Issues

  1. Authentication Errors

    • Check that your API key is set correctly
    • Verify connectivity to the Applitools server

  2. Image Format Issues

    • Ensure the image is in a supported format (PNG, JPEG, etc.)
    • Check for corrupt or incomplete image files

  3. Region Validation Failures

    • Verify region coordinates are within the image bounds
    • Check that regions are properly defined (non-zero width/height)

  4. Baseline Mismatches

    • Review test results in the Applitools dashboard
    • Check for unexpected changes in image content/format
    • Verify environment settings affecting the images

  5. Performance Issues

    • Large images may take longer to process
    • Consider resizing very large images before testing
    • Check network connectivity to Applitools servers

Debugging Tips

  1. Enable verbose logging:

    eyes.log_handler = Logger.new(STDOUT)
eyes.log_handler.level = Logger::DEBUG

  2. Check the image path and accessibility:

    puts "File exists: #{File.exist?('/path/to/image.png')}"
puts "File size: #{File.size('/path/to/image.png')}"

  3. Verify region coordinates:

    region = Applitools::Region.new(x, y, width, height)
puts "Region: #{region.to_s}"

FAQ

Q: Can I use Eyes Images SDK to test screenshots from web applications?
A: Yes, you can capture screenshots using any method and then use the Eyes Images SDK to validate them.

Q: How do I handle dynamic content in images?
A: Use ignore regions for content that changes between tests, or use a more lenient match level like LAYOUT.

Q: Can I test images with different resolutions?
A: Yes, but be aware that differing resolutions may cause baseline mismatches. Consider resizing images to a standard resolution before testing.

Q: Is it possible to compare two images directly without using the Applitools service?
A: The SDK is designed to work with the Applitools service. For direct image comparison without Applitools, you would need to use separate image processing libraries.

Q: How can I test multiple images in sequence?
A: You can make multiple check_image calls within a single test session (between open and close), or you can group related images into a batch.

Q: Can I integrate this SDK with my existing test framework?
A: Yes, the SDK can be integrated with any Ruby test framework including RSpec, Cucumber, Minitest, etc.

Q: How do I handle images with varying content but same structure?
A: Use the LAYOUT match level which focuses on the structure of elements rather than their exact content.

API Reference

Applitools::Images::Eyes

Core methods:

  • initialize - Creates a new Eyes instance
  • open(options) - Starts a test session
  • check_image(options) - Checks a full image
  • check_region(options) - Checks a specific region in an image
  • check(tag, target) - Checks using the Target API
  • close(throw_exception = true) - Closes a test session
  • abort_if_not_closed - Aborts an open test

Configuration methods:

  • api_key= - Sets the Applitools API key
  • server_url= - Sets the Applitools server URL
  • proxy= - Sets the proxy configuration
  • match_level= - Sets the default match level
  • match_timeout= - Sets the match timeout
  • batch= - Sets the batch information
  • branch_name= - Sets the branch name
  • parent_branch_name= - Sets the parent branch name
  • viewport_size= - Sets the viewport size

Applitools::Images::Target

Factory methods:

  • Target.path(path) - Creates a target from an image file path
  • Target.bytes(image_bytes) - Creates a target from image bytes
  • Target.image(image) - Creates a target from an image object

Instance methods:

  • ignore(region) - Defines a region to ignore
  • floating(region, max_left, max_up, max_right, max_down) - Defines a floating region
  • match_level(match_level) - Sets the match level for this target
  • timeout(timeout_ms) - Sets the match timeout for this target

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.